nHentai Node.JS API Client

3.4.3 · active · verified Wed Apr 22

nhentai-api is a Node.JS client library designed for interacting with the undocumented APIs of nhentai.net. Currently at version 3.4.3, the library exhibits an active release cadence, with recent minor updates addressing type fixes and introducing new features such as `getRandomBook`. It provides an objective-oriented API abstraction, facilitating tasks like bidirectional inspection (e.g., retrieving an image from a book or a book from an image). A key differentiating feature is its built-in support for proxies, allowing users to configure custom agents for requests, enhancing flexibility and privacy. The library focuses on returning structured data from the nhentai.net API and provides direct URLs for binary content like images. It also offers advanced search functionalities and helper methods for filtering and managing various tag types. The package ships with comprehensive TypeScript types, significantly improving developer experience and type safety.

Common errors

```
ReferenceError: API is not defined
```
cause Attempting to use `API` class without proper CommonJS destructuring or incorrect ESM import.

fix For CommonJS, use `const { API } = require('nhentai-api');`. For ES Modules, use `import { API } from 'nhentai-api';`.
```
TypeError: api.getRandomBook is not a function
```
cause Attempting to call `getRandomBook` on an `API` instance from a version older than `3.4.1`.

fix Update your `nhentai-api` package to version `3.4.1` or newer using `npm update nhentai-api` or `yarn upgrade nhentai-api`.
```
UnhandledPromiseRejectionWarning: Error: Request failed with status code 404 (or 429, 500)
```
cause The requested book ID does not exist (404), too many requests were made (429), or there's a server-side issue (5xx).

fix Validate the book ID, implement exponential backoff for rate limiting (429), or wrap API calls in `try/catch` blocks to handle network/API errors gracefully.

Warnings

breaking Major version updates to `3.x` may introduce breaking changes compared to previous major versions. While specific changes are not detailed in the provided release notes, it is recommended to review the full changelog on GitHub when upgrading from `2.x` or earlier.
Fix: Consult the official GitHub repository for a complete list of breaking changes and migration guides when upgrading across major versions.
gotcha The `API#getRandomBook` method was added in version `3.4.1`. Attempting to call this method on earlier versions will result in an error or undefined behavior.
Fix: Ensure your `nhentai-api` package is updated to version `3.4.1` or higher to utilize the `getRandomBook` functionality.
gotcha Initial `3.0.2` release notes explicitly state 'Has no tests yet'. This could imply a higher risk of unexpected behavior or bugs in early `3.x` versions compared to later, more stable releases.
Fix: For production applications, consider using more recent patch versions of the `3.x` series (e.g., `3.4.x`) that have likely incorporated bug fixes and improved stability.

Install

npm install nhentai-api npm
yarn add nhentai-api yarn
pnpm add nhentai-api pnpm

Imports

API
wrong:
```
const API = require('nhentai-api');
```
correct:
```
import { API } from 'nhentai-api';
```
CommonJS users should destructure the `API` class from the `require` call, e.g., `const { API } = require('nhentai-api');`
TagTypes
wrong:
```
const TagTypes = require('nhentai-api').TagTypes;
```
correct:
```
import { TagTypes } from 'nhentai-api';
```
Used for filtering tags by type. CommonJS users should also destructure `TagTypes` from the `require` call. It represents an object with tag type constants.
API as NhentaiAPI
wrong:
```
import NhentaiAPI from 'nhentai-api';
```
correct:
```
import { API as NhentaiAPI } from 'nhentai-api';
```
The `API` class is a named export; there is no default export. Renaming on import is done via `as` keyword for clarity or to avoid naming conflicts.

Quickstart

This quickstart initializes the nhentai API client, fetches a specific book by ID, retrieves a random book, performs a search query, and demonstrates iterating through search results using an async generator. It logs key information like book titles, image URLs, and tag details.

import { API, TagTypes } from 'nhentai-api';

async function main() {
  const api = new API();
  console.log('Fetching a specific book (ID: 177013)...');
  try {
    const book = await api.getBook(177013);
    console.log(`Book Title: ${book.title.pretty}`);
    console.log(`Cover URL: ${api.getImageURL(book.cover)}`);
    if (book.pages.length > 0) {
      console.log(`First page URL: ${api.getImageURL(book.pages[0])}`);
    }
    console.log(`Tags: ${book.tags.map(t => t.name).join(', ')}`);
    console.log(`Artists: ${book.artists.map(a => a.name).join(', ')}`);

    console.log('\nFetching a random book...');
    const randomBook = await api.getRandomBook();
    console.log(`Random Book ID: ${randomBook.id}`);
    console.log(`Random Book Title: ${randomBook.title.pretty}`);

    console.log('\nSearching for books with query "test" (first page)...');
    const searchResult = await api.search('test');
    console.log(`Search query: "${searchResult.query}"`);
    console.log(`Total search pages: ${searchResult.pages}`);
    if (searchResult.books.length > 0) {
      console.log(`First book from search: ${searchResult.books[0].title.pretty}`);
    }

    // Example of using search generator
    console.log('\nUsing search generator for the first 2 pages of "hentai"...');
    let pageCount = 0;
    for await (const search of api.searchGenerator('hentai')) {
      console.log(`  Page ${search.page}: Found ${search.books.length} books.`);
      if (search.page >= 2) break;
    }

  } catch (error: any) {
    console.error('An error occurred during API interaction:', error.message);
  }
}

main();

view raw JSON →