pixivpy3 Documentation

When an API response includes a next_url, you can use the parse_qs method to extract the query string parameters required to fetch the next page of results. These parameters can then be passed into the original method using dictionary unpacking (**).

from pixivpy3 import AppPixivAPI
api = AppPixivAPI()

# 1. Get initial results
json_result = api.illust_related(57065990)

# 2. Extract pagination parameters from the next_url
next_qs = api.parse_qs(json_result.next_url)

# 3. Fetch the next page using the extracted parameters
json_result = api.illust_related(**next_qs)
illust = json_result.illusts[0]
print(f">>> {illust.title}, origin url: {illust.image_urls.large}")

When upgrading from the older pixivpy2 to pixivpy3:

1. Replace all calls starting with api.papi.* with api.*.
2. Replace deprecated SPAI (Service API) calls with the new Public-API/App-API calls.

Example of accessing response fields in v3:

rank_list = api.illust_ranking('day')
ranking = rank_list.response[0]
for img in ranking.works:
    print(f"[{img.work.user.name}/{img.work.title}(id={img.work.id})] {img.work.image_urls.px_480mw}")

from pixivpy3 import AppPixivAPI
api = AppPixivAPI()
rank_list = api.illust_ranking('day')
print(rank_list)

# more fields about response: https://github.com/upbit/pixivpy/wiki/sniffer
ranking = rank_list.response[0]
for img in ranking.works:
    # print(img.work)
    print(f"[{img.work.user.name}/{img.work.title}(id={img.work.id})] {img.work.image_urls.px_480mw}")

To use PixivPy3 for Python 3, install it using pip. Ensure you have the requests library installed as it is a requirement.

# for Python3
pip install pixivpy3 --upgrade

Password-based login is no longer supported. You must use a refresh_token to authenticate. Use the api.auth(refresh_token=REFRESH_TOKEN) method to set up your session.

To obtain a refresh_token, you can use external tools like gppt: get-pixivpy-token or follow OAuth flows involving Selenium/ChromeDriver.

from pixivpy3 import AppPixivAPI

access_token = "..."
refresh_token = "..."

api = AppPixivAPI()
api.set_auth(access_token, refresh_token)

The PixivCrawler class is a high-level wrapper around the pixivpy3 API designed for data scraping and persistence. It uses pandas for data manipulation and sqlite3 for storage.

Key features include:

• Pagination Handling: Automatically follows next_url using api.parse_qs to fetch all pages of results.
• Rate Limiting: Includes a randSleep method to introduce random delays between API calls to avoid being blocked.
• Data Persistence: Converts nested JSON fields (like image_urls, tags, user) into stringified JSON for SQLite compatibility and provides a DBIllusts method to reload them back into Python objects.

The BasePixivAPI manages an internal cloudscraper session to handle requests.

• Authentication Lifecycle: The auth() method generates necessary security headers like x-client-time and x-client-hash (using hash_secret) to simulate a legitimate app request. It can perform either a password grant type or a refresh_token grant type.
• Request Execution: The requests_call() method is the internal engine that executes GET, POST, and DELETE requests. It merges additional_headers with any headers provided specifically for that call.
• Error Handling: Many operations raise a PixivError if authentication fails or if the HTTP request encounters an error.

Pixiv often returns {} (an empty object) instead of null for certain fields. To prevent validation errors and avoid making many fields nullable, pixivpy3 uses the EmptyObject class. An EmptyObject instance evaluates to False in a boolean context.

Commonly, fields like series in NovelInfo or series_navigation in WebviewNovel are typed as Union[..., EmptyObject].

To use pixivpy3, import AppPixivAPI, instantiate it, and log in using your Pixiv credentials. You can also set the accepted language for tags (e.g., zh-cn for Chinese).

Note: If you are behind the Great Firewall (GFW), you may need to use ByPassSniApi() instead of AppPixivAPI() and call api.require_appapi_hosts().

from pixivpy3 import *

PIXIV_USERNAME = "userbay"
PIXIV_PASSWORD = "UserPay"

api = AppPixivAPI()
# For bypassing GFW:
# api = ByPassSniApi()
# api.require_appapi_hosts()

api.set_accept_language("zh-cn")

token = api.login(PIXIV_USERNAME, PIXIV_PASSWORD)
user_id = token.response.user.id

The PixivDownloader class is a utility designed to download images (either original or square versions) from a Pixiv database (SQLite) previously populated by a crawler. It uses pixivpy3 to handle the actual downloading and includes built-in mechanisms for parsing JSON fields from the database and implementing random sleep intervals to avoid rate limiting.

To use it, instantiate PixivDownloader with your database file, then call StartDownload specifying the target directory and whether you want original or square images.

Use api.illust_detail(illust_id) to retrieve detailed information about a specific illustration. The returned object contains an illust attribute which provides access to various image URL sizes (e.g., large, medium).

from pixivpy3 import AppPixivAPI

access_token = "..."
refresh_token = "..."

api = AppPixivAPI()
api.set_auth(access_token, refresh_token)

# get origin url
json_result = api.illust_detail(59580629)
illust = json_result.illust
print(f">>> origin url: {illust.image_urls.large}")

Use api.illust_ranking(mode) to get ranked illustrations.

Supported modes:

• day
• week
• month
• day_male
• day_female
• week_original
• week_rookie
• day_manga

from pixivpy3 import AppPixivAPI

access_token = "..."
refresh_token = "..."

api = AppPixivAPI()
api.set_auth(access_token, refresh_token)

# get ranking: 1-30
json_result = api.illust_ranking('day')
for illust in json_result.illusts:
    print(f" p1 [{illust.title}] {illust.image_urls.medium}")

To fetch subsequent pages of rankings, use api.parse_qs(json_result.next_url) to extract query parameters from the next_url provided in the previous result, then pass those parameters as keyword arguments to api.illust_ranking(**next_qs).

To iterate through all available pages, use a while loop that continues as long as next_qs is truthy.

# next page: 31-60
next_qs = api.parse_qs(json_result.next_url)
json_result = api.illust_ranking(**next_qs)
for illust in json_result.illusts:
    print(f" p2 [{illust.title}] {illust.image_urls.medium}")

# get all page:
next_qs = {"mode": "day"}
while next_qs:
    json_result = api.illust_ranking(**next_qs)
    for illust in json_result.illusts:
        print(f"[{illust.title}] {illust.image_urls.medium}")
    next_qs = api.parse_qs(json_result.next_url)