Pixiv API

https://pixiv-api.readthedocs.io/en/latest/
Admin
Pixiv API is a documented, idiomatic, and tested Python wrapper library around Pixiv's App API.
Tokens:5,478
Snippets:56
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install pixiv-api

Source: https://pixiv-api.readthedocs.io/en/latest

Use pip to install the library in your Python environment.

```bash
$ pip install pixiv-api
```

--------------------------------

### Initialize Client

Source: https://pixiv-api.readthedocs.io/en/latest

Instantiate the client object to begin interacting with the Pixiv API.

```python
from pixivapi import Client

client = Client()
```

--------------------------------

### Client(language='English', client_id=..., client_secret=...)

Source: https://pixiv-api.readthedocs.io/en/latest

Initializes a new Pixiv API client instance.

```APIDOC
## Client Initialization

### Description
Initializes the Pixiv API client with language settings and credentials.

### Parameters
- **language** (str) - Optional - The language tag for translations.
- **client_id** (str) - Optional - The client ID.
- **client_secret** (str) - Optional - The client secret.
```

--------------------------------

### login(username, password)

Source: https://pixiv-api.readthedocs.io/en/latest

Authenticates with Pixiv using credentials to obtain access and refresh tokens.

```APIDOC
## login(username, password)

### Description
Logs in with username and password to fetch an access token and a refresh token.

### Parameters
- **username** (str) - Required - Your username.
- **password** (str) - Required - Your password.
```

--------------------------------

### download(url, destination, referer='https://pixiv.net')

Source: https://pixiv-api.readthedocs.io/en/latest

Downloads a file from a given URL to a local destination.

```APIDOC
## download(url, destination, referer)

### Description
Download a file to a given destination using the client's access token.

### Parameters
- **url** (str) - Required - The URL of the file.
- **destination** (str) - Required - The destination file path.
- **referer** (str) - Optional - The Referer header.
```

--------------------------------

### Fetch Recommended Illustrations

Source: https://pixiv-api.readthedocs.io/en/latest

Retrieves personalized illustration recommendations, including optional ranking data.

```python
{
    'contest_exists': False,  # Does a contest exist?
    'illustrations': [Illustration, ...],  # List of illustrations.
    'next': {  # Parameters to get the next set of illustrations.
        'min_bookmark_id_for_recent_illustrations': 6277740037,
        'max_bookmark_id_for_recommend': 6268205545,
        'offset': 0,
    },
    'ranking_illustrations': [Illustration, ...] # Ranking illust.
}
```

--------------------------------

### Download Single Illustration

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch a specific illustration by ID and save it to a local directory.

```python
from pathlib import Path
from pixivapi import Size

illustration = client.fetch_illustration(75523989)
illustration.download(
    directory=Path.home() / 'my_pixiv_images',
    size=Size.ORIGINAL,
)
```

--------------------------------

### fetch_illustrations_recommended(...)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch one’s recommended illustrations.

```APIDOC
## fetch_illustrations_recommended(content_type, include_ranking_illustrations, max_bookmark_id_for_recommend, min_bookmark_id_for_recent_illustrations, offset, bookmark_illust_ids, include_ranking_label)

### Description
Fetch one’s recommended illustrations.

### Parameters
- **content_type** (ContentType) - Optional - The type of content to fetch (ILLUSTRATION or MANGA).
- **include_ranking_illustrations** (bool) - Optional - If True, the top 10 ranked illustrations daily are included.
- **max_bookmark_id_for_recommend** (int) - Optional - Maximum bookmark ID for recommended illustrations.
- **min_bookmark_id_for_recent_illustrations** (int) - Optional - Minimum bookmark ID for recent illustrations.
- **offset** (int) - Optional - The number of illustrations to offset by.
- **bookmark_illust_ids** (list) - Optional - A list of illustration IDs.
- **include_ranking_label** (bool) - Optional - Whether or not to include the ranking label.

### Response
- **contest_exists** (bool) - Does a contest exist?
- **illustrations** (list) - List of Illustration objects.
- **next** (dict) - Parameters to get the next set of illustrations.
- **ranking_illustrations** (list) - Ranking illustrations.
```

--------------------------------

### FullUser workspace dictionary structure

Source: https://pixiv-api.readthedocs.io/en/latest

Represents the dictionary containing workspace information, provided by the Client.fetch_user endpoint.

