Comment on page
Search

get
https://api.waifu.im/
search
Search images.
Retrieves images randomly or by tag based on the specified search criteria.
Parameters
Query
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.
many
boolean
Return an array of 30 files if true.
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: <=, >=, >, <, !=, =
Header
Authorization
string
Bearer followed by a space and your token
Responses
200: OK
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: 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
Python
Javascript
curl -X GET \
  'https://api.waifu.im/search?included_tags=maid&height=>=2000' \
  -H 'Content-Type: application/json'
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)
​
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(params);
const requestUrl = `${apiUrl}?${queryParams}`;
​
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);
  });
​