pixivgo

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2026 License: Unlicense Imports: 15 Imported by: 0

README

English | 中文

pixivgo

A Go client for the Pixiv App-API. Golang rewrite of pixivpy.

Features

  • Zero external dependencies — standard library only
  • Full API coverage — illustrations, users, novels, search, bookmarks, and more (~40 methods)
  • Type-safe request parameters and response models
  • Built-in image download with streaming support
  • SNI bypass for restricted networks (DNS-over-HTTPS)
  • Pagination helper for next_url parsing
  • Thread-safe after construction

Quick Start

go get github.com/txperl/pixivgo

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/txperl/pixivgo"
)

func main() {
    ctx := context.Background()
    client := pixivgo.NewClient()

    // Authenticate with refresh token
    _, err := client.Auth(ctx, os.Getenv("PIXIV_REFRESH_TOKEN"))
    if err != nil {
        log.Fatal(err)
    }

    // Search illustrations
    result, err := client.SearchIllust(ctx, pixivgo.SearchIllustParams{
        Word: "風景",
        Sort: pixivgo.SortPopularDesc,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, illust := range result.Illusts {
        fmt.Printf("%s (views: %d)\n", illust.Title, illust.TotalView)
    }
}

Authentication

Pixiv requires a refresh token for authentication. Password login is no longer supported.

To obtain a refresh token, use one of these tools:

// Authenticate and store tokens internally
authResp, err := client.Auth(ctx, "YOUR_REFRESH_TOKEN")

// Or set tokens directly if you already have them
client.SetAuth(accessToken, refreshToken)

Usage

Ranking
ranking, err := client.IllustRanking(ctx, pixivgo.IllustRankingParams{
    Mode: pixivgo.ModeDay,
})
for _, illust := range ranking.Illusts {
    fmt.Println(illust.Title, "by", illust.User.Name)
}
Download
path, err := client.Download(ctx, illust.ImageUrls.Large, &pixivgo.DownloadOptions{
    Path: "./downloads",
})
// or stream to any io.Writer
err = client.DownloadToWriter(ctx, illust.ImageUrls.Large, w)
Pagination
result, _ := client.IllustRanking(ctx, pixivgo.IllustRankingParams{Mode: pixivgo.ModeDay})

// Get next page
nextParams := pixivgo.ParseNextURL(result.NextURL)
if nextParams != nil {
    fmt.Println("next offset:", nextParams.Get("offset"))
}
SNI Bypass

For accessing Pixiv from restricted networks:

import "github.com/txperl/pixivgo/bypass"

httpClient, hosts, err := bypass.NewHTTPClient(ctx)
if err != nil {
    log.Fatal(err)
}
client := pixivgo.NewClient(
    pixivgo.WithHTTPClient(httpClient),
    pixivgo.WithBaseURL(hosts),
)
Error Handling

All errors are wrapped in PixivError, which includes HTTP status, headers, and response body:

var pe *pixivgo.PixivError
if errors.As(err, &pe) {
    fmt.Println(pe.StatusCode, pe.Body)
}

API Overview

Category Example Methods
Illust IllustDetail, IllustRanking, IllustRecommended, ...
User UserDetail, UserIllusts, UserFollowAdd, ...
Novel NovelDetail, NovelSeries, WebviewNovel, ...
Search SearchIllust, SearchNovel, SearchUser
Bookmark UserBookmarksIllust, IllustBookmarkAdd, ...
Misc TrendingTagsIllust, ShowcaseArticle, UgoiraMetadata

Full API reference: GoDoc

Client Options

Option Description
WithHTTPClient(hc) Custom http.Client (for proxies, bypass, etc.)
WithBaseURL(url) Override API base URL
WithAcceptLanguage(l) Language for tag translations (e.g. "en-us")
WithAdditionalHeaders(h) Add custom HTTP headers

Acknowledgments

This project is a Golang rewrite of pixivpy by @upbit. Thank you for the excellent work on the original Python client.

License

Feel free to use, reuse and abuse the code in this project.

Documentation

Overview

Package pixivgo provides an unofficial Go client for the Pixiv App-API (6.x).

It supports illustration/novel/user queries, search, bookmarks, rankings, image downloads, and optional SNI bypass for restricted networks.

Basic usage: 

client := pixivgo.NewClient()
resp, err := client.Auth(ctx, "your_refresh_token")
if err != nil {
    log.Fatal(err)
}
result, err := client.SearchIllust(ctx, pixivgo.SearchIllustParams{
    Word: "landscape",
})

Index

Constants

This section is empty.

Variables

View Source 
var ErrAuthRequired = errors.New("pixivgo: authentication required; call Auth() or SetAuth() first")

ErrAuthRequired is returned when an API method requires authentication but no access token has been set.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a pointer to the given bool value.

func Int 

func Int(v int) *int

Int returns a pointer to the given int value. Useful for setting optional *int fields in parameter structs.

func ParseNextURL 

func ParseNextURL(nextURL *string) url.Values

ParseNextURL extracts query parameters from a Pixiv next_url pagination string. It handles PHP-style array parameters (e.g., "seed_illust_ids[]" → "seed_illust_ids"). Returns nil if nextURL is nil or empty.

func String 

func String(v string) *string

String returns a pointer to the given string value. Useful for setting optional *string fields in parameter structs.

Types

type AuthResponse 

type AuthResponse struct {
	AccessToken  string   `json:"access_token"`
	ExpiresIn    int      `json:"expires_in"`
	TokenType    string   `json:"token_type"`
	Scope        string   `json:"scope"`
	RefreshToken string   `json:"refresh_token"`
	User         UserInfo `json:"user"`
}

AuthResponse contains the token data from an auth request.

type BookmarkDetail 

type BookmarkDetail struct {
	IsBookmarked bool          `json:"is_bookmarked"`
	Tags         []BookmarkTag `json:"tags"`
	Restrict     string        `json:"restrict"`
}

BookmarkDetail contains bookmark information.

type BookmarkDetailResponse 

type BookmarkDetailResponse struct {
	BookmarkDetail BookmarkDetail `json:"bookmark_detail"`
}

BookmarkDetailResponse is the response from illust_bookmark_detail.

type BookmarkTag 

type BookmarkTag struct {
	Name         string `json:"name"`
	IsRegistered bool   `json:"is_registered"`
}

BookmarkTag contains a bookmark tag with registration status.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the Pixiv App-API client. It is safe for concurrent use after construction.

func NewClient 

func NewClient(opts ...Option) *Client

NewClient creates a new Pixiv API client with the given options.

func (*Client) Auth 

func (c *Client) Auth(ctx context.Context, refreshToken string) (*AuthResponse, error)

Auth authenticates with Pixiv using a refresh token. It stores the resulting access token and refresh token on the client. Password authentication is not supported (deprecated by Pixiv).

func (*Client) Clone 

func (c *Client) Clone() *Client

Clone returns a copy that shares the underlying *http.Client (transport and connection pool) but holds an independent auth token: SetAuth or Auth on one never affects the other. Use it to pin a token for the duration of a request — e.g. a refresh-and-retry that must not race a concurrent SetAuth.

func (*Client) Download 

func (c *Client) Download(ctx context.Context, imageURL string, opts *DownloadOptions) (string, error)

Download downloads an image from the given URL to a file. Returns the path of the saved file.

func (*Client) DownloadToWriter 

func (c *Client) DownloadToWriter(ctx context.Context, imageURL string, w io.Writer) error

DownloadToWriter downloads an image from the given URL and writes it to w.

func (*Client) IllustBookmarkAdd 

func (c *Client) IllustBookmarkAdd(ctx context.Context, params IllustBookmarkAddParams) error

IllustBookmarkAdd adds an illustration to bookmarks. Requires authentication.

func (*Client) IllustBookmarkDelete 

func (c *Client) IllustBookmarkDelete(ctx context.Context, params IllustBookmarkDeleteParams) error

IllustBookmarkDelete removes an illustration from bookmarks. Requires authentication.

func (*Client) IllustBookmarkDetail 

func (c *Client) IllustBookmarkDetail(ctx context.Context, params IllustBookmarkDetailParams) (*BookmarkDetailResponse, error)

IllustBookmarkDetail returns bookmark detail for an illustration.

func (*Client) IllustComments 

func (c *Client) IllustComments(ctx context.Context, params IllustCommentsParams) (*IllustCommentsResponse, error)

IllustComments returns comments on an illustration.

func (*Client) IllustDetail 

func (c *Client) IllustDetail(ctx context.Context, params IllustDetailParams) (*IllustDetailResponse, error)

IllustDetail returns detail information for an illustration.

func (*Client) IllustFollow 

func (c *Client) IllustFollow(ctx context.Context, params IllustFollowParams) (*IllustListResponse, error)

IllustFollow returns new illustrations from followed users. Requires authentication.

func (*Client) IllustNew 

func (c *Client) IllustNew(ctx context.Context, params IllustNewParams) (*IllustListResponse, error)

IllustNew returns the latest illustrations.

func (*Client) IllustRanking 

func (c *Client) IllustRanking(ctx context.Context, params IllustRankingParams) (*IllustListResponse, error)

IllustRanking returns illustration rankings.

func (*Client) IllustRecommended 

func (c *Client) IllustRecommended(ctx context.Context, params IllustRecommendedParams) (*IllustListResponse, error)

IllustRecommended returns recommended illustrations. When NoAuth is true, the no-login endpoint is used.

func (*Client) IllustRelated 

func (c *Client) IllustRelated(ctx context.Context, params IllustRelatedParams) (*IllustListResponse, error)

IllustRelated returns illustrations related to the specified illustration.

func (*Client) NovelComments 

func (c *Client) NovelComments(ctx context.Context, params NovelCommentsParams) (*NovelComments, error)

NovelComments returns comments on a novel.

func (*Client) NovelDetail 

func (c *Client) NovelDetail(ctx context.Context, params NovelDetailParams) (*NovelInfo, error)

NovelDetail returns detail information for a novel.

func (*Client) NovelFollow 

func (c *Client) NovelFollow(ctx context.Context, params NovelFollowParams) (*NovelListResponse, error)

NovelFollow returns new novels from followed users. Requires authentication.

func (*Client) NovelNew 

func (c *Client) NovelNew(ctx context.Context, params NovelNewParams) (*NovelListResponse, error)

NovelNew returns the latest novels.

func (*Client) NovelRecommended 

func (c *Client) NovelRecommended(ctx context.Context, params NovelRecommendedParams) (*NovelListResponse, error)

NovelRecommended returns recommended novels.

func (*Client) NovelSeries 

func (c *Client) NovelSeries(ctx context.Context, params NovelSeriesParams) (*NovelSeriesResponse, error)

NovelSeries returns detail for a novel series.

func (*Client) SearchIllust 

func (c *Client) SearchIllust(ctx context.Context, params SearchIllustParams) (*SearchIllustrations, error)

SearchIllust searches for illustrations by keyword.

func (*Client) SearchNovel 

func (c *Client) SearchNovel(ctx context.Context, params SearchNovelParams) (*SearchNovelResponse, error)

SearchNovel searches for novels by keyword.

func (*Client) SearchUser 

func (c *Client) SearchUser(ctx context.Context, params SearchUserParams) (*UserListResponse, error)

SearchUser searches for users by keyword.

func (*Client) SetAPIProxy 

func (c *Client) SetAPIProxy(proxyHosts string)

SetAPIProxy changes the API base URL (e.g., "http://app-api.pixivlite.com").

func (*Client) SetAcceptLanguage 

func (c *Client) SetAcceptLanguage(lang string)

SetAcceptLanguage sets the Accept-Language header for tag translations.

func (*Client) SetAdditionalHeaders 

func (c *Client) SetAdditionalHeaders(h http.Header)

SetAdditionalHeaders overrides the additional headers for all requests.

func (*Client) SetAuth 

func (c *Client) SetAuth(accessToken string, refreshToken string)

SetAuth manually sets the access token and optionally the refresh token. Use this when you already have valid tokens.

func (*Client) ShowcaseArticle 

func (c *Client) ShowcaseArticle(ctx context.Context, params ShowcaseArticleParams) (*ShowcaseArticleResponse, error)

ShowcaseArticle returns a featured showcase article. This uses the Pixiv Web API (no authentication required).

func (*Client) TrendingTagsIllust 

func (c *Client) TrendingTagsIllust(ctx context.Context, params TrendingTagsIllustParams) (*TrendingTagsResponse, error)

TrendingTagsIllust returns trending tags for illustrations.

func (*Client) UgoiraMetadata 

func (c *Client) UgoiraMetadata(ctx context.Context, params UgoiraMetadataParams) (*UgoiraMetadataResponse, error)

UgoiraMetadata returns metadata for an animated illustration (ugoira).

func (*Client) UserBookmarkTagsIllust 

func (c *Client) UserBookmarkTagsIllust(ctx context.Context, params UserBookmarkTagsIllustParams) (*UserBookmarkTagsResponse, error)

UserBookmarkTagsIllust returns a user's bookmark tags for illustrations.

func (*Client) UserBookmarksIllust 

func (c *Client) UserBookmarksIllust(ctx context.Context, params UserBookmarksIllustParams) (*UserBookmarksIllustrations, error)

UserBookmarksIllust returns a user's bookmarked illustrations.

func (*Client) UserBookmarksNovel 

func (c *Client) UserBookmarksNovel(ctx context.Context, params UserBookmarksNovelParams) (*UserBookmarksNovel, error)

UserBookmarksNovel returns a user's bookmarked novels.

func (*Client) UserDetail 

func (c *Client) UserDetail(ctx context.Context, params UserDetailParams) (*UserInfoDetailed, error)

UserDetail returns detailed information for a user.

func (*Client) UserEditAIShowSettings 

func (c *Client) UserEditAIShowSettings(ctx context.Context, params UserEditAIShowSettingsParams) error

UserEditAIShowSettings toggles the visibility of AI-generated works. Requires authentication.

func (*Client) UserFollowAdd 

func (c *Client) UserFollowAdd(ctx context.Context, params UserFollowAddParams) error

UserFollowAdd follows a user. Requires authentication.

func (*Client) UserFollowDelete 

func (c *Client) UserFollowDelete(ctx context.Context, params UserFollowDeleteParams) error

UserFollowDelete unfollows a user. Requires authentication.

func (*Client) UserFollower 

func (c *Client) UserFollower(ctx context.Context, params UserFollowerParams) (*UserListResponse, error)

UserFollower returns a user's followers.

func (*Client) UserFollowing 

func (c *Client) UserFollowing(ctx context.Context, params UserFollowingParams) (*UserFollowing, error)

UserFollowing returns the users that a user is following.

func (*Client) UserID 

func (c *Client) UserID() string

UserID returns the authenticated user's ID.

func (*Client) UserIllusts 

func (c *Client) UserIllusts(ctx context.Context, params UserIllustsParams) (*UserIllustrations, error)

UserIllusts returns a user's illustrations.

func (*Client) UserList 

func (c *Client) UserList(ctx context.Context, params UserListParams) (*UserListResponse, error)

UserList returns a user's blacklist.

func (*Client) UserMyPixiv 

func (c *Client) UserMyPixiv(ctx context.Context, params UserMyPixivParams) (*UserListResponse, error)

UserMyPixiv returns a user's "My Pixiv" (close friends).

func (*Client) UserNovels 

func (c *Client) UserNovels(ctx context.Context, params UserNovelsParams) (*UserNovels, error)

UserNovels returns a user's novels.

func (*Client) UserRecommended 

func (c *Client) UserRecommended(ctx context.Context, params UserRecommendedParams) (*UserListResponse, error)

UserRecommended returns recommended users.

func (*Client) UserRelated 

func (c *Client) UserRelated(ctx context.Context, params UserRelatedParams) (*UserListResponse, error)

UserRelated returns users related to the specified user.

func (*Client) WebviewNovel 

func (c *Client) WebviewNovel(ctx context.Context, params WebviewNovelParams) (*WebviewNovelResult, error)

WebviewNovel fetches novel content from the webview endpoint. If params.Raw is true, RawHTML is populated. Otherwise, Novel is populated by extracting and parsing JSON from the HTML.

type Comment 

type Comment struct {
	ID            FlexInt      `json:"id"`
	Comment       string       `json:"comment"`
	Date          string       `json:"date"`
	User          *CommentUser `json:"user"`
	ParentComment *Comment     `json:"parent_comment,omitempty"`
}

Comment represents a comment on an illustration or novel.

type CommentUser 

type CommentUser struct {
	ID               FlexInt          `json:"id"`
	Name             string           `json:"name"`
	Account          string           `json:"account"`
	ProfileImageUrls ProfileImageUrls `json:"profile_image_urls"`
}

CommentUser contains user info as it appears in comments.

type DownloadOptions 

type DownloadOptions struct {
	Path    string // directory to save to (default: current directory)
	Name    string // filename override (default: basename from URL)
	Prefix  string // filename prefix
	Replace bool   // overwrite existing files (default: false)
	Referer string // Referer header (default: "https://app-api.pixiv.net/")
}

DownloadOptions controls how images are downloaded.

type Duration 

type Duration string

Duration controls the time range for search results. 

const (
	WithinLastDay   Duration = "within_last_day"
	WithinLastWeek  Duration = "within_last_week"
	WithinLastMonth Duration = "within_last_month"
)

type Filter 

type Filter string

Filter controls platform-specific filtering. 

const (
	FilterForIOS Filter = "for_ios"
	FilterNone   Filter = "none"
)

type FlexInt 

type FlexInt int

FlexInt is an int that can be unmarshaled from both JSON numbers and strings. Pixiv's API is inconsistent: the auth endpoint returns user IDs as strings, while other endpoints return them as integers.

func (FlexInt) Int 

func (fi FlexInt) Int() int

Int returns the underlying int value.

func (FlexInt) MarshalJSON 

func (fi FlexInt) MarshalJSON() ([]byte, error)

func (*FlexInt) UnmarshalJSON 

func (fi *FlexInt) UnmarshalJSON(data []byte) error

type IllustBookmarkAddParams 

type IllustBookmarkAddParams struct {
	IllustID int
	Restrict Restrict
	Tags     []string
	NoAuth   bool
}

IllustBookmarkAddParams are the parameters for IllustBookmarkAdd.

type IllustBookmarkDeleteParams 

type IllustBookmarkDeleteParams struct {
	IllustID int
	NoAuth   bool
}

IllustBookmarkDeleteParams are the parameters for IllustBookmarkDelete.

type IllustBookmarkDetailParams 

type IllustBookmarkDetailParams struct {
	IllustID int
	NoAuth   bool
}

IllustBookmarkDetailParams are the parameters for IllustBookmarkDetail.

type IllustCommentsParams 

type IllustCommentsParams struct {
	IllustID             int
	Offset               *int
	IncludeTotalComments *bool
	NoAuth               bool
}

IllustCommentsParams are the parameters for IllustComments.

type IllustCommentsResponse 

type IllustCommentsResponse struct {
	TotalComments        int       `json:"total_comments"`
	Comments             []Comment `json:"comments"`
	NextURL              *string   `json:"next_url"`
	CommentAccessControl int       `json:"comment_access_control"`
}

IllustCommentsResponse is the response from illust_comments.

type IllustDetailParams 

type IllustDetailParams struct {
	IllustID int
	NoAuth   bool
}

IllustDetailParams are the parameters for IllustDetail.

type IllustDetailResponse 

type IllustDetailResponse struct {
	Illust IllustrationInfo `json:"illust"`
}

IllustDetailResponse is the response from illust_detail.

type IllustFollowParams 

type IllustFollowParams struct {
	Restrict Restrict
	Offset   *int
	NoAuth   bool
}

IllustFollowParams are the parameters for IllustFollow.

type IllustListResponse 

type IllustListResponse struct {
	Illusts []IllustrationInfo `json:"illusts"`
	NextURL *string            `json:"next_url"`
}

IllustListResponse is a generic response containing a list of illustrations. Used by illust_related, illust_recommended, illust_ranking, illust_follow, illust_new.

type IllustNewParams 

type IllustNewParams struct {
	ContentType IllustType
	Filter      Filter
	MaxIllustID *int
	NoAuth      bool
}

IllustNewParams are the parameters for IllustNew.

type IllustRankingParams 

type IllustRankingParams struct {
	Mode   RankingMode
	Filter Filter
	Date   *string // "YYYY-MM-DD"
	Offset *int
	NoAuth bool
}

IllustRankingParams are the parameters for IllustRanking.

type IllustRecommendedParams 

type IllustRecommendedParams struct {
	ContentType                  IllustType
	IncludeRankingLabel          *bool
	Filter                       Filter
	MaxBookmarkIDForRecommend    *int
	MinBookmarkIDForRecentIllust *int
	Offset                       *int
	IncludeRankingIllusts        *bool
	BookmarkIllustIDs            []string
	IncludePrivacyPolicy         *string
	Viewed                       []string
	NoAuth                       bool
}

IllustRecommendedParams are the parameters for IllustRecommended.

type IllustRelatedParams 

type IllustRelatedParams struct {
	IllustID      int
	Filter        Filter
	SeedIllustIDs []string
	Offset        *int
	Viewed        []string
	NoAuth        bool
}

IllustRelatedParams are the parameters for IllustRelated.

type IllustType 

type IllustType string

IllustType is the type of illustration. 

const (
	IllustTypeIllust IllustType = "illust"
	IllustTypeManga  IllustType = "manga"
)

type IllustrationInfo 

type IllustrationInfo struct {
	ID                    FlexInt           `json:"id"`
	Title                 string            `json:"title"`
	Type                  string            `json:"type"`
	ImageUrls             ImageUrls         `json:"image_urls"`
	Caption               string            `json:"caption"`
	Restrict              int               `json:"restrict"`
	User                  UserInfo          `json:"user"`
	Tags                  []IllustrationTag `json:"tags"`
	Tools                 []string          `json:"tools"`
	CreateDate            string            `json:"create_date"`
	PageCount             int               `json:"page_count"`
	Width                 int               `json:"width"`
	Height                int               `json:"height"`
	SanityLevel           int               `json:"sanity_level"`
	XRestrict             int               `json:"x_restrict"`
	Series                *Series           `json:"series"`
	MetaSinglePage        MetaSinglePage    `json:"meta_single_page"`
	MetaPages             []MetaPage        `json:"meta_pages"`
	TotalView             int               `json:"total_view"`
	TotalBookmarks        int               `json:"total_bookmarks"`
	IsBookmarked          bool              `json:"is_bookmarked"`
	Visible               bool              `json:"visible"`
	IsMuted               bool              `json:"is_muted"`
	IllustAIType          int               `json:"illust_ai_type"`
	IllustBookStyle       int               `json:"illust_book_style"`
	TotalComments         *int              `json:"total_comments,omitempty"`
	RestrictionAttributes []string          `json:"restriction_attributes"`
}

IllustrationInfo contains complete illustration details.

type IllustrationTag 

type IllustrationTag struct {
	Name           string  `json:"name"`
	TranslatedName *string `json:"translated_name"`
}

IllustrationTag is a tag on an illustration.

type ImageUrls 

type ImageUrls struct {
	SquareMedium string  `json:"square_medium"`
	Medium       string  `json:"medium"`
	Large        string  `json:"large"`
	Original     *string `json:"original,omitempty"`
}

ImageUrls contains illustration image URLs at various sizes.

Original is only present on per-page image_urls (meta_pages entries); the top-level illust image_urls omits it (single-page works expose the original via MetaSinglePage.OriginalImageURL instead). Hence the pointer + omitempty.

type MetaPage 

type MetaPage struct {
	ImageUrls ImageUrls `json:"image_urls"`
}

MetaPage contains image URLs for multi-page illustrations.

type MetaSinglePage 

type MetaSinglePage struct {
	OriginalImageURL *string `json:"original_image_url,omitempty"`
}

MetaSinglePage contains the original image URL for single-page illustrations.

type NovelComments 

type NovelComments struct {
	TotalComments        int       `json:"total_comments"`
	Comments             []Comment `json:"comments"`
	NextURL              *string   `json:"next_url"`
	CommentAccessControl int       `json:"comment_access_control"`
}

NovelComments is the response from novel_comments.

type NovelCommentsParams 

type NovelCommentsParams struct {
	NovelID              int
	Offset               *int
	IncludeTotalComments *bool
	NoAuth               bool
}

NovelCommentsParams are the parameters for NovelComments.

type NovelDetailParams 

type NovelDetailParams struct {
	NovelID int
	NoAuth  bool
}

NovelDetailParams are the parameters for NovelDetail.

type NovelDetailResponse 

type NovelDetailResponse struct {
	Novel NovelInfo `json:"novel"`
}

NovelDetailResponse wraps the novel_detail endpoint response.

type NovelFollowParams 

type NovelFollowParams struct {
	Restrict Restrict
	Offset   *int
	NoAuth   bool
}

NovelFollowParams are the parameters for NovelFollow.

type NovelInfo 

type NovelInfo struct {
	ID                   FlexInt    `json:"id"`
	Title                string     `json:"title"`
	Caption              string     `json:"caption"`
	Restrict             int        `json:"restrict"`
	XRestrict            int        `json:"x_restrict"`
	IsOriginal           bool       `json:"is_original"`
	ImageUrls            ImageUrls  `json:"image_urls"`
	CreateDate           string     `json:"create_date"`
	Tags                 []NovelTag `json:"tags"`
	PageCount            int        `json:"page_count"`
	TextLength           int        `json:"text_length"`
	User                 UserInfo   `json:"user"`
	Series               *Series    `json:"series"`
	IsBookmarked         bool       `json:"is_bookmarked"`
	TotalBookmarks       int        `json:"total_bookmarks"`
	TotalView            int        `json:"total_view"`
	Visible              bool       `json:"visible"`
	TotalComments        int        `json:"total_comments"`
	IsMuted              bool       `json:"is_muted"`
	IsMyPixivOnly        bool       `json:"is_mypixiv_only"`
	IsXRestricted        bool       `json:"is_x_restricted"`
	NovelAIType          int        `json:"novel_ai_type"`
	CommentAccessControl *int       `json:"comment_access_control,omitempty"`
}

NovelInfo contains complete novel details.

type NovelListResponse 

type NovelListResponse struct {
	Novels  []NovelInfo `json:"novels"`
	NextURL *string     `json:"next_url"`
}

NovelListResponse is a generic response containing a list of novels. Used by novel_recommended, novel_new, novel_follow.

type NovelNavigationInfo 

type NovelNavigationInfo struct {
	ID              FlexInt `json:"id"`
	Viewable        bool    `json:"viewable"`
	ContentOrder    string  `json:"content_order"`
	Title           string  `json:"title"`
	CoverURL        string  `json:"cover_url"`
	ViewableMessage *string `json:"viewable_message"`
}

NovelNavigationInfo contains navigation info within a novel series.

type NovelNewParams 

type NovelNewParams struct {
	Filter     Filter
	MaxNovelID *int
	NoAuth     bool
}

NovelNewParams are the parameters for NovelNew.

type NovelRating 

type NovelRating struct {
	Like     int `json:"like"`
	Bookmark int `json:"bookmark"`
	View     int `json:"view"`
}

NovelRating contains like/bookmark/view counts for a novel.

type NovelRecommendedParams 

type NovelRecommendedParams struct {
	IncludeRankingLabel       *bool
	Filter                    Filter
	Offset                    *int
	IncludeRankingNovels      *bool
	AlreadyRecommended        []string
	MaxBookmarkIDForRecommend *int
	IncludePrivacyPolicy      *string
	NoAuth                    bool
}

NovelRecommendedParams are the parameters for NovelRecommended.

type NovelSeriesParams 

type NovelSeriesParams struct {
	SeriesID  int
	Filter    Filter
	LastOrder *string
	NoAuth    bool
}

NovelSeriesParams are the parameters for NovelSeries.

type NovelSeriesResponse 

type NovelSeriesResponse struct {
	NovelSeriesDetail any         `json:"novel_series_detail"`
	Novels            []NovelInfo `json:"novels"`
	NextURL           *string     `json:"next_url"`
}

NovelSeriesResponse is the response from novel_series.

type NovelTag 

type NovelTag struct {
	Name                string  `json:"name"`
	TranslatedName      *string `json:"translated_name"`
	AddedByUploadedUser bool    `json:"added_by_uploaded_user"`
}

NovelTag is a tag on a novel.

type Option 

type Option func(*Client)

Option configures a Client.

func WithAcceptLanguage 

func WithAcceptLanguage(lang string) Option

WithAcceptLanguage sets the Accept-Language header for tag translations. Common values: "en-us", "zh-cn", "ja".

func WithAdditionalHeaders 

func WithAdditionalHeaders(h http.Header) Option

WithAdditionalHeaders sets additional HTTP headers for all requests.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default API base URL (https://app-api.pixiv.net).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets a custom http.Client for all requests. Use this to inject proxied clients or bypass-configured transports.

type PixivError 

type PixivError struct {
	Message    string
	StatusCode int
	Header     http.Header
	Body       string
	Err        error
}

PixivError represents an error from the Pixiv API or the HTTP transport layer.

func (*PixivError) Error 

func (e *PixivError) Error() string

func (*PixivError) Unwrap 

func (e *PixivError) Unwrap() error

type Profile 

type Profile struct {
	Webpage                    *string `json:"webpage"`
	Gender                     string  `json:"gender"`
	Birth                      string  `json:"birth"`
	BirthDay                   string  `json:"birth_day"`
	BirthYear                  int     `json:"birth_year"`
	Region                     string  `json:"region"`
	AddressID                  int     `json:"address_id"`
	CountryCode                string  `json:"country_code"`
	Job                        string  `json:"job"`
	JobID                      int     `json:"job_id"`
	TotalFollowUsers           int     `json:"total_follow_users"`
	TotalMyPixivUsers          int     `json:"total_mypixiv_users"`
	TotalIllusts               int     `json:"total_illusts"`
	TotalManga                 int     `json:"total_manga"`
	TotalNovels                int     `json:"total_novels"`
	TotalIllustBookmarksPublic int     `json:"total_illust_bookmarks_public"`
	TotalIllustSeries          int     `json:"total_illust_series"`
	TotalNovelSeries           int     `json:"total_novel_series"`
	BackgroundImageURL         string  `json:"background_image_url"`
	TwitterAccount             string  `json:"twitter_account"`
	TwitterURL                 *string `json:"twitter_url"`
	PawooURL                   *string `json:"pawoo_url"`
	IsPremium                  bool    `json:"is_premium"`
	IsUsingCustomProfileImage  bool    `json:"is_using_custom_profile_image"`
}

Profile contains extended user profile details.

type ProfileImageUrls 

type ProfileImageUrls struct {
	Medium string `json:"medium"`
}

ProfileImageUrls contains user profile image URLs.

type ProfilePublicity 

type ProfilePublicity struct {
	Gender    string `json:"gender"`
	Region    string `json:"region"`
	BirthDay  string `json:"birth_day"`
	BirthYear string `json:"birth_year"`
	Job       string `json:"job"`
	Pawoo     bool   `json:"pawoo"`
}

ProfilePublicity contains privacy settings.

type RankingMode 

type RankingMode string

RankingMode is the ranking period/category. 

const (
	ModeDay          RankingMode = "day"
	ModeWeek         RankingMode = "week"
	ModeMonth        RankingMode = "month"
	ModeDayMale      RankingMode = "day_male"
	ModeDayFemale    RankingMode = "day_female"
	ModeWeekOriginal RankingMode = "week_original"
	ModeWeekRookie   RankingMode = "week_rookie"
	ModeDayManga     RankingMode = "day_manga"
	ModeDayR18       RankingMode = "day_r18"
	ModeDayMaleR18   RankingMode = "day_male_r18"
	ModeDayFemaleR18 RankingMode = "day_female_r18"
	ModeWeekR18      RankingMode = "week_r18"
	ModeWeekR18G     RankingMode = "week_r18g"
)

type Restrict 

type Restrict string

Restrict controls public/private visibility. 

const (
	RestrictPublic  Restrict = "public"
	RestrictPrivate Restrict = "private"
)

type SearchIllustParams 

type SearchIllustParams struct {
	Word         string       // required
	SearchTarget SearchTarget // default: PartialMatchForTags
	Sort         Sort         // default: SortDateDesc
	Duration     *Duration
	StartDate    *string // "YYYY-MM-DD"
	EndDate      *string // "YYYY-MM-DD"
	Filter       Filter
	SearchAIType *int // 0 or 1
	Offset       *int
	NoAuth       bool
}

SearchIllustParams are the parameters for SearchIllust.

type SearchIllustrations 

type SearchIllustrations struct {
	Illusts         []IllustrationInfo `json:"illusts"`
	NextURL         *string            `json:"next_url"`
	SearchSpanLimit int                `json:"search_span_limit"`
	ShowAI          bool               `json:"show_ai"`
}

SearchIllustrations is the response from search_illust.

type SearchNovelParams 

type SearchNovelParams struct {
	Word                        string
	SearchTarget                SearchTarget
	Sort                        Sort
	MergePlainKeywordResults    *string // "true" or "false"
	IncludeTranslatedTagResults *string // "true" or "false"
	StartDate                   *string
	EndDate                     *string
	Filter                      *string
	SearchAIType                *int
	Offset                      *int
	NoAuth                      bool
}

SearchNovelParams are the parameters for SearchNovel.

type SearchNovelResponse 

type SearchNovelResponse struct {
	Novels          []NovelInfo `json:"novels"`
	NextURL         *string     `json:"next_url"`
	SearchSpanLimit int         `json:"search_span_limit"`
	ShowAI          bool        `json:"show_ai"`
}

SearchNovelResponse is the response from search_novel.

type SearchTarget 

type SearchTarget string

SearchTarget controls how search queries are matched. 

const (
	PartialMatchForTags SearchTarget = "partial_match_for_tags"
	ExactMatchForTags   SearchTarget = "exact_match_for_tags"
	TitleAndCaption     SearchTarget = "title_and_caption"
	Keyword             SearchTarget = "keyword"
)

type SearchUserParams 

type SearchUserParams struct {
	Word     string
	Sort     Sort
	Duration *Duration
	Filter   Filter
	Offset   *int
	NoAuth   bool
}

SearchUserParams are the parameters for SearchUser.

type Series 

type Series struct {
	ID    FlexInt `json:"id"`
	Title string  `json:"title"`
}

Series contains series information. Pixiv returns {} instead of null for empty series; in that case ID will be 0.

type ShowcaseArticleParams 

type ShowcaseArticleParams struct {
	ShowcaseID int
}

ShowcaseArticleParams are the parameters for ShowcaseArticle.

type ShowcaseArticleResponse 

type ShowcaseArticleResponse struct {
	Body any `json:"body"`
}

ShowcaseArticleResponse is the response from showcase_article.

type Sort 

type Sort string

Sort controls the ordering of search results. 

const (
	SortDateDesc    Sort = "date_desc"
	SortDateAsc     Sort = "date_asc"
	SortPopularDesc Sort = "popular_desc"
)

type TrendTag 

type TrendTag struct {
	Tag            IllustrationTag  `json:"tag"`
	TranslatedName *string          `json:"translated_name"`
	Illust         IllustrationInfo `json:"illust"`
}

TrendTag is a trending tag with a sample illustration.

type TrendingTagsIllustParams 

type TrendingTagsIllustParams struct {
	Filter Filter
	NoAuth bool
}

TrendingTagsIllustParams are the parameters for TrendingTagsIllust.

type TrendingTagsResponse 

type TrendingTagsResponse struct {
	TrendTags []TrendTag `json:"trend_tags"`
}

TrendingTagsResponse is the response from trending_tags_illust.

type UgoiraFrame 

type UgoiraFrame struct {
	File  string `json:"file"`
	Delay int    `json:"delay"`
}

UgoiraFrame contains timing information for a single ugoira frame.

type UgoiraMetadata 

type UgoiraMetadata struct {
	ZipUrls UgoiraZipUrls `json:"zip_urls"`
	Frames  []UgoiraFrame `json:"frames"`
}

UgoiraMetadata contains animated illustration metadata.

type UgoiraMetadataParams 

type UgoiraMetadataParams struct {
	IllustID int
	NoAuth   bool
}

UgoiraMetadataParams are the parameters for UgoiraMetadata.

type UgoiraMetadataResponse 

type UgoiraMetadataResponse struct {
	UgoiraMetadata UgoiraMetadata `json:"ugoira_metadata"`
}

UgoiraMetadataResponse is the response from ugoira_metadata.

type UgoiraZipUrls 

type UgoiraZipUrls struct {
	Medium string `json:"medium"`
}

UgoiraZipUrls contains URLs for ugoira zip files.

type UserBookmarkTag 

type UserBookmarkTag struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

UserBookmarkTag contains a bookmark tag with count.

type UserBookmarkTagsIllustParams 

type UserBookmarkTagsIllustParams struct {
	UserID   int
	Restrict Restrict
	Offset   *int
	NoAuth   bool
}

UserBookmarkTagsIllustParams are the parameters for UserBookmarkTagsIllust.

type UserBookmarkTagsResponse 

type UserBookmarkTagsResponse struct {
	BookmarkTags []UserBookmarkTag `json:"bookmark_tags"`
	NextURL      *string           `json:"next_url"`
}

UserBookmarkTagsResponse is the response from user_bookmark_tags_illust.

type UserBookmarksIllustParams 

type UserBookmarksIllustParams struct {
	UserID        int
	Restrict      Restrict
	Filter        Filter
	MaxBookmarkID *int
	Tag           *string
	NoAuth        bool
}

UserBookmarksIllustParams are the parameters for UserBookmarksIllust.

type UserBookmarksIllustrations 

type UserBookmarksIllustrations struct {
	Illusts []IllustrationInfo `json:"illusts"`
	NextURL *string            `json:"next_url"`
}

UserBookmarksIllustrations is the response from user_bookmarks_illust.

type UserBookmarksNovel 

type UserBookmarksNovel struct {
	Novels  []NovelInfo `json:"novels"`
	NextURL *string     `json:"next_url"`
}

UserBookmarksNovel is the response from user_bookmarks_novel.

type UserBookmarksNovelParams 

type UserBookmarksNovelParams struct {
	UserID        int
	Restrict      Restrict
	Filter        Filter
	MaxBookmarkID *int
	Tag           *string
	NoAuth        bool
}

UserBookmarksNovelParams are the parameters for UserBookmarksNovel.

type UserDetailParams 

type UserDetailParams struct {
	UserID int
	Filter Filter
	NoAuth bool
}

UserDetailParams are the parameters for UserDetail.

type UserEditAIShowSettingsParams 

type UserEditAIShowSettingsParams struct {
	ShowAI bool
	NoAuth bool
}

UserEditAIShowSettingsParams are the parameters for UserEditAIShowSettings.

type UserFollowAddParams 

type UserFollowAddParams struct {
	UserID   int
	Restrict Restrict
	NoAuth   bool
}

UserFollowAddParams are the parameters for UserFollowAdd.

type UserFollowDeleteParams 

type UserFollowDeleteParams struct {
	UserID int
	NoAuth bool
}

UserFollowDeleteParams are the parameters for UserFollowDelete.

type UserFollowerParams 

type UserFollowerParams struct {
	UserID int
	Filter Filter
	Offset *int
	NoAuth bool
}

UserFollowerParams are the parameters for UserFollower.

type UserFollowing 

type UserFollowing struct {
	UserPreviews []UserPreview `json:"user_previews"`
	NextURL      *string       `json:"next_url"`
}

UserFollowing is the response from user_following.

type UserFollowingParams 

type UserFollowingParams struct {
	UserID   int
	Restrict Restrict
	Offset   *int
	NoAuth   bool
}

UserFollowingParams are the parameters for UserFollowing.

type UserIllustrations 

type UserIllustrations struct {
	User    UserInfo           `json:"user"`
	Illusts []IllustrationInfo `json:"illusts"`
	NextURL *string            `json:"next_url"`
}

UserIllustrations is the response from user_illusts.

type UserIllustsParams 

type UserIllustsParams struct {
	UserID int
	Type   IllustType
	Filter Filter
	Offset *int
	NoAuth bool
}

UserIllustsParams are the parameters for UserIllusts.

type UserInfo 

type UserInfo struct {
	ID                   FlexInt          `json:"id"`
	Name                 string           `json:"name"`
	Account              string           `json:"account"`
	ProfileImageUrls     ProfileImageUrls `json:"profile_image_urls"`
	Comment              *string          `json:"comment,omitempty"`
	IsFollowed           *bool            `json:"is_followed"`
	IsAccessBlockingUser *bool            `json:"is_access_blocking_user,omitempty"`
	IsAcceptRequest      *bool            `json:"is_accept_request,omitempty"`
}

UserInfo contains basic user information.

type UserInfoDetailed 

type UserInfoDetailed struct {
	User             UserInfo         `json:"user"`
	Profile          Profile          `json:"profile"`
	ProfilePublicity ProfilePublicity `json:"profile_publicity"`
	Workspace        Workspace        `json:"workspace"`
}

UserInfoDetailed is the response from user_detail.

type UserListParams 

type UserListParams struct {
	UserID int
	Filter Filter
	Offset *int
	NoAuth bool
}

UserListParams are the parameters for UserList.

type UserListResponse 

type UserListResponse struct {
	UserPreviews []UserPreview `json:"user_previews"`
	NextURL      *string       `json:"next_url"`
}

UserListResponse is a generic response containing user previews. Used by user_follower, user_mypixiv, user_list, user_related, user_recommended.

type UserMyPixivParams 

type UserMyPixivParams struct {
	UserID int
	Offset *int
	NoAuth bool
}

UserMyPixivParams are the parameters for UserMyPixiv.

type UserNovels 

type UserNovels struct {
	User    UserInfo    `json:"user"`
	Novels  []NovelInfo `json:"novels"`
	NextURL *string     `json:"next_url"`
}

UserNovels is the response from user_novels.

type UserNovelsParams 

type UserNovelsParams struct {
	UserID int
	Filter Filter
	Offset *int
	NoAuth bool
}

UserNovelsParams are the parameters for UserNovels.

type UserPreview 

type UserPreview struct {
	User    UserInfo           `json:"user"`
	Illusts []IllustrationInfo `json:"illusts"`
	Novels  []NovelInfo        `json:"novels"`
	IsMuted bool               `json:"is_muted"`
}

UserPreview contains a user with sample works.

type UserRecommendedParams 

type UserRecommendedParams struct {
	Filter Filter
	Offset *int
	NoAuth bool
}

UserRecommendedParams are the parameters for UserRecommended.

type UserRelatedParams 

type UserRelatedParams struct {
	SeedUserID int
	Filter     Filter
	Offset     *int
	NoAuth     bool
}

UserRelatedParams are the parameters for UserRelated.

type WebviewNovel 

type WebviewNovel struct {
	ID                 string               `json:"id"`
	Title              string               `json:"title"`
	SeriesID           *string              `json:"seriesId"`
	SeriesTitle        *string              `json:"seriesTitle"`
	SeriesIsWatched    *bool                `json:"seriesIsWatched"`
	UserID             string               `json:"userId"`
	CoverURL           string               `json:"coverUrl"`
	Tags               []string             `json:"tags"`
	Caption            string               `json:"caption"`
	CDate              string               `json:"cdate"`
	Rating             NovelRating          `json:"rating"`
	Text               string               `json:"text"`
	Marker             *string              `json:"marker"`
	Illusts            []string             `json:"illusts"`
	Images             []string             `json:"images"`
	SeriesNavigation   *NovelNavigationInfo `json:"seriesNavigation"`
	GlossaryItems      []string             `json:"glossaryItems"`
	ReplaceableItemIDs []string             `json:"replaceableItemIds"`
	AIType             int                  `json:"aiType"`
	IsOriginal         bool                 `json:"isOriginal"`
}

WebviewNovel contains novel content extracted from webview HTML. Fields use camelCase JSON tags matching the embedded JSON format.

type WebviewNovelParams 

type WebviewNovelParams struct {
	NovelID int
	Raw     bool // if true, returns raw HTML instead of parsed model
	NoAuth  bool
}

WebviewNovelParams are the parameters for WebviewNovel.

type WebviewNovelResult 

type WebviewNovelResult struct {
	Novel   *WebviewNovel
	RawHTML string
}

WebviewNovelResult holds the result of WebviewNovel. Either Novel or RawHTML is set, depending on the Raw parameter.

type Workspace 

type Workspace struct {
	PC                string  `json:"pc"`
	Monitor           string  `json:"monitor"`
	Tool              string  `json:"tool"`
	Scanner           string  `json:"scanner"`
	Tablet            string  `json:"tablet"`
	Mouse             string  `json:"mouse"`
	Printer           string  `json:"printer"`
	Desktop           string  `json:"desktop"`
	Music             string  `json:"music"`
	Desk              string  `json:"desk"`
	Chair             string  `json:"chair"`
	Comment           string  `json:"comment"`
	WorkspaceImageURL *string `json:"workspace_image_url"`
}

Workspace contains user workspace information.

Source Files

View all Source files

Directories

Path Synopsis
Package bypass provides DNS-over-HTTPS resolution and SNI bypass for accessing Pixiv from restricted networks (e.g., behind the GFW).
 Package bypass provides DNS-over-HTTPS resolution and SNI bypass for accessing Pixiv from restricted networks (e.g., behind the GFW).
examples
basic command
download command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.