anipics 2.0.0

Simple module to get anime pictures

PyPI | GitHub Releases | Examples

🌸 About

Anipics wraps several anime image services behind a small sync and async API. It is designed for bots, small apps, scripts, and experiments where you just want a clean url or typed metadata without hand-writing HTTP calls for every provider.

📦 Installation

uv add anipics

pip install anipics

🚀 Quick Start

from anipics import NekosAPI, WaifuIm

waifu = WaifuIm().get(WaifuIm.Types.waifu)
print(waifu.url)

image = NekosAPI().get_random_image(tags=[NekosAPI.Types.girl])
print(image.id, image.url)

Async usage follows the same shape:

import asyncio

from anipics import Nekosia


async def main() -> None:
    image = await Nekosia().async_get(Nekosia.Types.catgirl)
    print(image.url)


asyncio.run(main())

More examples live in examples/. ✨

🧩 Services

Service	Best for	Extras
NekosAPI	🖼️ Random images and browsable metadata	Typed image metadata models
NekosBest	🎬 Reactions, GIFs, waifu/neko/kitsune images	Endpoint discovery
Nekosia	🏷️ Tag/category based anime images	Documented main categories and tag lookup
NekosLife	🌙 Classic neko/waifu/avatar style endpoints	Simple URL result API
PurrBot	⚡ SFW and NSFW gif/image endpoints	v2 API paths
WaifuIm	🎀 Waifu images with include/exclude filters	Tag lookup and NSFW filter options

✨ Typed Metadata

Most simple calls return Models.Result with a url field:

from anipics import PurrBot

result = PurrBot().get(PurrBot.Types.SFW.GIF.neko)
print(result.url)

NekosAPI metadata calls return typed Pydantic models:

from anipics import NekosAPI

image = NekosAPI().get_random_image(tags=[NekosAPI.Types.neko])

print(image.id)
print(image.url)
print(image.rating)
print(image.tags)

🛠️ Development

uv sync
uv run scripts/format.py
uv run scripts/test.py

Live tests call external services and are kept separate from the default test command:

uv run scripts/live_test.py

Build the package with:

uv build

📜 License

Anipics is distributed under the AGPL-3.0 license.