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

Images are classified by a tag system and can have multiple tags!

There are versatile tags that can describe both safe and lewd images and specially nsfw tags that only describe lewd images.

If no tag filtering is requested, the default tag, waifu, will be included. You can find a list of available tags here or below.

• VERSATILE
• NSFW

To get more information about the tags please take a look at the query strings.

Query strings

Errors

Example JSON response of an API error.

{
  "detail": "Description / Details"
}
                    

Search Images

You can get images randomly or by tag

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

Response

Example JSON response of a /search call

{
  "images": [
    {
      "signature": "5f7e656343cb7be1",
      "extension": ".jpg",
      "image_id": 3284,
      "favorites": 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

To take in an array of values, provide the query string again with different values

Python search example

A 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':'v5', '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 Waifu.im 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 favorites.

Query strings

To take in an array of values, provide the query string again with different values

Favorites

You can create your own gallery composed of your favorite images that you can look at conveniently. You can access your favorite images through the website or our Discord bot. You can also use the API directly to access your favorites (see below).

This requires a token and you will need to place it in the Authorization header, see an example here.

Response

Example JSON response of a /fav call

{
  "images": [
    {
      "signature": "5f7e656343cb7be1",
      "extension": ".jpg",
      "image_id": 3284,
      "favorites": 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

To take in an array of values, provide the query string again with different values

Python favorite example

In this example 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':'v5', '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 favorites
	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.