{"id":16457,"library":"nhentai-api","title":"nHentai Node.JS API Client","description":"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.","status":"active","version":"3.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/Zekfad/nhentai-api","tags":["javascript","r18","adult","nhentai","api","typescript"],"install":[{"cmd":"npm install nhentai-api","lang":"bash","label":"npm"},{"cmd":"yarn add nhentai-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add nhentai-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS users should destructure the `API` class from the `require` call, e.g., `const { API } = require('nhentai-api');`","wrong":"const API = require('nhentai-api');","symbol":"API","correct":"import { API } from 'nhentai-api';"},{"note":"Used for filtering tags by type. CommonJS users should also destructure `TagTypes` from the `require` call. It represents an object with tag type constants.","wrong":"const TagTypes = require('nhentai-api').TagTypes;","symbol":"TagTypes","correct":"import { TagTypes } from 'nhentai-api';"},{"note":"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.","wrong":"import NhentaiAPI from 'nhentai-api';","symbol":"API as NhentaiAPI","correct":"import { API as NhentaiAPI } from 'nhentai-api';"}],"quickstart":{"code":"import { API, TagTypes } from 'nhentai-api';\n\nasync function main() {\n  const api = new API();\n  console.log('Fetching a specific book (ID: 177013)...');\n  try {\n    const book = await api.getBook(177013);\n    console.log(`Book Title: ${book.title.pretty}`);\n    console.log(`Cover URL: ${api.getImageURL(book.cover)}`);\n    if (book.pages.length > 0) {\n      console.log(`First page URL: ${api.getImageURL(book.pages[0])}`);\n    }\n    console.log(`Tags: ${book.tags.map(t => t.name).join(', ')}`);\n    console.log(`Artists: ${book.artists.map(a => a.name).join(', ')}`);\n\n    console.log('\\nFetching a random book...');\n    const randomBook = await api.getRandomBook();\n    console.log(`Random Book ID: ${randomBook.id}`);\n    console.log(`Random Book Title: ${randomBook.title.pretty}`);\n\n    console.log('\\nSearching for books with query \"test\" (first page)...');\n    const searchResult = await api.search('test');\n    console.log(`Search query: \"${searchResult.query}\"`);\n    console.log(`Total search pages: ${searchResult.pages}`);\n    if (searchResult.books.length > 0) {\n      console.log(`First book from search: ${searchResult.books[0].title.pretty}`);\n    }\n\n    // Example of using search generator\n    console.log('\\nUsing search generator for the first 2 pages of \"hentai\"...');\n    let pageCount = 0;\n    for await (const search of api.searchGenerator('hentai')) {\n      console.log(`  Page ${search.page}: Found ${search.books.length} books.`);\n      if (search.page >= 2) break;\n    }\n\n  } catch (error: any) {\n    console.error('An error occurred during API interaction:', error.message);\n  }\n}\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the official GitHub repository for a complete list of breaking changes and migration guides when upgrading across major versions.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your `nhentai-api` package is updated to version `3.4.1` or higher to utilize the `getRandomBook` functionality.","message":"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.","severity":"gotcha","affected_versions":"<3.4.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"3.0.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const { API } = require('nhentai-api');`. For ES Modules, use `import { API } from 'nhentai-api';`.","cause":"Attempting to use `API` class without proper CommonJS destructuring or incorrect ESM import.","error":"ReferenceError: API is not defined"},{"fix":"Update your `nhentai-api` package to version `3.4.1` or newer using `npm update nhentai-api` or `yarn upgrade nhentai-api`.","cause":"Attempting to call `getRandomBook` on an `API` instance from a version older than `3.4.1`.","error":"TypeError: api.getRandomBook is not a function"},{"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.","cause":"The requested book ID does not exist (404), too many requests were made (429), or there's a server-side issue (5xx).","error":"UnhandledPromiseRejectionWarning: Error: Request failed with status code 404 (or 429, 500)"}],"ecosystem":"npm"}