JavaScript

The nekosapi (opens in a new tab) Typescript library is an officially supported API warapper for Nekos API, kindly made by Cataclym (opens in a new tab).

Source code: GitLab (opens in a new tab)

Installation

The library can be installed using Yarn, PNPM or NPM:

yarn add nekosapi

Usage

The NekosAPI() class can be imported from the nekosapi package.

const { NekosAPI } = require("nekosapi");
 
const nekos = new NekosAPI();

Get a random image

The NekosAPI() class has a getRandomImage() method that returns a random image.

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);
});

You can also get many images (up to 25) at once using the getRandomImages() method instead.

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 an image by it's ID

Every image in the API has its own ID. You can fetch an image by its ID to get a specific image's information.

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 an artist by it's ID

Each artist in the API has its ID. Although every image comes with (almost) all its artist information, fetching an artist by its ID has its advantages.

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
});

As you can see, the images property is added to the Artist object when it's fetched by ID. This is not the case if the artist is fetched using a different method.

Get all artist's images

If you want to fetch an artist's images, you can use the getImagesByArtistID() method. This method returns up to 25 images and supports pagination.

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 all categories

To get a list of all categories available, you can use the getCategories() method.

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 category by it's ID

All categories have their unique ID, which is always returned together with the category. You can get a specific category using the getCategoryByID() method.

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
});

The images property is only returned when using this method. Getting a category's information using another method will not return the images property.

Get a character by it's ID

Every character has it's unique ID, which is returned together with the character in every API response. You can get a specific charcater's information using the getCharacterByID() method.

const { NekosAPI } = require("nekosapi");
 
const nekos = new NekosAPI();
 
nekos.getCharacterByID((id = "some-uuid")).then((character) => {
    console.log(character.name);
});

Reference

Wrapper Class

NekosAPI: GitLab (opens in a new tab)

Interfaces

NekosImage: GitLab (opens in a new tab)
Artist: GitLab (opens in a new tab)
Category: GitLab (opens in a new tab)
Character: GitLab (opens in a new tab)

Python Deno