API Endpoints

Base URL

https://nekos.best/api/:version

Replace :version with one of the supported versions below.

Versions

Version

Status

v2

Current & Maintained

Categories

Categories define the type of content returned by the API. Each category maps to a fixed file format.

Images

husbandokitsunenekowaifu

GIFs

angrybakabiteblushbonkboredcrycuddledancefacepalmfeedhandholdhandshakehappyhighfivehugkickkisslaughlurknodnomnopepatpeckpokepoutpunchrunshootshrugslapsleepsmilesmugstaretableflipthinkthumbsupticklewavewinkyawnyeet

Endpoints

GET /endpoints

Returns all available API categories and their associated file formats.

Example

https://nekos.best/api/v2/endpoints

{
  "neko": { "format": "png" },
  "...": {},
  "wink": { "format": "gif" }
}

TIP

Use this endpoint to dynamically discover supported categories instead of hardcoding them.

---

GET /:category

Returns a random image or GIF from the specified category, including metadata.

Query Parameters

Name	Type	Required	Description
amount	number	No	Number of results to return (1 ≤ X ≤ 20)

By default the API defaults amount to 1.

Example (single result)

https://nekos.best/api/v2/neko

{
  "results": [
    {
      "artist_name": "John Doe",
      "artist_href": "https://www.example.com/en/users/1234567",
      "source_url": "https://www.example.com/en/artworks/1234567",
      "url": "https://nekos.best/api/v2/neko/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Example (multiple results)

https://nekos.best/api/v2/hug?amount=2

{
  "results": [
    {
      "anime_name": "Generic Anime Name",
      "url": "https://nekos.best/api/v2/hug/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.gif"
    },
    {
      "anime_name": "Generic Anime Name",
      "url": "https://nekos.best/api/v2/hug/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.gif"
    }
  ]
}

---

GET /search

Search for images or GIFs using metadata such as artist names or source titles.

Query Parameters

Name	Type	Required	Description
query	string	Yes	Search phrase
type	enum	Yes	1 = images, 2 = GIFs
category	string	No	Restrict results to a category
amount	number	No	Number of results (1 ≤ X ≤ 20)

Example (image search)

https://nekos.best/api/v2/search?query=John&type=1

{
  "results": [
    {
      "artist_name": "John Doe",
      "artist_href": "https://www.example.com/en/users/1234567",
      "source_url": "https://www.example.com/en/artworks/1234567",
      "url": "https://nekos.best/api/v2/neko/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Example (GIF search with category)

https://nekos.best/api/v2/search?query=Senko&type=2&category=pat&amount=2

{
  "results": [
    {
      "anime_name": "Generic Anime Name",
      "url": "https://nekos.best/api/v2/hug/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.gif"
    },
    {
      "anime_name": "Generic Anime Name",
      "url": "https://nekos.best/api/v2/hug/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.gif"
    }
  ]
}

---

GET /:category/:filename.:format

Retrieves a specific asset directly.

Path Parameters

Name	Description
category	Category name
filename	Asset filename (UUID)
format	File format (png, gif)

INFO

Metadata for this endpoint is returned via URL-encoded HTTP response headers.

Available headers:

• anime_name
• artist_name
• artist_href
• source_url

Example

https://nekos.best/api/v2/hug/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.gif

Response: Binary image or GIF data