WAIFU.IM is an easy to use api that allows you to get waifu pictures from an archive of over 4000 images and multiple tags!
https://api.waifu.im/
You can specify which version of the API you want to use by placing it in the Accept-Version header. If the value doesn't match any version the latest is used. We highly recommend you to use it since it will prevent your app to break if a new version with breaking change is developed. You can check which version you are using in the Version response header.
The latest version of the API is v4.
Note: this rate limit only apply for api.waifu.im domain.
The rate limit is 1 request every 200 milliseconds. If you go up to this value the request will be put in a queue (the size is 10) if the queue is full, the server will answer with a 429 status code.
You can check the Retry-After header to get the time to wait for (in seconds) before making another request.
I really recommend the Python users to use the wrapper, it fully supports the API and is updated when needed.
The image are classified with a tag system, it means that each image can have multiple tags!
There is versatile tags that can describe both safe and lewd images and specially nsfw tags that only describe lewd images.
Little tips, the default tag is waifu, you can find a list of available tags here or bellow.
Here is the json structure for the api errors.
{
"detail": "Description / Details"
}
You can either get completely random images or by tag.
PATH | Request type |
---|---|
/search/ | GET |
To filter by tag or by nsfw images please take a look at the query strings.
Here is an example response that you could get.
{
"images": [
{
"signature": "5f7e656343cb7be1",
"extension": ".jpg",
"image_id": 3284,
"favourites": 12,
"dominant_color": "#cac2c6",
"source": "https://www.pixiv.net/en/artworks/88563141",
"uploaded_at": "2021-11-02T11:16:19.048684+00:00",
"liked_at": null,
"is_nsfw": false,
"width": 2403,
"height": 4051,
"url": "https://cdn.waifu.im/3284.jpg",
"preview_url": "https://www.waifu.im/preview/3284/",
"tags": [
{
"tag_id": 12,
"name": "waifu",
"description": "A female anime/manga character.",
"is_nsfw": false
}
]
}
]
}
Name | Required | Type | Behaviour |
---|---|---|---|
included_tags | No | String Array | Force the API to return images with, at least all the provided tags |
excluded_tags | No | String Array | Force the API to return images without any of the provided tags |
is_nsfw | No | Strict Boolean or String | Force or exclude lewd files, only works if the included_tags aren't specially nsfw (see difference between versatile and nsfw tags above). You can provide 'null' to make it be random. Default to False. |
gif | No | Boolean | Force or prevent the API to return .gif files. |
order_by | No | String | You can choose to order the image by one of the following : FAVOURITES, UPLOADED_AT, RANDOM, default to RANDOM |
orientation | No | String | You can choose the orientation of your image using one of the following : LANDSCAPE, PORTRAIT |
many | No | Boolean | Return an array of 30 files if True. |
full | No | Boolean | Returns the full result without any limit (admins only) |
included_files | No | String Array | Force the api to provide only the included_files (image_id or signature). (logic defer from included_tags) |
excluded_files | No | String Array | Exclude the file(s) (image_id or signature). |
If you want to provide an array just provide the query string again, with a different value
Here is an python example with some query strings.
import aiohttp
# In this example aiohttp is used.
# This needs to be used in an async function.
# This is simply for demonstrative purposes, you can use
# any library for this.
# The only supported headers are User-Agent and Authorization
# Please change the user-agent as it's useful for identification purposes.
# This endpoint does not require a token but some others do.
HEADERS = {'Accept-Version':'v4', 'User-Agent': f'aiohttp/{aiohttp.__version__}; YourAppName'}
# Here let's say you want to exclude some images, disable gifs and request only safe pictures
# The url is written in multiple lines for readability purposes, but it is equal to:
# https://api.waifu.im/search/?excluded_files=3867126be8e260b5&excluded_files=3133&gif=false&excluded_tags=maid&excluded_tags=oppai&is_nsfw=false
# You can also provide params as a dict or a list of tuple with the 'params' kwarg
url = "https://api.waifu.im/search/?excluded_files=4401" \
"&excluded_files=3133" \
"&gif=false" \
"&excluded_tags=maid" \
"&excluded_tags=oppai" \
"&is_nsfw=false"
# Usually you would create a session and access it when needed.
session = aiohttp.ClientSession()
async with session.get(url, headers=HEADERS) as resp:
api = await resp.json()
if resp.status in {200, 201}:
url = api['images'][0]['url']
# Do whatever you want with the image url.
else:
error = api['detail']
# Do whatever you want with the error description.
This part isn't directly related to the API and the base url is not the same. This will allow you to generate a link asking a user that will click on it, permissions over his account (you also can do the opposite with revoke).
This will be useful if you want to use the user_id query string when dealing with favourites.
URI | Request type |
---|---|
https://www.waifu.im/authorization/ | GET |
https://www.waifu.im/authorization/revoke/ | GET |
Name | Required | Type | Behaviour |
---|---|---|---|
user_id | Yes | Integer | The discord user_id of the user that will receive the permissions |
permissions | Yes | String Array | The permissions that will be asked for. Available permissions are 'view_favourites' and 'manage_favourites' |
If you want to provide an array just provide the query string again, with a different value
You can create a personal gallery composed of your favorite images, for you to be able to look them whenever you want through the website or the bot, but you can also use the api to retrieve your favourite pictures, here is how to do it.
PATH | Request type |
---|---|
/fav/ | GET |
You will need to place your token in the Authorization header, see the example.
{
"images": [
{
"signature": "5f7e656343cb7be1",
"extension": ".jpg",
"image_id": 3284,
"favourites": 12,
"dominant_color": "#cac2c6",
"source": "https://www.pixiv.net/en/artworks/88563141",
"uploaded_at": "2021-11-02T11:16:19.048684+01:00",
"liked_at" : "2021-12-02T11:14:32.038284+01:00"
"is_nsfw": false,
"width": 2403,
"height": 4051,
"url": "https://cdn.waifu.im/3284.jpg",
"preview_url": "https://www.waifu.im/preview/3284/",
"tags": [
{
"tag_id": 12,
"name": "waifu",
"description": "A female anime/manga character.",
"is_nsfw": false
}
]
}
]
}
Name | Required | Type | Behaviour |
---|---|---|---|
user_id | No | Integer | The discord user id from which you want to consult the favourites (only if the provided user granted you the permission). |
included_tags | No | String Array | Force the API to return images with, at least all the provided tags |
excluded_tags | No | String Array | Force the API to return images without any of the provided tags |
is_nsfw | No | Strict Boolean or String | Force or exclude lewd files, only works if the included_tags aren't specially nsfw (see difference between versatile and nsfw tags above). You can provide 'null' to make it be random. Default to 'null'. |
gif | No | Boolean | Force or prevent the API to return .gif files. |
order_by | No | String | You can choose to order the image by one of the following : FAVOURITES, UPLOADED_AT, LIKED_AT, RANDOM, default to LIKED_AT |
orientation | No | String | You can choose the orientation of your image using one of the following : LANDSCAPE, PORTRAIT |
many | No | Boolean | Return an array of 30 files if True. |
included_files | No | String Array | Force the api to provide only the included_files (image_id or signature). (logic defer from included_tags) |
excluded_files | No | String Array | Exclude the file(s) (image_id or signature). |
If you want to provide an array just provide the query string again, with a different value
Here is a little example. Here let's say we want to get all the safe images with the waifu tag programmatically (even thought we could use included_tags query string). We also tell the api to returns only landscape pictures.
import aiohttp
token="eyJpZCI6NTA4MzQ2OTc4Mjg4MjcxMzYwLCJzZWNyZXQiOiJyb3AtekZIeE12bll4ZyJ9.89aLylZeRcIcYDjfg6E01iPRCqI"
# Please do change the user agent, it's useful for identification purpose.
headers= {'Accept-Version':'v4', 'User-Agent':f'aiohttp/{aiohttp.__version__}; YourAppName','Authorization':f"Bearer {token}"}
def has_waifu_tag(image):
for t in image["tags"]:
return t["name"] == "waifu" and not image["is_nsfw"]
# Do not open a new session everytime like here, save it
async with aiohttp.ClientSession() as cs:
# In this example we get all the picture with a landscape orientation in the user favourites
async with cs.get(f"https://api.waifu.im/fav?orientation=LANDSCAPE",headers=headers) as rep:
api = await rep.json()
if rep.status in {200, 201}:
# The filter() function extracts elements from an iterable (list, tuple etc.) for which a function returns True
waifu = list(filter(has_waifu_tag,rep["images"]))
# Do whatever you want with the waifu tag pictures.
# As mentioned before we could just have add '&included_tags=waifu'
else:
error = api["detail"]
#do whatever you want with the error message.
Previously you saw how to consult your favourite pictures, now let's see how you can edit it.
You can delete a picture, insert it or toggle it, it means that the picture will be deleted from the user favourites if it already was in, otherwise it will be added to it.
PATH | Request type |
---|---|
/fav/insert | POST |
/fav/delete | DELETE |
/fav/toggle | POST |
As previously, you will need to place your token in the Authorization header.
For insert and delete route, the API will return a 204 status code. Let's see the structure for the toggle route.
{
"state": "DELETED" or "INSERTED" depending on the action done
}
Name | Required | Type | Behaviour |
---|---|---|---|
user_id | No | Integer | The discord user id from which you want to edit the favourites (only if the provided user granted you the permission). |
image_id | Yes | Integer | The id (only) of the image that you want to add, remove or toggle from the user favourites. |