```json
{
    'chair': '',
    'comment': '',
    'desk': '',
    'desktop': '',
    'monitor': '',
    'mouse': '',
    'music': '',
    'pc': '',
    'printer': '',
    'scanner': '',
    'tablet': '',
    'tool': '',
    'workspace_image_url': None
}
```

--------------------------------

### fetch_following(user_id, visibility=Visibility.PUBLIC, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetches the users that a specific user is following. Returns a maximum of 30 users per response.

```APIDOC
## fetch_following(user_id, visibility=Visibility.PUBLIC, offset=None)

### Description
Fetch the users that a user is following. A maximum of 30 users are returned in a response.

### Parameters
- **user_id** (int) - Required - The ID of the user.
- **visibility** (Visibility) - Optional - The visibility of the followed users. Applies only to one’s own follows.
- **offset** (int) - Optional - The number of users to offset by.

### Returns
- **dict** - A dictionary containing a list of previews for the followed users and the offset needed to get the next page.
```

--------------------------------

### fetch_user_bookmarks(user_id, visibility=Visibility.PUBLIC, max_bookmark_id=None, tag=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch the illustrations bookmarked by a user.

```APIDOC
## fetch_user_bookmarks(user_id, visibility=Visibility.PUBLIC, max_bookmark_id=None, tag=None)

### Description
Fetch the illustrations bookmarked by a user. A maximum of 30 illustrations are returned in a response.

### Parameters
- **user_id** (int) - Required - The ID of the user.
- **visibility** (Visibility) - Optional - The visibility of the bookmarks.
- **max_bookmark_id** (int) - Optional - The ID of the maximum bookmark.
- **tag** (str) - Optional - The bookmark tag to filter bookmarks by.

### Returns
- **dict** - A dictionary containing the user’s bookmarks and the max_bookmark_id needed to get the next page.

### Raises
- **requests.RequestException** - If the request fails.
- **BadApiResponse** - If the response is not valid JSON.
```

--------------------------------

### Fetch Bookmark Details Response Structure

Source: https://pixiv-api.readthedocs.io/en/latest

The structure of the dictionary returned by the fetch_bookmark method.

```python
{
    'is_bookmarked': True,
    'visibility': Visibility.PUBLIC,
    'tags': [
        {
            'is_registered': False,
            'name': 'ghostblade',
        },
        ...
    ],
}
```

--------------------------------

### Authenticate Client

Source: https://pixiv-api.readthedocs.io/en/latest

Authenticate using either credentials or a refresh token.

```python
client.login('username', 'password')
```

```python
client.authenticate('refresh_token')
```

--------------------------------

### fetch_illustrations_following(visibility=<Visibility.PUBLIC: 'public'>, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch new illustrations from followed artists. A maximum of 30 illustrations are returned in one response.

```APIDOC
## fetch_illustrations_following(visibility, offset=None)

### Description
Fetch new illustrations from followed artists. A maximum of 30 illustrations are returned in one response.

### Parameters
- **visibility** (Visibility) - Required - Visibility of the followed artist; PUBLIC if publicly followed; PRIVATE if privately.
- **offset** (int) - Optional - The number of illustrations to offset by.

### Response
- **illustrations** (list) - List of Illustration objects.
- **next** (int) - Offset to get the next page of illustrations.
```

--------------------------------

### FullUser profile dictionary structure

Source: https://pixiv-api.readthedocs.io/en/latest

Represents the profile information dictionary returned when fetching a user via Client.fetch_user.

```json
{
    'address_id': 01,
    'background_image_url': None,
    'birth': '',
    'birth_day': '01-01',
    'birth_year': 0,
    'country_code': 'CN',
    'gender': '',
    'is_premium': True,
    'is_using_custom_profile_image': True,
    'job': 'Something',
    'job_id': 1,
    'pawoo_url': (
        'https://pawoo.net/oauth_authentications/123?provider=pixiv'
    ),
    'region': 'China',
    'total_follow_users': 0,
    'total_illust_bookmarks_public': 1,
    'total_illust_series': 0,
    'total_illusts': 0,
    'total_manga': 0,
    'total_mypixiv_users': 0,
    'total_novel_series': 0,
    'total_novels': 0,
    'twitter_account': 'twittername',
    'twitter_url': 'https://twitter.com/twittername',
    'webpage': 'https://webpage.com'
}
```

