Favorites

Get your favorites

By default, this endpoint returns all images in the user favorites, meaning it will also returns lewd images if there are some in the user favorites.

Get your favorites.

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

Requires

view_favorites

permission.

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.
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: <=, >=, >, <, !=, =

Headers

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

200: OK

{
  "images": [
    {
      "signature": "85d7aa55941c7087",
      "extension": ".jpg",
      "image_id": 7622,
      "favorites": 3,
      "dominant_color": "#dfcdc5",
      "source": "https://www.pixiv.net/en/artworks/95981691",
      "artist": {
        "artist_id": 54,
        "name": "大熊まい",
        "patreon": null,
        "pixiv": "https://www.pixiv.net/users/29449",
        "twitter": "https://twitter.com/m_okuma0831",
        "deviant_art": null
      },
      "uploaded_at": "2022-04-07T13:51:47.979181Z",
      "liked_at": "2022-04-07T14:07:46.455245Z",
      "is_nsfw": false,
      "width": 1406,
      "height": 1875,
      "byte_size": 1538007,
      "url": "https://cdn.waifu.im/7622.jpg",
      "preview_url": "https://www.waifu.im/preview/7622/",
      "tags": [
        {
          "tag_id": 12,
          "name": "waifu",
          "description": "A female anime/manga character.",
          "is_nsfw": false
        }
      ]
    }
  ]
}

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 your favorites:

Curl

curl -X GET \
  'https://api.waifu.im/fav' \
  -H 'Accept-Version: v5' \
  -H 'Authorization: Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0'

Python

import requests

url = 'https://api.waifu.im/fav'

headers = {
    'Accept-Version': 'v5',
    'Authorization': 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0',
}

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

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/fav';

const headers = new Headers();
headers.append('Accept-Version', 'v5');
headers.append('Authorization', 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0');

fetch(apiUrl, { headers })
  .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);
  });

Manage your favorites

Inserts an image into the user

POST https://api.waifu.im/fav/insert

Requires

manage_favorites

permission.

Headers

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

Request Body

Name	Type	Description
image_id*	integer	The ID of the image to insert.
user_id	integer	The user ID of the user whose favorites you want to edit.

200: OK

{"state":"INSERTED"}

400: Bad Request

{"detail":"Bad Request"}

401: Unauthorized

{"detail":"Unauthorized"}

403: Forbidden

{"detail":"Forbidden"}

404: Not Found

{"detail":"Not Found"}

409: Conflict

{"detail":"The image you provided is already in the user favorites, consider using /fav/toggle instead."}

500: Internal Server Error

{"detail":"Internal Server Error"}

Here is an example to insert the image ID 8008 into your favorites:

Curl

curl -X POST \
  'https://api.waifu.im/fav/insert' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Version: v5' \
  -H 'Authorization: Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0' \
  -d '{
    "image_id": 8008
  }'

Python

import requests

url = 'https://api.waifu.im/fav/insert'

headers = {
    'Accept-Version': 'v5',
    'Authorization': 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0',
    'Content-Type': 'application/json',
}

data = {
    'image_id': 8008
}

response = requests.post(url, headers=headers, json=data)

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/fav/insert';

const headers = new Headers();
headers.append('Accept-Version', 'v5');
headers.append('Authorization', 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0');
headers.append('Content-Type', 'application/json');

const data = {
  image_id: 8008
};

fetch(apiUrl, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
  .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);
  });

Removes an image from the user

POST https://api.waifu.im/fav/delete

Requires

manage_favorites

permission.

Headers

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

Request Body

Name	Type	Description
image_id*	integer	The ID of the image to remove.
user_id	integer	The user ID of the user whose favorites you want to edit.

200: OK

{"state":"DELETED"}

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 remove the image ID 8008 from your favorites:

Curl

curl -X POST \
  'https://api.waifu.im/fav/delete' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Version: v5' \
  -H 'Authorization: Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0' \
  -d '{
    "image_id": 8008
  }'

Python

import requests

url = 'https://api.waifu.im/fav/delete'

headers = {
    'Accept-Version': 'v5',
    'Authorization': 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0',
    'Content-Type': 'application/json',
}

data = {
    'image_id': 8008
}

response = requests.post(url, headers=headers, json=data)

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/fav/delete';

const headers = new Headers();
headers.append('Accept-Version', 'v5');
headers.append('Authorization', 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0');
headers.append('Content-Type', 'application/json');

const data = {
  image_id: 8008
};

fetch(apiUrl, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
  .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);
  });

Toggles an image in the user

POST https://api.waifu.im/fav/toggle

If the image is already in the user's favorites, it will be removed. If it was not in the favorites, it will be inserted.

Requires manage_favorites permission.

Headers

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

Request Body

Name	Type	Description
image_id*	integer	The ID of the image to toggle.
user_id	integer	The user ID of the user whose favorites you want to edit.

200: OK If the image was already in the favorites

{"state":"DELETED"}

200: OK If the image was not already in the favorites

{"state":"INSERTED"}

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 toggle the image ID 8008 from your favorites:

Curl

curl -X POST \
  'https://api.waifu.im/fav/toggle' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Version: v5' \
  -H 'Authorization: Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0' \
  -d '{
    "image_id": 8008
  }'

Python

import requests

url = 'https://api.waifu.im/fav/toggle'

headers = {
    'Accept-Version': 'v5',
    'Authorization': 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0',
    'Content-Type': 'application/json',
}

data = {
    'image_id': 8008
}

response = requests.post(url, headers=headers, json=data)

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/fav/toggle';

const headers = new Headers();
headers.append('Accept-Version', 'v5');
headers.append('Authorization', 'Bearer TjBY0MBcS3-SEc3Ms6T4GKjHGJkbqM6McejlQdnqo2y47jWNLa4agsWYdJukocDqHpm2zYFO5z2AjMzkUSfLsCz1AgbDhSjKLMIOnhJGFgODgOkSnzaAWzvGZZPdbm6vOTxs2chmz-3DSRVzwQLl__eYE4Wnjtr0aIGzXlo82M0');
headers.append('Content-Type', 'application/json');

const data = {
  image_id: 8008
};

fetch(apiUrl, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
  .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);
  });