API Endpoints

The API provides two ways of browsing the online catalog. Use the id (also known as magic number) for selective searches, or queries to hit a broader range of results. This is the right place if you want to learn more about how this library works.

Even though, strictly speaking, this is not part of the API, it's still important to note how one can redirect doujins to their URL:

            
                from urllib.parse import urljoin

                id = 177013

                # construct url from id:
                # https://nhentai.net/g/177013
                url = urljoin('https://nhentai.net/g/', str(id))
            
        

See also the self.url property.

This is the most important API endpoint that contains almost all information available. See also the self.api and self.json properties.

            
                from urllib.parse import urljoin

                id = 177013

                # construct endpoint from id:
                # https://nhentai.net/api/gallery/177013
                api = urljoin('https://nhentai.net/api/gallery/', str(id))
            
        

The cover image is constructed from the media ID and file extension. You can take a look at the implementation details from self.cover and Extension.convert to learn how to make this from scratch:

            
                # example for id=177013:
                # https://t.nhentai.net/galleries/987560/cover.jpg

                @property
                def cover(self) -> str:
                    """
                    Return the cover URL of this `Hentai` object.
                    """
                    cover_ext = Extension.convert(self.json['images']['cover']['t'])
                    return f"https://t.nhentai.net/galleries/{self.media_id}/cover{cover_ext}"
            
        

The thumbnail image is constructed from the media ID and file extension. You can take a look at the implementation details from self.thumbnail and Extension.convert to learn how to make this from scratch:

            
                # example for id=177013:
                # https://t.nhentai.net/galleries/987560/thumb.jpg

                @property
                def thumbnail(self) -> str:
                    """
                    Return the thumbnail URL of this `Hentai` object.
                    """
                    thumb_ext = Extension.convert(self.json['images']['thumbnail']['t'])
                    return f"https://t.nhentai.net/galleries/{self.media_id}/thumb{thumb_ext}"
            
        

The general Hentai API does not directly provide the image URLs, i.e. the doujin pages, in its initial response. They have to be constructed from the media ID, the filename and file extension. All file stems are iterated from \(1\) to len(self.json['images']['pages']). See below an example on how this is implemented in the self.image_urls property which in turn is based on the self.pages property that contains additional meta data such as image widths and image heights:

            
                # example for id=177013:
                # https://i.nhentai.net/galleries/987560/1.jpg

                @property
                def pages(self) -> List[Page]:
                    """
                    Return a collection of pages detailing URL, file extension, width and
                    height of this `Hentai` object.
                    """
                    pages = self.json['images']['pages']
                    extension = lambda num: Extension.convert(pages[num]['t'])
                    image_url = lambda num: f"https://i.nhentai.net/galleries/{self.media_id}/{num}{extension(num - 1)}"
                    return [Page(image_url(num + 1), Extension.convert(_['t']), _['w'], _['h']) for num, _ in enumerate(pages)]

                @property
                def image_urls(self) -> List[str]:
                    """
                    Return all image URLs of this `Hentai` object, excluding cover and thumbnail.
                    """
                    return [image.url for image in self.pages]
            
        

The comment section of a doujin can be obtained by appending /comments to this doujin's API property that we discussed here. See also the self.thread property. Interestingly enough, the comment section also includes quite a lot information about the poster (user).

            
                from urllib.parse import urljoin

                id = 177013

                # construct endpoint from id
                api = urljoin('https://nhentai.net/api/gallery/', str(id))
                # get comment section endpoint for this id:
                # https://nhentai.net/api/gallery/177013/comments
                cmt_api = urljoin(api, '/comments')
            
        

A list of related doujins can be obtained by appending /related to this doujin's API property that we discussed here. See also the self.related property. This endpoint returns a list of five doujins; as far as I am aware, this list can change over time.

            
                from urllib.parse import urljoin

                id = 177013

                # construct endpoint from id
                api = urljoin('https://nhentai.net/api/gallery/', str(id))
                # get related endpoint for this id:
                # https://nhentai.net/api/gallery/177013/related
                rlt_api = urljoin(api, '/related')
            
        

Search queries can yield more refined results by specifying the query, the page number and sort value. See also the Sort enum for the other known sort values. Each query returns as much as \(25\) doujins per page. You can skip the query value in the payload below to get doujins from the homepage.

            
                from hentai import RequestHandler

                payload = {'query': 'tag:loli', 'page': 1, 'sort': 'popular'}
                response = RequestHandler().get(url='https://nhentai.net/api/galleries/search', params=payload)

                # the result of this search query, i.e. the first page where tag=loli sorted by popular:
                # https://nhentai.net/api/galleries/search?query=tag:loli&page=1&sort=popular
                result = response.json()
            
        

Note that these methods are already implemented in the Utils class. Moreover, refer to this site for more information on search queries.

Another search query makes use of Tag IDs that is accessed by yet another endpoint. This type of query also returns as much as \(25\) doujins per page.

            
                from hentai import RequestHandler

                # 33918 = character id of holo
                payload = {'tag_id': 33918, 'page': 1, 'sort': 'popular'}
                response = RequestHandler().get(urljoin(Hentai.HOME, "api/galleries/tagged"), params=payload)

                # the result of this search query, i.e. the first page where tag_id=33918 sorted by popular:
                # https://nhentai.net/api/galleries/tagged?tag_id=33918&page=1&sort=popular
                result = response.json()