--------------------------------

### add_bookmark(illustration_id, visibility=Visibility.PUBLIC, tags=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Bookmark an illustration.

```APIDOC
## add_bookmark(illustration_id, visibility=Visibility.PUBLIC, tags=None)

### Description
Bookmark an illustration.

### Parameters
- **illustration_id** (int) - Required - The ID of the illustration.
- **visibility** (Visibility) - Optional - The visibility of the bookmark.
- **tags** (list) - Optional - The bookmark tags of the illustration.

### Raises
- **requests.RequestException** - If the request fails.
```

--------------------------------

### Fetch User Bookmark Tags Response Structure

Source: https://pixiv-api.readthedocs.io/en/latest

The structure of the dictionary returned by the fetch_user_bookmark_tags method.

```python
{
    'bookmark_tags': [  # List of bookmark tags.
        {
            'count': 5,  # Number of bookmarks with the tag.
            'name': 'a-bookmark-tag',
        },
        ...
    ],
    'next': 30,  # Offset for the next page of bookmark tags.
}
```

--------------------------------

### Response structure for fetch_following

Source: https://pixiv-api.readthedocs.io/en/latest

Represents the dictionary structure returned when fetching followed users, including user previews and pagination offset.

```python
{
    'user_previews': [  # List of bookmark tags.
        {
            'illustrations': [  # Their 3 most recent illustrations.
                Illustration,
                Illustration,
                Illustration,
            ],
            'is_muted': False,  # Are they muted?
            'novels': [   # Their 3 most recent novels.
                Novel,
                Novel,
                Novel,
            ],
            'user': User,  # Basic information about the user.
        },
        ...
    ],
    'next': 30,  # Offset for the next page of user previews.
}
```

--------------------------------

### Fetch User Bookmarks Response Structure

Source: https://pixiv-api.readthedocs.io/en/latest

The structure of the dictionary returned by the fetch_user_bookmarks method.

```python
{
    'illustrations': [Illustration, ...],  # List of illustrations.
    'next': 30,  # `max_bookmark_id` for the next page of bookmarks.
}
```

--------------------------------

### FullUser profile_publicity dictionary structure

Source: https://pixiv-api.readthedocs.io/en/latest

Represents the dictionary detailing public and private profile sections, provided by the Client.fetch_user endpoint.

```json
{
    'birth_day': 'public',
    'birth_year': 'public',
    'gender': 'public',
    'job': 'public',
    'pawoo': True,
    'region': 'public'
}
```

--------------------------------

### fetch_bookmark(illustration_id)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch details about a bookmarked illustration.

```APIDOC
## fetch_bookmark(illustration_id)

### Description
Fetch details about a bookmarked illustration.

### Parameters
- **illustration_id** (int) - Required - The ID of the bookmarked illustration.

### Returns
- **dict** - A dictionary containing whether or not the illustration is bookmarked, the visibility of the bookmark, and a list of tags.

### Raises
- **requests.RequestException** - If the request fails.
- **BadApiResponse** - If the response is not valid JSON.
```

--------------------------------

### Download Artist Illustrations

Source: https://pixiv-api.readthedocs.io/en/latest

Iterate through an artist's illustrations and download them using pagination.

```python
from pathlib import Path
from pixivapi import Size

artist_id = 2188232
directory = Path.home() / 'wlop'

response = client.fetch_user_illustrations(artist_id)
while True:
    for illust in response['illustrations']:
        illust.download(directory=directory, size=Size.ORIGINAL)

    if not response['next']:
        break

    response = client.fetch_user_illustrations(
        artist_id,
        offset=response['next'],
    )
```

--------------------------------

### Fetch Related Illustrations

Source: https://pixiv-api.readthedocs.io/en/latest

Returns a dictionary containing a list of related illustrations and the offset for the next page.

```python
{
    'illustrations': [Illustration, ...],  # List of illustrations.
    'next': 30,  # Offset to get the next page of illustrations.
}
```

--------------------------------

### fetch_user_bookmark_tags(user_id, visibility=Visibility.PUBLIC, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch the bookmark tags that belong to the user.

