API Documentation

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!

API Base URL

https://api.waifu.im/

Interactive Documentation

You can also use the interactive documentation here.

Rate Limit

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.

Github & Python Wrapper

I really recommend the Python users to use the wrapper, it fully supports the API and is updated when needed.

Github
Python wrapper

Tags

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.

Errors

Here is the json structure for the api errors.



All errors apart of 422 status code
Its recommended to handle them.

{
  "detail": "Description / Details"
}

The bellow json structure is the one for a 422 status code.
It means the provided arguments couldn't be validated (type issue etc).
This is just about the parameters validation so you will never face this error if you provided the arguments correctly.

{
  "detail": [
    {
      "loc": [
        "location of the argument (query, path etc...)",
        "name of argument"
      ],
      "msg": "description of the issue",
      "type": "type of the argument"
    }
  ]
}
      

Get Random Images

You can either get completely random images or by tag.

PATH Request type
/random/ GET

To filter by tag or by nsfw images please take a look at the query strings.

Response

Here is an example response that you could get.


{
  "images": [
    {
      "file": "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",
      "is_nsfw": false,
      "width": 2403,
      "height": 4051,
      "url": "https://cdn.waifu.im/5f7e656343cb7be1.jpg",
      "preview_url": "https://waifu.im/preview/5f7e656343cb7be1/",
      "tags": [
        {
          "tag_id": 12,
          "name": "waifu",
          "description": "A female anime/manga character.",
          "is_nsfw": false
        }
      ]
    }
  ]
}
				

Query strings

Name Required Type Behaviour
selected_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 selected_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
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)
excluded_files No String Array Exclude the file(s). You can or not provide the file extension.

If you want to provide an array just provide the query string again, with a different value

Example

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 = {'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/random/?excluded_files=3867126be8e260b5.jpeg&excluded_files=ca52928d43b30d6a&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/random/?excluded_files=3867126be8e260b5.jpeg" \
      "&excluded_files=ca52928d43b30d6a" \
      "&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.
      

Generate an Authorization Link

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://waifu.im/authorization/ GET
https://waifu.im/authorization/revoke/ GET

Query strings

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

Favourites

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.

Response


{
  "images": [
    {
      "file": "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",
      "is_nsfw": false,
      "width": 2403,
      "height": 4051,
      "url": "https://cdn.waifu.im/5f7e656343cb7be1.jpg",
      "preview_url": "https://waifu.im/preview/5f7e656343cb7be1/",
      "tags": [
        {
          "tag_id": 12,
          "name": "waifu",
          "description": "A female anime/manga character.",
          "is_nsfw": false
        }
      ]
    }
  ]
}
                

Query strings

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).
selected_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 selected_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
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.
excluded_files No String Array Exclude the file(s). You can or not provide the file extension.

If you want to provide an array just provide the query string again, with a different value

Example

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 selected_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= {'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 '&selected_tags=waifu'
	
		else:
			error = api["detail"]
			#do whatever you want with the error message.
			

Edit Favourites

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.

Response

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
}
                

Query strings

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 Yes String The image that you want to add, remove or toggle from the user favourites.

Get Images Information

PATH Request type
/info/ GET

Response

The Json structure has been thought so that it will often be the same, therefore the structure is the same as the random images one.

Query strings

Name Required Type Behaviour
images Yes String Array The image(s) that you want information from.

If you want to provide an array just provide the query string again, with a different value