API Endpoints Overview

Nekosia API offers various endpoints that provide access to a wide range of images and related information. Below is a list of all available endpoints along with a brief description of their functions.

It is also worth familiarizing yourself with the session mechanism, which allows for tracking displayed images for users, helping to avoid showing duplicate images.

Available API Versions

Click here to see the list of available API versions.

Base URL Information

All API requests should be directed to the base URL: https://api.nekosia.cat/api/v1. This URL serves as the foundation for all endpoint calls within the API.

Tags and categories

Main categories

catgirl, foxgirl, wolf-girl, animal-ears, tail, tail-with-ribbon, tail-from-under-skirt
cute, cuteness-is-justice, blue-archive, girl, young-girl, maid, maid-uniform, vtuber, w-sitting, lying-down, hands-forming-a-heart, wink, valentine, headphones
thigh-high-socks, knee-high-socks, white-tights, black-tights, heterochromia, uniform, sailor-uniform, hoodie, ribbon, white-hair, blue-hair, long-hair, blonde, blue-eyes, purple-eyes

Other

swimwear, swimsuit, bikini, sea, swim-ring
Ensure that these photos are appropriate for your project and adhere to the platform's guidelines where you plan to publish them. Don't worry, all the photos are SFW (Safe for Work, with no adult content).

Tags

You can find the full list of tags on the Booru website.

GET /images/:category

This endpoint allows you to fetch random images from a selected category.

Parameters

/images/:category?count={int}&additionalTags={string}&blacklistedTags={string}&rating={string}

  • :category - Check available category tags on our Booru page. Each image is assigned to one main category.
  • ?count - The number of images to fetch (default: 1, maximum: 48). The higher the number, the longer the server response time (in milliseconds).
  • &additionalTags - Additional tags to include when searching for images.
  • &blacklistedTags - Tags to exclude from the search results.
  • &rating - Image rating. safe or questionable. The default value is ALWAYS safe.

Example Response

{
    "success": Boolean,
    "status": Int,
    "key": undefined || String,
    "count": Int,
    "id": String,
    "colors": { "main": "#Hex", "palette": ["#Hex1", "#Hex2", "#Hex3", "#Hex4", "#Hex5", "#Hex6", "#Hex7", "#Hex8", "#Hex9", "#Hex10", "#Hex11", "#Hex12", "#Hex13", "#Hex14"] },
    "image": {
        "original": { "url": String, "extension": String },
        "compressed": { "url": String, "extension": String }
    },
    "metadata": { "original": { "width": Int, "height": Int, "size": Int, "extension": String }, "compressed": { "width": Int, "height": Int, "size": Int, "extension": String } },
    "category": String,
    "tags": [String, String, String, String, String...],
    "rating": safe || questionable || nsfw,
    "anime": { "title": String || null, "character": String || null },
    "source": { "url": String || null, "direct": String || null },
    "attribution": { "artist": { "username": String || null, "profile": String || null }, "copyright": String || null }
}

Example Request

GET /images/cute?count=4&additionalTags=white-hair,uniform&blacklistedTags=short-hair,sad,maid

Error Responses

{
  "success": false,
  "status": 400,
  "message": "Request missing category parameter."
}

Shadow Category

Nekosia API offers a special shadow category, which differs from the others in its operation. Using this category allows you to fetch random images only from those that match your selected tags. This is a recommended solution if you do not want to limit yourself to the main categories only.

Characteristics

  1. The shadow category requires additional tags to be provided in the additionalTags parameter, which are used for precise filtering of images.
  2. When using shadow, the additionalTags parameter must be filled with appropriate tags. Note that some tags may be unavailable for safety reasons.

Parameters

  • category - Must be set to shadow.
  • count - The number of images to fetch (default: 1, maximum: 48).
  • additionalTags - The main tag to be included in the image search. This is crucial for this category.
  • blacklistedTags - List of tags to be excluded.

Example Request

GET /images/shadow?count=3&additionalTags=catgirl,foxgirl,wolf-girl&blacklistedTags=dog-girl

The shadow category allows for precise image searches matching the selected criteria, offering a more personalized experience.

Sessions

The API supports a session mechanism, which allows for tracking displayed images for users. This way, you can avoid displaying duplicate images. Sessions can be identified by the user's IP address or a unique session identifier (e.g., an external system user ID, such as Discord).

Types of Sessions

  • ip - Session identified based on the user's IP address. This is useful when you do not have a unique user identifier.
  • id - Session identified based on a unique user identifier passed in the id parameter. This can be, for example, a specific person's ID on Discord.

Session Parameters

  • session - Type of session (ip or id).
    • ip - Session identified based on the user's IP address.
    • id - Session identified based on a unique user identifier.
  • id - Unique user identifier if session is set to id. Otherwise, the parameter is ignored. The identifier must meet the following conditions:
    • Length of 6 to 128 characters.
    • No special characters such as !@#$%^&*()_+{}|:"<>?.

Example Requests

  1. Session identified based on the IP address:

    GET /images/catgirl?session=ip&additionalTags=foxgirl,wolf-girl,tail&blacklistedTags=dog-girl

  2. Session identified based on a unique user identifier (e.g., from Discord):

    GET /images/catgirl?session=id&id=561621386569973783&additionalTags=foxgirl,wolf-girl,tail&blacklistedTags=dog-girl

Important Notes

  1. Uniqueness of IP-based sessions:
    IP-based sessions may not be fully unique, especially in shared networks.

  2. Uniqueness of session identifiers (id):
    Session identifiers (id) should be sufficiently long and unique to ensure session uniqueness. Using unique identifiers such as external system user IDs (e.g., Discord) ensures precise session tracking and avoids image duplication.

  3. Session storage time:
    Sessions are stored for approximately 8 days, after which they are automatically deleted.

  4. Resetting sessions:
    If the user views all available images from a given category, the system automatically resets the session for that user, allowing random images to be displayed again.

  5. Security and privacy:
    Session identifiers and IP addresses are stored with the highest standards of security and privacy. This data is used solely for tracking displayed images and is not shared with third parties.

Use Cases

  • session=ip: Can be used in cases where the user is not logged in, when the service does not offer a login feature, or when there is no way to identify a specific user.
  • session=id: Recommended for example for Discord bots. With this solution, the user will never encounter duplicate images.

GET /getImageById/:id

Retrieve details about a specific image.

Example Request

GET /getImageById/66bc6b7481a59a1cf2c79db5

Via curl

curl -X GET "https://api.nekosia.cat/api/v1/getImageById/66bc6b7481a59a1cf2c79db5" -H "Content-Type: application/json"