```APIDOC
## fetch_user_bookmark_tags(user_id, visibility=Visibility.PUBLIC, offset=None)

### Description
Fetch the bookmark tags that belong to the user. A maximum of 30 tags are returned in a response.

### Parameters
- **user_id** (int) - Required - The ID of the user.
- **visibility** (Visibility) - Optional - The visibility of the tags.
- **offset** (int) - Optional - The number of tags to offset by.

### Returns
- **dict** - A dictionary containing the user’s bookmark tags and the offset needed to get the next page.

### Raises
- **requests.RequestException** - If the request fails.
- **BadApiResponse** - If the response is not valid JSON or if another user’s private tags are requested.
```

--------------------------------

### Illustration.download

Source: https://pixiv-api.readthedocs.io/en/latest

Downloads an illustration to a specified directory. Supports single-page and multi-page illustrations.

```APIDOC
## Illustration.download

### Description
Downloads the illustration to the desired directory. If the illustration has multiple pages, a folder will be created and the images placed inside.

### Parameters
- **directory** (pathlib.Path) - Required - The illustration will be downloaded to this directory.
- **size** (Size) - Optional - The size of the image to download. Defaults to Size.ORIGINAL.
- **filename** (str) - Optional - The filename of a single-page illustration or the folder name of a multi-page illustration. Do not include the file extension. Defaults to the illustration ID.

### Exceptions
- **requests.RequestException** - If the request fails.
- **FileNotFoundError** - If the destination directory does not exist.
- **PermissionError** - If the destination cannot be written to.
```

--------------------------------

### fetch_illustrations_ranking(mode=<RankingMode.DAY: 'day'>, date=None, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch the ranking illustrations. A maximum of 30 illustrations are returned in one response.

```APIDOC
## fetch_illustrations_ranking(mode, date, offset)

### Description
Fetch the ranking illustrations. A maximum of 30 illustrations are returned in one response.

### Parameters
- **mode** (RankingMode) - Optional - The ranking list to fetch.
- **date** (str) - Optional - The date of the list, in %Y-%m-%d format.
- **offset** (int) - Optional - The number of illustrations to offset by.

### Response
- **illustrations** (list) - List of Illustration objects.
- **next** (int) - Offset to get the next page of illustrations.
```

--------------------------------

### fetch_user(user_id)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch details about a Pixiv user.

```APIDOC
## fetch_user(user_id)

### Description
Fetch details about a Pixiv user.

### Parameters
- **user_id** (int) - Required - The ID of the user.

### Returns
- **FullUser** - A FullUser object.

### Raises
- **requests.RequestException** - If the request fails.
- **BadApiResponse** - If the response is not valid JSON.
```

--------------------------------

### Fetch Trending Tags

Source: https://pixiv-api.readthedocs.io/en/latest

Retrieves a list of trending illustrations and their associated tags.

```python
[
    {
        'illustration': Illustration,
        'tag': '艦これ',
        'translated_name': 'Kancolle',
    },
    ...
]
```

--------------------------------

### Response structure for fetch_followers

Source: https://pixiv-api.readthedocs.io/en/latest

Represents the dictionary structure returned when fetching followers, including user previews and pagination offset.

```python
{
    'user_previews': [  # List of bookmark tags.
        {
            'illustrations': [  # Their 3 most recent illustrations.
                Illustration,
                Illustration,
                Illustration,
            ],
            'is_muted': False,  # Are they muted?
            'novels': [   # Preview of their novels.
                Novel,
                Novel,
                Novel,
            ],
            'user': User,  # Basic information about the user.
        },
        ...
    ],
    'next': 30,  # Offset for the next page of user previews.
}
```

--------------------------------

### Fetch Illustration Comments Response Structure

Source: https://pixiv-api.readthedocs.io/en/latest

The structure of the dictionary returned by the fetch_illustration_comments method.

```python
{
    'comments': [Comment, ...],  # List of comments.
    'next': 30,  # Offset to get the next page of comments.
    'total_comments': 142,
}
```

--------------------------------

### fetch_followers(offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetches the users that are following the requesting user.

```APIDOC
## fetch_followers(offset=None)

### Description
Fetch the users that are following the requesting user.

### Parameters
- **offset** (int) - Optional - The number of users to offset by.

### Returns
- **dict** - A dictionary containing a list of previews for the users that follow the requesting user and the offset needed to get the next page.
```

--------------------------------

### fetch_user_illustrations(user_id, content_type=ContentType.ILLUSTRATION, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch the illustrations posted by a user.

