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!

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.

• VERSATILE
• NSFW

Errors

Here is the json structure for the api errors.

{
  "detail": "Description / Details"
}
                    

Search Images

You can either get completely random images or by tag.

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": [
    {
      "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
        }
      ]
    }
  ]
}
				    

Query strings

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 = {'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.
                    

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.

Query strings

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.

You will need to place your token in the Authorization header, see the example.

Response

{
  "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
        }
      ]
    }
  ]
}
                    

Query strings

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 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.
			        

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.

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
}
                    

Fields