Search

Search images.

GET https://api.waifu.im/search

Retrieves images randomly or by tag based on the specified search criteria.

Query Parameters

Name	Type	Description
included_tags	array[string]	Force the API to return images with at least all the provided tags.
excluded_tags	array[string]	Force the API to return images without any of the provided tags.
included_files	array[string]	Force the API to provide only the specified file IDs or signatures.
excluded_files	array[string]	Force the API to not list the specified file IDs or signatures.
is_nsfw	string	Force or exclude lewd files (only works if included_tags only contain versatile tags and no nsfw only tag). You can provide 'null' to make it random.
gif	boolean	Force or prevent the API to return .gif files.
order_by	string	Ordering criteria for the images.
orientation	string	Image orientation criteria.
limit	integer	Return an array of the number provided. A value greater than 30 requires admin permissions. Default is 1.
full	boolean	Returns the full result without any limit (admins only).
width	string	Filter images by width (in pixels). Accepted operators: <=, >=, >, <, !=, =
height	string	Filter images by height (in pixels). Accepted operators: <=, >=, >, <, !=, =
byte_size	string	Filter images by byte size. Accepted operators: <=, >=, >, <, !=, =

Headers

Name	Type	Description
Authorization	string	Bearer followed by a space and your token

200: OK

{
  "images": [
    {
      "artist": {
        "artist_id": 1,
        "deviant_art": "https://www.deviantart.com/4thwallzart",
        "name": "fourthwallzart",
        "patreon": "string",
        "pixiv": "string",
        "twitter": "https://twitter.com/4thWallzArt"
      },
      "byte_size": 3299586,
      "dominant_color": "#bbb7b2",
      "extension": ".png",
      "favorites": 1,
      "height": 2304,
      "image_id": 8108,
      "is_nsfw": false,
      "liked_at": "string",
      "preview_url": "https://www.waifu.im/preview/8108/",
      "signature": "58e6f0372364abda",
      "source": "https://www.patreon.com/posts/persephone-78224476",
      "tags": [
        {
          "description": "A female anime/manga character.",
          "is_nsfw": false,
          "name": "waifu",
          "tag_id": 12
        }
      ],
      "uploaded_at": "2023-05-03T18:40:04.381354+02:00",
      "url": "https://cdn.waifu.im/8108.png",
      "width": 1536
    }
  ]
}

400: Bad Request

{"detail":"Bad Request"}

401: Unauthorized

{"detail":"Unauthorized"}

403: Forbidden

{"detail":"Forbidden"}

404: Not Found

{"detail":"Not Found"}

500: Internal Server Error

{"detail":"Internal Server Error"}

Here is an example to get a random image with the maid tag with an height superior or equal to 2000 pixels:

Curl

curl -X GET \
  'https://api.waifu.im/search?included_tags=maid&height=>=2000' \
  -H 'Content-Type: application/json'

Python

import requests

url = 'https://api.waifu.im/search'
params = {
    'included_tags': ['maid'],
    'height': '>=2000'
}

response = requests.get(url, params=params)

if response.status_code == 200:
    data = response.json()
    # Process the response data as needed
else:
    print('Request failed with status code:', response.status_code)

Javascript

const apiUrl = 'https://api.waifu.im/search';  // Replace with the actual API endpoint URL
const params = {
  included_tags: 'maid',
  height: '>=2000'
};

const queryParams = new URLSearchParams();

for (const key in params) {
  if (Array.isArray(params[key])) {
    params[key].forEach(value => {
      queryParams.append(key, value);
    });
  } else {
    queryParams.set(key, params[key]);
  }
}
const requestUrl = `${apiUrl}?${queryParams.toString()}`;

fetch(requestUrl)
  .then(response => {
    if (response.ok) {
      return response.json();
    } else {
      throw new Error('Request failed with status code: ' + response.status);
    }
  })
  .then(data => {
    // Process the response data as needed
    console.log(data);
  })
  .catch(error => {
    console.error('An error occurred:', error.message);
  });