```APIDOC
## fetch_user_illustrations(user_id, content_type=ContentType.ILLUSTRATION, offset=None)

### Description
Fetch the illustrations posted by a user.

### Parameters
- **user_id** (int) - Required - The ID of the user.
- **content_type** (ContentType) - Optional - The type of content to fetch (ILLUSTRATION or MANGA).
- **offset** (int) - Optional - The number of illustrations/manga to offset by.

### Returns
- **dict** - A dictionary containing the user’s illustrations and the offset to get the next page.

### Raises
- **requests.RequestException** - If the request fails.
- **BadApiResponse** - If the response is not valid JSON.
```

--------------------------------

### fetch_illustration(illustration_id)

Source: https://pixiv-api.readthedocs.io/en/latest

Retrieves details for a specific illustration.

```APIDOC
## fetch_illustration(illustration_id)

### Description
Fetch the details of a single illustration.

### Parameters
- **illustration_id** (int) - Required - The ID of the illustration.
```

--------------------------------

### fetch_illustration_comments(illustration_id, offset, include_total_comments)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetches comments for a specific illustration.

```APIDOC
## fetch_illustration_comments(illustration_id, offset, include_total_comments)

### Description
Fetch the comments of an illustration. A maximum of 30 comments are returned in one response.

### Parameters
- **illustration_id** (int) - Required - ID of the illustration.
- **offset** (int) - Optional - Number of comments to offset by.
- **include_total_comments** (bool) - Optional - Whether to include the total number of comments.
```

--------------------------------

### fetch_trending_tags()

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch trending illustrations and tags.

```APIDOC
## fetch_trending_tags()

### Description
Fetch trending illustrations and tags.

### Response
- **list** (list) - A list of dicts containing an illustration, the tag name, and the tag translation.
```

--------------------------------

### Search Illustrations Response Structure

Source: https://pixiv-api.readthedocs.io/en/latest

The structure of the dictionary returned by the search_illustrations method.

```python
{
    'illustrations': [Illustration, ...],  # List of illustrations.
    'next': 30,  # Offset to get the next page of illustrations.
    'search_span_limit': 31536000,
}
```

--------------------------------

### search_illustrations(word, search_target, sort, duration, offset)

Source: https://pixiv-api.readthedocs.io/en/latest

Searches for illustrations based on specific criteria.

```APIDOC
## search_illustrations(word, search_target, sort, duration, offset)

### Description
Search the illustrations. A maximum of 30 illustrations are returned in one response.

### Parameters
- **word** (str) - Required - The search term.
- **search_target** (SearchTarget) - Optional - The target for the search term.
- **sort** (Sort) - Optional - How to sort the illustrations.
- **duration** (Duration) - Optional - Max-age for the illustrations.
- **offset** (int) - Optional - Number of illustrations to offset by.
```

--------------------------------

### Retrieve Refresh Token

Source: https://pixiv-api.readthedocs.io/en/latest

Access the refresh token from the authenticated client for future use.

```python
refresh_token = client.refresh_token
```

--------------------------------

### fetch_illustration_related(illustration_id, offset=None)

Source: https://pixiv-api.readthedocs.io/en/latest

Fetch illustrations related to a specified illustration. A maximum of 30 illustrations are returned in one response.

```APIDOC
## fetch_illustration_related(illustration_id, offset=None)

### Description
Fetch illustrations related to a specified illustration. A maximum of 30 illustrations are returned in one response.

### Parameters
- **illustration_id** (int) - Required - ID of the illustration.
- **offset** (int) - Optional - Illustrations to offset by.

### Response
- **illustrations** (list) - List of Illustration objects.
- **next** (int) - Offset to get the next page of illustrations.
```

--------------------------------

### authenticate(refresh_token)

Source: https://pixiv-api.readthedocs.io/en/latest

Refreshes the access token using a provided refresh token.

```APIDOC
## authenticate(refresh_token)

### Description
Uses a refresh token to obtain a new access token.

### Parameters
- **refresh_token** (str) - Required - The refresh token.
```

--------------------------------

### delete_bookmark(illustration_id)

Source: https://pixiv-api.readthedocs.io/en/latest

Delete a bookmark.

```APIDOC
## delete_bookmark(illustration_id)

### Description
Delete a bookmark.

### Parameters
- **illustration_id** (int) - Required - The ID of the illustration.

### Raises
- **requests.RequestException** - If the request fails.
```
Tokens:
Raw