Python 3
The anime-api library is an officially supported Python 3 wrapper for Nekos API.
Source code: GitHub
Installation
The anime-api library can be installed on Python 3.7 and higher using pip, Poetry or Conda.
pip install anime-apiUsage
The anime-api library contains lots of wrappers for different APIs, but we'll focus on the NekosAPI() class. You can import it from the anime_api.apis module.
from anime_api.apis import NekosAPI
nekos = NekosAPI()Get a random image
The NekosAPI() class has a get_random_image() method that returns a random image.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# This will return up to 10 images with the `kemonomimi` category
image = nekos.get_random_image(categories=["kemonomimi"])
print(image.url)You can also get many images (up to 25) at once using the get_random_images() method instead.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# The categories argument is optional. If not specified, the images will be
# completely random (no specific category)
images = nekos.get_random_images(limit=10, categories=["kemonomimi"])
for image in images:
print(image.url)Get an image by it's ID
Every image in the API has its own ID. You can fetch an image by its ID to get a specific image's information.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
image_id = "some-uuid"
image = nekos.get_image_by_id(image_id=image_id)
assert image.id == image_id
print(image.url)Search for an artist
If you want to search for an artist, you can use the get_artists() method.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# This will return up to 10 artists and skip the first 5. By default the limit
# is set to 10 and the offset is set to 0. The search argument is optional. If
# you don't specify it, a list of all artists available will be returned
# instead. Search is case-insensitive.
artists = nekos.get_artists(limit=10, offset=0, search="%?shiren%?")
for artist in artists:
print(artist.name)The search query format is explained here. You can also learn to escape queries here.
Get an artist by it's ID
Each artist in the API has its ID. Although every image comes with (almost) all its artist information, fetching an artist by its ID has its advantages.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
artist_id = "some-uuid"
artist = nekos.get_artist_by_id(artist_id=artist_id)
assert artist.id == artist_id
print(artist.images)As you can see, the images property is added to the Artist object when it's fetched by ID. This is not the case if the artist is fetched using a different method.
Get all artist's images
If you want to fetch an artist's images, you can use the get_images_by_artist_id() method. This method returns up to 25 images and supports pagination.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# This will return up to 10 images from arist with "some-uuid" as ID and skip
# the first 5. By default the limit is set to 10 and the offset is set to 0.
images = nekos.get_images_by_artist_id(artist_id="some-uuid", limit=10, offset=5)
for image in images:
print(image.artist.name)Search for a category
To search for a category, you can use the get_categories() method.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# This will return up to 10 categories and skip the first 5. By default the
# limit is set to 10 and the offset is set to 0. The search argument is optional. If
# you don't specify it, a list of all artists available will be returned
# instead. Search is case-insensitive.
categories = nekos.get_categories(limit=10, offset=0, search="%?catgi%?")
for category in categories:
print(category)The search query format is explained here. You can also learn to escape queries here.
Get a category by it's ID
All categories have their unique ID, which is always returned together with the category. You can get a specific category using the get_gategory_by_id() method.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
category_id = "some-uuid"
category = nekos.get_category_by_id(category_id=category_id)
assert category.id == category_id
print(category.name)Search for a character
To search for a character, you can use the get_characters().
from anime_api.apis import NekosAPI
nekos = NekosAPI()
# This will return up to 10 characters and skip the first 5. By default the
# limit is set to 10 and the offset is set to 0. The search argument is optional. If
# you don't specify it, a list of all artists available will be returned
# instead. Search is case-insensitive.
characters = nekos.get_characters(limit=10, offset=0, search="%?kaguya%?")
for character in characters:
print(character)The search query format is explained here. You can also learn to escape queries here.
Get a character by it's ID
Every character has it's unique ID, which is returned together with the character in every API response. You can get a specific charcater's information using the get_character_by_id() method.
from anime_api.apis import NekosAPI
nekos = NekosAPI()
character_id = "some-uuid"
character = nekos.get_character_by_id(character_id=character_id)
assert character.id == character_id
print(character.name)Helpers
Escape a search query
Sometimes you might want to make a query that contains special characters like [ or *.
from anime_api.apis.nekos_api import NekosAPI, EscapedQuery
nekos = NekosAPI()
escaped_query = EscapedQuery("`[` or `]` or maybe `*`?")
characters = nekos.get_characters(search=escaped_query)
for character in characters:
print(character.name)Using the EscapedQuery() class, you can easily escape special characters to use them as literals.
This is what actually happens undercover:
>>> from anime_api.apis.nekos_api import EscapedQuery
>>>
>>> query = "`[` or `]` or maybe `*`?"
>>> escaped = EscapedQuery(query)
>>>
>>> str(escaped)
`\\[` or `\\]` or maybe `\\*`\\?This way, you can search for special characters without any problems. If you wanted, you could also use f-strings to make even more complex queries. For example:
from anime_api.apis.nekos_api import NekosAPI, EscapedQuery
nekos = NekosAPI()
query = f"({EscapedQuery('[ and ]')}) | ({EscapedQuery('{ and }')})"
characters = nekos.get_characters(search=query)
for character in characters:
print(character.name)This way, you'd be matching characters that contain either [ and ] or { and }.
Reference
Wrapper Class
NekosAPI: GitHub
Objects
Types
Helpers
EscapedQuery: GitHub