### Get Random Images - Python and JavaScript Source: https://nekosapi.com/docs/images/random This snippet demonstrates how to fetch random images from the Nekos API using Python and JavaScript. It shows basic request setup and response handling. No specific dependencies beyond standard libraries are required for these examples. ```python import requests res = requests.get("https://api.nekosapi.com/v4/images/random") res.raise_for_status() data = res.json() ``` ```javascript // JavaScript example would typically use fetch or a library like axios // Example using fetch: /* fetch('https://api.nekosapi.com/v4/images/random') .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error('Error:', error)); */ ``` -------------------------------- ### Install nekosapi JavaScript Library Source: https://nekosapi.com/docs/libraries/javascript Installs the nekosapi library using Yarn, PNPM, or NPM. This is the first step to using the API wrapper in your JavaScript projects. ```bash yarn add nekosapi ``` -------------------------------- ### Install anime-api Library using Pip Source: https://nekosapi.com/docs/libraries/python Install the anime-api library on Python 3.7+ using pip. This is the primary method for integrating Nekos API functionality into your Python projects. ```python pip install anime-api ``` -------------------------------- ### Get Random Image File - JavaScript Request Source: https://nekosapi.com/docs/images/random-file This snippet illustrates how to fetch a random image file from the Nekos API using JavaScript's fetch API. It makes a GET request to the specified endpoint and retrieves the response content. This example is a basic implementation and may require further processing of the response depending on the desired output. ```javascript fetch("https://api.nekosapi.com/v4/images/random/file") .then(response => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.blob(); // Or response.json() if the API returns JSON with the URL }) .then(data => { console.log("Successfully fetched image data."); // Process the image data (e.g., create an image element, download) }) .catch(error => { console.error("Error fetching image:", error); }); ``` -------------------------------- ### Get All Categories (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Retrieves a list of all available categories from the Nekos API. Supports pagination with limit and offset. Returns a promise that resolves with an array of category objects, each containing a name. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); // This will return up to 10 categories and skip the first 5. By default the // limit is set to 10 and the offset is set to 0. nekos.getCategories((limit = 10), (offset = 5)).then((categories) => { for (const category of categories) { console.log(category.name); } }); ``` -------------------------------- ### Get Random Image File - Python Request Source: https://nekosapi.com/docs/images/random-file This snippet demonstrates how to make a GET request to the Nekos API's random image file endpoint using Python's requests library. It fetches the raw content of a random image file URL, potentially filtered by various parameters not shown in this basic example. Ensure the 'requests' library is installed. ```python import requests res = requests.get("https://api.nekosapi.com/v4/images/random/file") res.raise_for_status() data = res.content ``` -------------------------------- ### Get Artist Images by Artist ID (Python) Source: https://nekosapi.com/docs/libraries/python Retrieve all images associated with a specific artist using get_images_by_artist_id(). Supports pagination with limit and offset parameters. Returns a list of image objects. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # This will return up to 10 images from arist with "some-uuid" as ID and skip # the first 5. By default the limit is set to 10 and the offset is set to 0. images = nekos.get_images_by_artist_id(artist_id="some-uuid", limit=10, offset=5) for image in images: print(image.artist.name) ``` -------------------------------- ### Get Artist's Images by ID (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches images created by a specific artist using their ID. Supports pagination with limit and offset parameters. Returns a promise that resolves with an array of image URLs. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); // This will return up to 10 images from arist with "some-uuid" as ID and skip // the first 5. By default the limit is set to 10 and the offset is set to 0. nekos .getImagesByArtistID((id = "some-uuid"), (limit = 10), (offset = 0)) .then((images) => { for (const image of images) { console.log(image.url); } }); ``` -------------------------------- ### Get Image by ID (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches a specific image from the Nekos API using its unique ID. Returns a promise that resolves with the image object containing its URL and other information. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); // This will return the image that has the ID of `some-uuid` (not an actual ID) nekos.getImageByID((id = "some-uuid")).then((image) => { console.log(image.url); }); ``` -------------------------------- ### GET /v4/images/random/file Source: https://nekosapi.com/docs/images/random-file Retrieves a redirect to a random image file URL, allowing filtering by tags, characters, artists, and rating. ```APIDOC ## GET /v4/images/random/file ### Description This endpoint allows you to get a redirect to a random image's file URL, filtering by tags, characters, artists, etc. ### Method GET ### Endpoint /v4/images/random/file ### Parameters #### Query Parameters - **rating** (Array of strings) - Optional - The (age) rating of the image. Allowed values: ["safe", "suggestive", "borderline", "explicit"] - **artist** (Array of integers) - Optional - The artist's ID. - **tags** (Array of strings) - Optional - The tags names, comma-delimited. - **without_tags** (Array of strings) - Optional - The tags to exclude's names, comma-delimited. ### Request Example ```python import requests res = requests.get("https://api.nekosapi.com/v4/images/random/file") res.raise_for_status() data = res.content ``` ### Response #### Success Response (200) - **url** (string) - The URL to the random image file. - **id** (string) - The ID of the image. - **source** (string) - The source of the image. - **like_count** (integer) - The number of likes for the image. - **is_rendered** (boolean) - Whether the image has been rendered. #### Response Example ```json { "url": "https://nekos.api/images/random/file/example.jpg", "id": "12345", "source": "example.com", "like_count": 100, "is_rendered": true } ``` ``` -------------------------------- ### GET /v4/images/random Source: https://nekosapi.com/docs/images/random This endpoint allows you to retrieve a specified number of random images, with options to filter by rating, artists, tags, or exclude specific tags. ```APIDOC ## GET /v4/images/random ### Description This endpoint allows you to get x random images, filtering by tags, characters, artists, etc. ### Method GET ### Endpoint /v4/images/random ### Parameters #### Query Parameters - **rating** (Array of strings) - Optional - The (age) rating of the image. Allowed values: [safe, suggestive, borderline, explicit] - **artist** (Array of integers) - Optional - The artist's ID. - **tags** (Array of strings) - Optional - The tags names, comma-delimited. - **without_tags** (Array of strings) - Optional - The tags to exclude's names, comma-delimited. - **limit** (Integer) - Optional - The amount of images to return. Range: [1..100] ### Request Example ```python import requests res = requests.get("https://api.nekosapi.com/v4/images/random") res.raise_for_status() data = res.json() ``` ### Response #### Success Response (200) - **images** (Array of objects) - An array containing image objects. - **id** (Integer) - The unique identifier for the image. - **url** (String) - The URL of the image. - **dominant_colors** (Array of strings) - An array of dominant colors in the image. - **created_at** (String) - The timestamp when the image was created. - **source** (String) - The source of the image. - **width** (Integer) - The width of the image in pixels. - **height** (Integer) - The height of the image in pixels. - **artist_id** (Integer) - The ID of the artist who created the image. - **artist_name** (String) - The name of the artist. - **image_tags** (Array of objects) - An array of tags associated with the image. - **tag** (String) - The name of the tag. - **id** (Integer) - The ID of the tag. - **locked** (Boolean) - Indicates if the tag is locked. #### Response Example ```json { "images": [ { "id": 12345, "url": "https://example.com/image.jpg", "dominant_colors": ["#RRGGBB", "#RRGGBB"], "created_at": "2023-01-01T12:00:00Z", "source": "Example Source", "width": 1920, "height": 1080, "artist_id": 678, "artist_name": "Example Artist", "image_tags": [ { "tag": "example_tag", "id": 90, "locked": false } ] } ] } ``` ``` -------------------------------- ### Get a Random Image (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches a random image from the Nekos API. Supports specifying categories or fetching a completely random image. Returns a promise that resolves with the image URL. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); // This will return an image with the `catgirl` category. If the `categories` // argument is not specified, the image will be completely random (no specific // categories). nekos.getRandomImage((categories = ["catgirl"])).then((image) => { console.log(image.url); }); ``` -------------------------------- ### Get Artist by ID (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches artist information from the Nekos API using the artist's unique ID. Returns a promise that resolves with an artist object, including their name and a list of their images. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); nekos.getArtistByID((id = "some-uuid")).then((artist) => { console.log(artist.name); console.log(artist.images); // The amount of images that the artist has in the API }); ``` -------------------------------- ### Get a Random Image from Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Fetch a single random image, optionally filtered by category, using the get_random_image() method. Returns an image object with a URL. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # This will return up to 10 images with the `kemonomimi` category image = nekos.get_random_image(categories=["kemonomimi"]) print(image.url) ``` -------------------------------- ### GET /v4/images/{id} Source: https://nekosapi.com/docs/images/details Retrieve a specific image using its unique identifier. ```APIDOC ## GET /v4/images/{id} ### Description This endpoint allows you to get an image by its ID. ### Method GET ### Endpoint `/v4/images/{id}` ### Parameters #### Path Parameters - **id** (String) - Required - The image's ID ### Request Example ```python import requests res = requests.get(f"https://api.nekosapi.com/v4/images/{image_id}") res.raise_for_status() data = res.json() ``` ### Response #### Success Response (200) - **[Field Name]** (Type) - Description of the field (e.g., image URL, tags, etc.) #### Response Example ```json { "id": "example_image_id", "url": "https://example.com/image.jpg", "tags": ["neko", "cute", "anime"] } ``` ``` -------------------------------- ### Get Multiple Random Images (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches multiple random images (up to 25) from the Nekos API. Allows specifying categories and a limit for the number of images. Returns a promise that resolves with an array of image URLs. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); // This will return up to 5 images with the `catgirl` category (it will be less // if there are less than the limit images with that category). The categories // argument is also optional. nekos .getRandomImages((categories = ["catgirl"]), (limit = 5)) .then((images) => { for (const image of images) { console.log(image.url); } }); ``` -------------------------------- ### Get Artist by ID from Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Fetch an artist's details using their ID with get_artist_by_id(). This method uniquely includes the artist's associated images in the returned artist object. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() artist_id = "some-uuid" artist = nekos.get_artist_by_id(artist_id=artist_id) assert artist.id == artist_id print(artist.images) ``` -------------------------------- ### Get Character by ID (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches a specific character's information from the Nekos API using its unique ID. Returns a promise that resolves with a character object, including its name. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); nekos.getCharacterByID((id = "some-uuid")).then((character) => { console.log(character.name); }); ``` -------------------------------- ### Get Multiple Random Images from Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Fetch multiple random images (up to 25) using get_random_images(). The categories argument is optional for completely random results. Returns a list of image objects. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # The categories argument is optional. If not specified, the images will be # completely random (no specific category) images = nekos.get_random_images(limit=10, categories=["kemonomimi"]) for image in images: print(image.url) ``` -------------------------------- ### Get Category by ID from Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Fetch a specific category's details using its unique ID with get_category_by_id(). Returns a category object containing its ID and name. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() category_id = "some-uuid" category = nekos.get_category_by_id(category_id=category_id) assert category.id == category_id print(category.name) ``` -------------------------------- ### Get Nekos Character by ID Python Source: https://nekosapi.com/docs/libraries/python Fetches the details of a specific character from the NekosAPI using its unique ID. The character ID is typically returned in API responses. Requires the 'anime-api' library. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() character_id = "some-uuid" character = nekos.get_character_by_id(character_id=character_id) assert character.id == character_id print(character.name) ``` -------------------------------- ### Get Image by ID from Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Retrieve a specific image's information using its unique ID with the get_image_by_id() method. Returns an image object containing details like URL and ID. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() image_id = "some-uuid" image = nekos.get_image_by_id(image_id=image_id) assert image.id == image_id print(image.url) ``` -------------------------------- ### Get Image by ID - Python and JavaScript Source: https://nekosapi.com/docs/images/details This snippet demonstrates how to retrieve image details from the Nekos API using a provided image ID. It requires the 'requests' library in Python and 'fetch' API in JavaScript. The endpoint returns a JSON object containing image information. ```python import requests res = requests.get(f"https://api.nekosapi.com/v4/images/{image_id}") res.raise_for_status() data = res.json() ``` ```javascript const response = await fetch(`https://api.nekosapi.com/v4/images/${image_id}`); const data = await response.json(); ``` -------------------------------- ### Search for Images using Nekos API Source: https://nekosapi.com/docs/images/search This endpoint allows searching for images by specifying various criteria such as age rating, artist ID, tags, and tags to exclude. It returns a JSON response containing the image data. The results can be limited and offset for pagination. This example demonstrates a basic request. ```Python import requests res = requests.get("https://api.nekosapi.com/v4/images") res.raise_for_status() data = res.json() ``` ```JavaScript // JavaScript example would go here, if provided in the input. ``` -------------------------------- ### Get Category by ID (JavaScript) Source: https://nekosapi.com/docs/libraries/javascript Fetches a specific category's information from the Nekos API using its unique ID. Returns a promise that resolves with a category object, including its name and the number of images associated with it. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); nekos.getCategoryByID((id = "some-uuid")).then((category) => { console.log(category.name); console.log(category.images); // The amount of images in the API with this category }); ``` -------------------------------- ### Initialize nekosapi JavaScript Client Source: https://nekosapi.com/docs/libraries/javascript Demonstrates how to import and instantiate the NekosAPI class from the nekosapi package to begin making API requests. ```javascript const { NekosAPI } = require("nekosapi"); const nekos = new NekosAPI(); ``` -------------------------------- ### Paginate API Results with Limit and Offset Source: https://nekosapi.com/docs/api-introduction Demonstrates how to paginate API results using the 'limit' and 'offset' query parameters. The 'limit' parameter has a maximum of 100 items, while 'offset' is not limited. The response includes an 'items' array and a 'count' of total items. ```http GET /v4/images?limit=100&offset=10 ``` ```json { "items": [ { ... }, { ... }, ... ], "count": 4038 // Total number of items, not only those returned in the page } ``` -------------------------------- ### Nekos API Documentation Source: https://nekosapi.com/docs/api-introduction This section details how to use the Nekos API, including its base URL, rate limits, pagination, error handling, and array query parameters. ```APIDOC ## Introduction Base URL: `https://api.nekosapi.com/v4` This page will help you understand how to use the JSON API. We highly recommend reading this before starting to use the API. ## Rate limits The API has no rate limits at the moment. Can this be a problem in the future? Yes. In case that this becomes an issue, a rate limit will be set. ## Pagination The API uses `limit` and `offset` parameters to paginate the results. ### Example `GET /v4/images?limit=100&offset=10` ```json { "items": [ { ... }, { ... }, ... ], "count": 4038 // Total number of items, not only those returned in the page } ``` The `limit` parameter has a maximum of 100 items. The `offset` parameter is not limited. ## Errors Though we try to make error formats as consistent as possible, we cannot guarantee that all errors will return the same json format (due to different libraries having their own error formats). You can try to read the following error format and use the status code in case it fails: ### Example Error Response `GET /v4/images?limit=101` ```json { "detail": [ { "loc": [ "query", "limit" ], "msg": "ensure this value is less than or equal to 100", "type": "value_error.number.not_le", "ctx": { "limit_value": 100 } } ] } ``` ## Array Query Parameters Array query parameters are always a comma-delimited list. ### Example `/images?tag=girl,blue_hair` ``` -------------------------------- ### Initialize NekosAPI in Python Source: https://nekosapi.com/docs/libraries/python Import and initialize the NekosAPI class from the anime_api.apis module. This sets up the client for making requests to the Nekos API. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() ``` -------------------------------- ### Use Comma-Delimited Tags in API Queries Source: https://nekosapi.com/docs/api-introduction Shows how to use array query parameters, specifically for tags, by providing a comma-delimited list. This allows filtering results based on multiple tags simultaneously. ```http /images?tag=girl,blue_hair ``` -------------------------------- ### Escape Search Queries Python Source: https://nekosapi.com/docs/libraries/python Demonstrates how to use the EscapedQuery helper class to safely include special characters in NekosAPI search queries. This prevents unintended filtering or errors caused by characters like '[', ']', or '*'. Requires the 'anime-api' library. ```python from anime_api.apis.nekos_api import NekosAPI, EscapedQuery nekos = NekosAPI() escaped_query = EscapedQuery("`[` or `]` or maybe `*`?") characters = nekos.get_characters(search=escaped_query) for character in characters: print(character.name) ``` ```python from anime_api.apis.nekos_api import EscapedQuery query = "`[` or `]` or maybe `*`?" escaped = EscapedQuery(query) print(str(escaped)) ``` -------------------------------- ### Complex Escaped Search Queries Python Source: https://nekosapi.com/docs/libraries/python Shows how to construct complex search queries by combining EscapedQuery with f-strings to match characters containing specific sets of special characters. This is useful for intricate search criteria. Requires the 'anime-api' library. ```python from anime_api.apis.nekos_api import NekosAPI, EscapedQuery nekos = NekosAPI() query = f"({EscapedQuery('[ and ]')}) | ({EscapedQuery('{ and }')})" characters = nekos.get_characters(search=query) for character in characters: print(character.name) ``` -------------------------------- ### Search Artists in Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Search for artists using the get_artists() method. Supports limiting results, skipping records (offset), and case-insensitive searching with a pattern. Returns a list of artist objects. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # This will return up to 10 artists and skip the first 5. By default the limit # is set to 10 and the offset is set to 0. The search argument is optional. If # you don't specify it, a list of all artists available will be returned # instead. Search is case-insensitive. artists = nekos.get_artists(limit=10, offset=0, search="%?shiren%?ec") for artist in artists: print(artist.name) ``` -------------------------------- ### Handle API Errors Due to Exceeding Limit Source: https://nekosapi.com/docs/api-introduction Illustrates the error response format when the 'limit' query parameter exceeds its maximum value of 100. The error details include the location of the error, a message, and the error type. ```http GET /v4/images?limit=101 ``` ```json { "detail": [ { "loc": [ "query", "limit" ], "msg": "ensure this value is less than or equal to 100", "type": "value_error.number.not_le", "ctx": { "limit_value": 100 } } ] } ``` -------------------------------- ### Search Categories in Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Search for categories using get_categories(). This method allows filtering by a search term and supports pagination with limit and offset. Returns a list of category names. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # This will return up to 10 categories and skip the first 5. By default the # limit is set to 10 and the offset is set to 0. The search argument is optional. If # you don't specify it, a list of all artists available will be returned # instead. Search is case-insensitive. categories = nekos.get_categories(limit=10, offset=0, search="%?catgi%?") for category in categories: print(category) ``` -------------------------------- ### Search Nekos Characters Python Source: https://nekosapi.com/docs/libraries/python Retrieves a list of characters from the NekosAPI based on a search query. The search is case-insensitive and supports wildcard characters. Requires the 'anime-api' library. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() characters = nekos.get_characters(limit=10, offset=0, search="%?kaguya%?") for character in characters: print(character) ``` -------------------------------- ### Search Characters in Nekos API (Python) Source: https://nekosapi.com/docs/libraries/python Search for characters using the get_characters() method. Supports limiting results and skipping records (offset). The search argument is optional for retrieving all characters. ```python from anime_api.apis import NekosAPI nekos = NekosAPI() # This will return up to 10 characters and skip the first 5. By default the # limit is set to 10 and the offset is set to 0. The search argument is optional. If # you don't specify it, a list of all artists available will be returned ``` -------------------------------- ### Search for an Image Source: https://nekosapi.com/docs/images/search This endpoint allows you to search for an image, filtering by tags, characters, artists, etc. It returns a JSON response containing image data. ```APIDOC ## GET /v4/images ### Description Allows searching for images based on various criteria such as tags, artists, and ratings. ### Method GET ### Endpoint /v4/images ### Parameters #### Query Parameters - **rating** (Array of strings) - Optional - The (age) rating of the image (safe, suggestive, borderline, explicit). - **artist** (Array of integers) - Optional - The artist's ID. - **tags** (Array of strings) - Optional - The tags names, comma-delimited. - **without_tags** (Array of strings) - Optional - The tags to exclude's names, comma-delimited. - **limit** (Integer) - Optional - The amount of images to return (1-100). - **offset** (Integer) - Optional - The amount of images to skip. ### Request Example ```python import requests res = requests.get("https://api.nekosapi.com/v4/images") res.raise_for_status() data = res.json() ``` ### Response #### Success Response (200) - **data** (Array) - An array of image objects. - **object** (String) - The type of object returned (e.g., "image"). - **id** (Integer) - The unique identifier for the image. - **url** (String) - The URL of the image. - **artist_id** (Integer) - The ID of the artist who created the image. - **artist_name** (String) - The name of the artist. - **source_id** (String) - The ID of the source of the image. - **source_name** (String) - The name of the source of the image. - **tags** (Array of Objects) - An array of tag objects associated with the image. - **tag** (String) - The name of the tag. - **local_tags** (Array of Strings) - Localized tag names. - **aliase** (Array of Strings) - Aliases for the tag. - **width** (Integer) - The width of the image. - **height** (Integer) - The height of the image. - **created_at** (String) - The date and time the image was created. - **approved_at** (String) - The date and time the image was approved. - **rating** (String) - The age rating of the image. #### Response Example ```json { "data": [ { "object": "image", "id": 12345, "url": "https://example.com/image.jpg", "artist_id": 678, "artist_name": "Example Artist", "source_id": "src123", "source_name": "Example Source", "tags": [ { "tag": "cat", "local_tags": ["gato"], "aliase": ["kitty"] } ], "width": 800, "height": 600, "created_at": "2023-01-01T10:00:00Z", "approved_at": "2023-01-01T11:00:00Z", "rating": "safe" } ] } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.