pixiv

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Jul 19, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Overview

Package pixiv 提供可嵌入 Go 程序的 Pixiv 客户端与稳定模型。

Index

Constants

View Source
const (
	// AuthExportBundleSchema 与 AuthExportBundleVersion 共同标识稳定的认证导出格式。
	AuthExportBundleSchema  = "pixiv-cli.auth-export"
	AuthExportBundleVersion = 1
)

Variables

View Source
var (
	ErrInvalidArgument           error = codeSentinel(CodeInvalidArgument)
	ErrArtworkUnavailable        error = codeSentinel(CodeArtworkUnavailable)
	ErrUnauthorized              error = codeSentinel(CodeUnauthorized)
	ErrForbidden                 error = codeSentinel(CodeForbidden)
	ErrUnsupported               error = codeSentinel(CodeUnsupported)
	ErrRateLimited               error = codeSentinel(CodeRateLimited)
	ErrUpstreamError             error = codeSentinel(CodeUpstreamError)
	ErrUpstreamUnavailable       error = codeSentinel(CodeUpstreamUnavailable)
	ErrMalformedUpstreamResponse error = codeSentinel(CodeMalformedUpstreamResponse)
)

Functions

func BuildLoginAuthorizationURL

func BuildLoginAuthorizationURL(challenge, state string) string

BuildLoginAuthorizationURL 返回官方 App OAuth 登录地址。它供只负责浏览器 交互的 adapter 复用;PKCE verifier 和 state 的生成、校验及 code exchange 仍分别由调用方或 LoginSession 负责。

func EncodeAuthExportBundle added in v0.4.0

func EncodeAuthExportBundle(bundle *AuthExportBundle) ([]byte, error)

EncodeAuthExportBundle 编码稳定的认证导出 JSON,并保留结尾换行。

func IsOfficialOAuthCallbackURL

func IsOfficialOAuthCallbackURL(rawURL string) bool

IsOfficialOAuthCallbackURL 判断 URL 是否为 Pixiv App OAuth 的官方 HTTPS callback;它不解析或暴露 authorization code、state 等 query 内容。

func IsOfficialOAuthStartURL

func IsOfficialOAuthStartURL(rawURL string) bool

IsOfficialOAuthStartURL 判断 post-redirect 的 return_to 是否指向本次 App OAuth start 路由。调用方仍需独立校验它携带的 PKCE challenge。

func OAuthCallbackURLPrefix

func OAuthCallbackURLPrefix() string

OAuthCallbackURLPrefix 返回官方 HTTPS callback 的可扫描 URL 前缀。浏览器 adapter 可据此定位候选 URL,但仍必须使用 IsOfficialOAuthCallbackURL 校验。

Types

type Account

type Account struct {
	UserID   int64  `json:"user_id"`
	Username string `json:"username,omitempty"`
	Default  bool   `json:"default"`
	HasToken bool   `json:"has_token"`
}

Account 是不含 refresh token 的本地账号摘要。

type AccountsResult

type AccountsResult struct {
	DefaultUserID int64     `json:"default_user_id,omitempty"`
	Accounts      []Account `json:"accounts"`
}

AccountsResult 包含当前默认 UID 与不含凭据的账号列表。

type AddBookmarkRequest

type AddBookmarkRequest struct {
	IllustID int64    `json:"illust_id"`
	Restrict Restrict `json:"restrict,omitempty"`
	Tags     []string `json:"tags,omitempty"`
}

AddBookmarkRequest 指定要收藏的作品、可见范围与标签。

type AuthExportBundle added in v0.4.0

type AuthExportBundle struct {
	Schema        string                    `json:"schema"`
	Version       int                       `json:"version"`
	DefaultUserID int64                     `json:"default_user_id"`
	Accounts      []AuthExportSecretAccount `json:"accounts"`
}

AuthExportBundle 是含 opaque refresh-token secret 的版本化认证导出。

func DecodeAuthExportBundle added in v0.4.0

func DecodeAuthExportBundle(body []byte) (*AuthExportBundle, error)

DecodeAuthExportBundle 解码认证导出 JSON。

type AuthExportSecretAccount added in v0.4.0

type AuthExportSecretAccount struct {
	UserID       int64  `json:"user_id"`
	Username     string `json:"username"`
	RefreshToken string `json:"refresh_token"`
}

AuthExportSecretAccount 是认证导出中的账号记录。

RefreshToken 是 opaque secret;调用方不得记录、诊断输出或意外转发此值。

type AuthExportSelection added in v0.4.0

type AuthExportSelection struct {
	UserID int64
	All    bool
}

AuthExportSelection 指定认证导出范围。零值导出本地默认账号;UserID 导出 指定账号;All 导出全部账号。

type AuthRestoreResult added in v0.4.0

type AuthRestoreResult struct {
	DefaultUserID int64     `json:"default_user_id"`
	Added         []Account `json:"added"`
	Updated       []Account `json:"updated"`
}

AuthRestoreResult 汇总 restore 结果;账号摘要不含任何 secret。

type Backend

type Backend string

Backend 标识失败所在的协议边界。

const (
	BackendAppAPI   Backend = "app_api"
	BackendWebAPI   Backend = "web_api"
	BackendOAuth    Backend = "oauth"
	BackendResource Backend = "resource"
)

type Client

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

Client 组合 App API 主数据与显式 Web 补全能力。

func NewClient

func NewClient(options Options) (*Client, error)

NewClient 构造具体客户端;它不会执行网络请求或隐式认证。

func OpenDefault

func OpenDefault(options Options) (*Client, error)

OpenDefault 构造使用本地 auth.json、config.toml 与环境变量的客户端。 它不缓存这些状态:每次公开操作开始时都会取得一次新快照。

func (*Client) AddBookmark

func (c *Client) AddBookmark(ctx context.Context, request AddBookmarkRequest) (err error)

AddBookmark 收藏作品。restrict 省略时使用 public;标签按调用方顺序原样提交。

func (*Client) AuthFilePath

func (c *Client) AuthFilePath() (string, error)

AuthFilePath 返回此 Client 操作账号数据的路径。显式 NewClient 必须提供 AuthFilePath;OpenDefault 会在每次调用时解析现有默认路径。

func (*Client) CheckAccount

func (c *Client) CheckAccount(ctx context.Context, userID int64) (out *Account, err error)

CheckAccount 刷新指定本地账号,验证 UID 不变并保存旋转后的 token。

func (*Client) CheckRefreshToken

func (c *Client) CheckRefreshToken(ctx context.Context, refreshToken string) (out *Account, err error)

CheckRefreshToken 验证一次调用方提供的 refresh token 并返回其身份摘要。它不会读取、 选择、旋转或写入本地 auth store,因此环境变量等临时凭据不能改变默认账号。

func (*Client) CompleteLogin

func (c *Client) CompleteLogin(ctx context.Context, session *LoginSession, callbackOrCode string, options LoginOptions) (out *Account, err error)

CompleteLogin 校验 callback/state,交换 authorization code 并安全保存账号。 callbackOrCode 可为裸 code 或回调 URL;任意非官方 callback URL 必须带匹配 state。

func (*Client) ConfigFilePath

func (c *Client) ConfigFilePath() (string, error)

ConfigFilePath 返回此 Client 操作配置数据的路径。显式 NewClient 必须提供 ConfigFilePath;OpenDefault 会在每次调用时解析现有默认路径。

func (*Client) CurrentUserID

func (c *Client) CurrentUserID(ctx context.Context) (userID int64, err error)

CurrentUserID 返回 OpenDefault 当前认证快照对应的 Pixiv UID。

它为 CLI 等需要将省略的 USER_ID 解释为“我自己”的调用方提供身份边界;不会把 本地默认账号错误地当作显式 refresh token 或环境变量 token 的身份。显式 NewClient 的 access token 不携带可验证 UID,因此返回 unsupported。

func (*Client) Download

func (c *Client) Download(ctx context.Context, ref ResourceRef, destinationPath string) (err error)

Download 将完整资源流式写入同目录临时文件,并在成功后原子替换目标。

func (*Client) ExportAccountRefreshToken added in v0.4.0

func (c *Client) ExportAccountRefreshToken(userID int64) (token string, err error)

ExportAccountRefreshToken 返回本地账号保存的 refresh token。该显式导出操作只 读取 auth store,不应用环境变量或运行时账号优先级,也不会联网、刷新或改写凭据。

func (*Client) ExportAuthBundle added in v0.4.0

func (c *Client) ExportAuthBundle(selection AuthExportSelection) (*AuthExportBundle, error)

ExportAuthBundle 从配置的本地 auth store 取得一次只读快照。

func (*Client) FollowUser

func (c *Client) FollowUser(ctx context.Context, request FollowUserRequest) (err error)

FollowUser 关注用户。restrict 省略时使用 public;它不读取当前关注状态。

func (*Client) FollowingIllusts

func (c *Client) FollowingIllusts(ctx context.Context, request FollowingIllustsRequest) (result *IllustListResult, err error)

FollowingIllusts 返回当前认证账号所关注用户的一个作品批次。

func (*Client) GetConfig

func (c *Client) GetConfig(alias string) (out ConfigValue, err error)

GetConfig 读取 alias 的有效值,包含现有环境变量覆盖规则。

func (*Client) IllustDetail

func (c *Client) IllustDetail(ctx context.Context, id int64) (result *IllustDetail, err error)

IllustDetail 先读取 App API 详情,再用 Web pages 显式补全页面元数据。 App 失败时不会请求 Web;Web 补全失败会直接返回错误。

func (*Client) IllustPages

func (c *Client) IllustPages(ctx context.Context, illustID int64) (result []MetaPage, err error)

IllustPages 返回作品的全部页面元数据;该接口不分页。

func (*Client) IllustRanking

func (c *Client) IllustRanking(ctx context.Context, request IllustRankingRequest) (result *IllustListResult, err error)

IllustRanking 返回一个排行榜上游批次。

func (*Client) IllustRecommended

func (c *Client) IllustRecommended(ctx context.Context, request IllustRecommendedRequest) (result *IllustListResult, err error)

IllustRecommended 返回一个认证推荐作品批次。

func (*Client) IllustRelated

func (c *Client) IllustRelated(ctx context.Context, request IllustRelatedRequest) (result *IllustListResult, err error)

IllustRelated 返回与指定作品相关的一个 App API 批次。

func (*Client) ImportAccount

func (c *Client) ImportAccount(ctx context.Context, refreshToken string) (out *Account, err error)

ImportAccount 刷新给定 refresh token,随后安全保存其旋转后的 token。

func (*Client) ListAccounts

func (c *Client) ListAccounts() (out *AccountsResult, err error)

ListAccounts 返回本地账号的安全摘要。

func (*Client) MangaRecommended

func (c *Client) MangaRecommended(ctx context.Context, request IllustRecommendedRequest) (result *IllustListResult, err error)

MangaRecommended 返回一个认证漫画推荐批次;它与插画推荐使用相同 catalog,但游标互不兼容。

func (*Client) NovelRecommended

func (c *Client) NovelRecommended(ctx context.Context, request NovelRecommendedRequest) (result *NovelListResult, err error)

NovelRecommended 返回一个认证小说推荐批次;其 opaque cursor 不能用于其他推荐种类。

func (*Client) OpenResource

func (c *Client) OpenResource(ctx context.Context, request OpenResourceRequest) (out *ResourceResponse, err error)

OpenResource 打开经 policy 验证的 Pixiv 资源;成功响应的 Body 由调用方关闭。

func (*Client) ParseResourceRef

func (c *Client) ParseResourceRef(rawURL string) (out ResourceRef, err error)

ParseResourceRef 根据 Client 的资源策略解析并验证 URL。

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context) (out *Account, err error)

Refresh 刷新当前默认账号并保存旋转后的 token。

func (*Client) RefreshAccount

func (c *Client) RefreshAccount(ctx context.Context, userID int64) (out *Account, err error)

RefreshAccount 是 Refresh 的显式 UID 变体。

func (*Client) RemoveAccount

func (c *Client) RemoveAccount(userID int64) (err error)

RemoveAccount 删除本地账号;删除默认账号时沿用存储层的确定性提升规则。

func (*Client) RemoveBookmark

func (c *Client) RemoveBookmark(ctx context.Context, request RemoveBookmarkRequest) (err error)

RemoveBookmark 取消收藏作品;它不读取当前收藏状态。

func (*Client) RestoreAuthBundle added in v0.4.0

func (c *Client) RestoreAuthBundle(bundle *AuthExportBundle) (*AuthRestoreResult, error)

RestoreAuthBundle 将已解码的认证导出离线合并到配置的本地 auth store。

func (*Client) SearchIllust

func (c *Client) SearchIllust(ctx context.Context, request SearchIllustRequest) (result *IllustListResult, err error)

SearchIllust 返回一个作品搜索上游批次。

func (*Client) SearchIllustOptions added in v0.4.0

func (c *Client) SearchIllustOptions(ctx context.Context, request SearchIllustOptionsRequest) (result *SearchIllustOptionsResult, err error)

func (*Client) SearchUser

func (c *Client) SearchUser(ctx context.Context, request SearchUserRequest) (result *UserListResult, err error)

SearchUser 返回一个用户搜索上游批次。

func (*Client) SelectAccount

func (c *Client) SelectAccount(userID int64) (err error)

SelectAccount 将已有账号选为默认账号。

func (*Client) SetConfig

func (c *Client) SetConfig(alias, raw string) (out ConfigValue, err error)

SetConfig 校验并私有写入一个现有 alias。

func (*Client) Snapshot

func (c *Client) Snapshot(ctx context.Context) (*Client, error)

Snapshot 取得一次明确的本地配置与认证快照,供一个高层操作内的多个 cursor 请求复用。OpenDefault 的普通公开方法仍各自刷新快照;调用方只有显式 选择本方法时才把同一快照固定在返回 Client 上。

func (*Client) StartLogin

func (c *Client) StartLogin() (out *LoginSession, err error)

StartLogin 创建一次性的程序化登录会话;pkg 不会启动浏览器、loopback server 或 TTY。

func (*Client) TrendingTagsIllust

func (c *Client) TrendingTagsIllust(ctx context.Context) (result *TrendingTagsIllustResult, err error)

TrendingTagsIllust 返回 App API 当前的插画趋势标签。

func (*Client) UgoiraMetadata

func (c *Client) UgoiraMetadata(ctx context.Context, illustID int64) (result *UgoiraMetadataResult, err error)

UgoiraMetadata 以 App 数据为主,并用 Web 的真实 originalSrc 补全原始压缩包 URL。

func (*Client) UnfollowUser

func (c *Client) UnfollowUser(ctx context.Context, request UnfollowUserRequest) (err error)

UnfollowUser 取消关注用户;它不读取当前关注状态。

func (*Client) UnsetConfig

func (c *Client) UnsetConfig(alias string) (out bool, err error)

UnsetConfig 移除一个现有 alias 的文件值;环境覆盖仍会由 GetConfig 显示。

func (*Client) UserArtworks

func (c *Client) UserArtworks(ctx context.Context, request UserArtworksRequest) (result *IllustListResult, err error)

UserArtworks 返回指定用户的一个作品批次。

func (*Client) UserBookmarks

func (c *Client) UserBookmarks(ctx context.Context, request UserBookmarksRequest) (result *IllustListResult, err error)

UserBookmarks 返回指定用户的一个收藏作品批次。

func (*Client) UserBookmarksCursor

func (c *Client) UserBookmarksCursor(ctx context.Context, request UserBookmarksRequest, maxBookmarkID int64) (cursor Cursor, err error)

UserBookmarksCursor 将旧调用方持有的 max_bookmark_id 适配为绑定用户、可见性和 tag 查询的公开 opaque cursor。它不请求上游,也不暴露 cursor 的编码细节;调用方 仍只能把返回值交回 UserBookmarks。

func (*Client) UserDetail

func (c *Client) UserDetail(ctx context.Context, request UserDetailRequest) (result *UserDetailResult, err error)

UserDetail 返回指定用户的稳定完整详情。

func (*Client) UserFollowing

func (c *Client) UserFollowing(ctx context.Context, request UserFollowingRequest) (result *UserListResult, err error)

UserFollowing 返回指定用户关注的一个用户批次。

func (*Client) UserRecommended

func (c *Client) UserRecommended(ctx context.Context, request UserRecommendedRequest) (result *UserRecommendedResult, err error)

UserRecommended 返回一个认证作者推荐批次及对应作品预览。

type ConfigValue

type ConfigValue struct {
	Key      string `json:"key"`
	Value    string `json:"value,omitempty"`
	Source   string `json:"source"`
	HasValue bool   `json:"has_value"`
}

ConfigValue 是一个配置项的安全、可序列化视图。

type Cursor

type Cursor string

Cursor 是版本化、不透明且绑定查询的分页游标;零值表示没有下一批。

type Error

type Error struct {
	Code                    ErrorCode
	Operation               Operation
	Backend                 Backend
	Retryable               bool
	UpstreamStatus          int
	IllustID                int64
	UserID                  int64
	TransportKind           TransportKind
	LocalStateKind          LocalStateKind
	LocalWriteCommitOutcome LocalWriteCommitOutcome
	// contains filtered or unexported fields
}

Error 是公开 SDK 的安全、可分类错误。cause 只保存已脱敏原因。

func (*Error) Error

func (e *Error) Error() string

Error 返回不含上游响应体、URL、header 或凭据的诊断文本。

func (*Error) Is

func (e *Error) Is(target error) bool

Is 让调用方通过稳定 code sentinel 使用 errors.Is。

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap 暴露已验证安全的 cause,并保留 context 取消等标准错误链。

type ErrorCode

type ErrorCode string

ErrorCode 是供调用方稳定分支处理的机器可读错误码。

const (
	CodeInvalidArgument           ErrorCode = "invalid_argument"
	CodeArtworkUnavailable        ErrorCode = "artwork_unavailable"
	CodeUnauthorized              ErrorCode = "unauthorized"
	CodeForbidden                 ErrorCode = "forbidden"
	CodeUnsupported               ErrorCode = "unsupported"
	CodeRateLimited               ErrorCode = "rate_limited"
	CodeUpstreamError             ErrorCode = "upstream_error"
	CodeUpstreamUnavailable       ErrorCode = "upstream_unavailable"
	CodeMalformedUpstreamResponse ErrorCode = "malformed_upstream_response"
)

type FollowUserRequest

type FollowUserRequest struct {
	UserID   int64    `json:"user_id"`
	Restrict Restrict `json:"restrict,omitempty"`
}

FollowUserRequest 指定要关注的用户与可见范围。

type FollowingIllustsRequest

type FollowingIllustsRequest struct {
	Restrict Restrict `json:"restrict,omitempty"`
	Cursor   Cursor   `json:"cursor,omitempty"`
}

type Illust

type Illust struct {
	ID             int64      `json:"id"`
	Title          string     `json:"title"`
	Type           string     `json:"type"`
	PageCount      int        `json:"page_count"`
	TotalBookmarks int        `json:"total_bookmarks"`
	TotalView      int        `json:"total_view"`
	XRestrict      int        `json:"x_restrict"`
	User           User       `json:"user"`
	Tags           []Tag      `json:"tags"`
	ImageURLs      ImageURLs  `json:"image_urls"`
	MetaSinglePage SinglePage `json:"meta_single_page"`
	MetaPages      []MetaPage `json:"meta_pages"`
	AIType         int        `json:"ai_type"`
	CreateDate     string     `json:"create_date"`
	Width          int        `json:"width"`
	Height         int        `json:"height"`
	Tools          []string   `json:"tools"`
}

Illust 是供调用方稳定使用的规范化作品模型。

type IllustDetail

type IllustDetail struct {
	Illust Illust `json:"illust"`
}

IllustDetail 是作品详情响应;保留 Pixiv App API 的 illust envelope。

type IllustListResult

type IllustListResult struct {
	Illusts    []Illust `json:"illusts"`
	NextCursor Cursor   `json:"next_cursor,omitempty"`
}

type IllustRankingRequest

type IllustRankingRequest struct {
	Mode   RankingMode `json:"mode,omitempty"`
	Date   string      `json:"date,omitempty"`
	Cursor Cursor      `json:"cursor,omitempty"`
}

type IllustRecommendedRequest

type IllustRecommendedRequest struct {
	Cursor Cursor `json:"cursor,omitempty"`
}

type IllustRelatedRequest

type IllustRelatedRequest struct {
	IllustID int64  `json:"illust_id"`
	Cursor   Cursor `json:"cursor,omitempty"`
}

type IllustType

type IllustType string
const (
	IllustTypeIllust IllustType = "illust"
	IllustTypeManga  IllustType = "manga"
	IllustTypeUgoira IllustType = "ugoira"
)

type ImageURLs

type ImageURLs struct {
	SquareMedium string `json:"square_medium"`
	Medium       string `json:"medium"`
	Large        string `json:"large"`
	Original     string `json:"original"`
}

ImageURLs 汇集同一页面的标准图片尺寸 URL。

type LocalStateKind added in v0.4.0

type LocalStateKind string

LocalStateKind 标识不携带路径、文件内容或凭据的稳定本地状态失败子类。

const (
	LocalStateKindAuthMalformed    LocalStateKind = "auth_malformed"
	LocalStateKindConfigMalformed  LocalStateKind = "config_malformed"
	LocalStateKindPermissionDenied LocalStateKind = "permission_denied"
	LocalStateKindNotFound         LocalStateKind = "not_found"
	LocalStateKindInvalidProxy     LocalStateKind = "invalid_proxy"
	LocalStateKindAccountMismatch  LocalStateKind = "account_mismatch"
	LocalStateKindUnavailable      LocalStateKind = "unavailable"
	LocalStateKindUnknown          LocalStateKind = "unknown"
)

type LocalWriteCommitOutcome added in v0.4.0

type LocalWriteCommitOutcome string

LocalWriteCommitOutcome 标识本地原子写入失败时 replacement 的提交状态。

const (
	LocalWriteCommitOutcomeUnknown      LocalWriteCommitOutcome = "unknown"
	LocalWriteCommitOutcomeNotCommitted LocalWriteCommitOutcome = "not_committed"
	LocalWriteCommitOutcomeCommitted    LocalWriteCommitOutcome = "committed"
)

type LoginOptions

type LoginOptions struct {
	UseAsDefault bool
}

LoginOptions 控制成功登录后是否选择该账号为默认账号。

type LoginSession

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

LoginSession 是同一进程、同一 Client 绑定的一次性 PKCE 会话。复制这个 小 handle 仍共享同一个会话状态与 one-time gate。

func (*LoginSession) AcceptsCallbackURL

func (s *LoginSession) AcceptsCallbackURL(rawURL string) bool

AcceptsCallbackURL 判断浏览器捕获的 URL 是否携带属于本会话的有效 authorization code。它不返回 code、state 或 verifier,也不标记会话已使用;实际交换仍必须由 CompleteLogin 完成并再次校验。裸 code 不是 URL,不能由 watcher 通过本方法接受。

func (*LoginSession) AuthorizationURL

func (s *LoginSession) AuthorizationURL() string

AuthorizationURL 返回调用方应自行打开或交给浏览器的 Pixiv 授权地址。

func (LoginSession) Format

func (LoginSession) Format(state fmt.State, _ rune)

func (LoginSession) GoString

func (LoginSession) GoString() string

func (LoginSession) String

func (LoginSession) String() string

String、GoString 和 Format 均不暴露 URL、state 或 PKCE verifier;授权 URL 只能通过 AuthorizationURL 这个显式能力取得。

type MetaPage

type MetaPage struct {
	PageIndex int       `json:"page_index"`
	Width     int       `json:"width"`
	Height    int       `json:"height"`
	Extension string    `json:"extension"`
	ImageURLs ImageURLs `json:"image_urls"`
}

MetaPage 是按作品顺序规范化的完整页面元数据。

type Novel

type Novel struct {
	ID             int64     `json:"id"`
	Title          string    `json:"title"`
	Caption        string    `json:"caption"`
	User           User      `json:"user"`
	Tags           []Tag     `json:"tags"`
	ImageURLs      ImageURLs `json:"image_urls"`
	CreateDate     string    `json:"create_date"`
	TotalBookmarks int       `json:"total_bookmarks"`
	TotalView      int       `json:"total_view"`
}

Novel 是小说推荐结果中的稳定必要字段。

type NovelListResult

type NovelListResult struct {
	Novels     []Novel `json:"novels"`
	NextCursor Cursor  `json:"next_cursor,omitempty"`
}

NovelListResult 包含小说推荐批次与仅能续用到该操作的 opaque cursor。

type NovelRecommendedRequest

type NovelRecommendedRequest struct {
	Cursor Cursor `json:"cursor,omitempty"`
}

NovelRecommendedRequest 仅包含本操作的 opaque continuation。

type OpenResourceRequest

type OpenResourceRequest struct {
	Ref             ResourceRef
	Range           string
	IfNoneMatch     string
	IfModifiedSince string
}

OpenResourceRequest 描述 range 或条件资源请求。

type Operation

type Operation string

Operation 标识稳定的公开 SDK 操作。

const (
	OperationIllustDetail        Operation = "illust_detail"
	OperationIllustPages         Operation = "illust_pages"
	OperationIllustRelated       Operation = "illust_related"
	OperationTrendingTagsIllust  Operation = "trending_tags_illust"
	OperationUgoiraMetadata      Operation = "ugoira_metadata"
	OperationSearchIllust        Operation = "search_illust"
	OperationSearchIllustOptions Operation = "search_illust_options"
	OperationIllustRanking       Operation = "illust_ranking"
	OperationIllustRecommended   Operation = "illust_recommended"
	OperationMangaRecommended    Operation = "manga_recommended"
	OperationNovelRecommended    Operation = "novel_recommended"
	OperationUserRecommended     Operation = "user_recommended"
	OperationFollowingIllusts    Operation = "following_illusts"
	OperationSearchUser          Operation = "search_user"
	OperationUserDetail          Operation = "user_detail"
	OperationUserArtworks        Operation = "user_artworks"
	OperationUserBookmarks       Operation = "user_bookmarks"
	OperationUserFollowing       Operation = "user_following"
	OperationAddBookmark         Operation = "add_bookmark"
	OperationRemoveBookmark      Operation = "remove_bookmark"
	OperationFollowUser          Operation = "follow_user"
	OperationUnfollowUser        Operation = "unfollow_user"
	OperationParseResourceRef    Operation = "parse_resource_ref"
	OperationOpenResource        Operation = "open_resource"
	OperationDownload            Operation = "download"
	OperationRefresh             Operation = "refresh"
	OperationImportAccount       Operation = "import_account"
	OperationListAccounts        Operation = "list_accounts"
	OperationSelectAccount       Operation = "select_account"
	OperationRemoveAccount       Operation = "remove_account"
	OperationCheckAccount        Operation = "check_account"
	OperationCheckRefreshToken   Operation = "check_refresh_token"
	OperationConfigGet           Operation = "config_get"
	OperationConfigSet           Operation = "config_set"
	OperationConfigUnset         Operation = "config_unset"
	OperationStartLogin          Operation = "start_login"
	OperationCompleteLogin       Operation = "complete_login"
	OperationCurrentUserID       Operation = "current_user_id"
	OperationSnapshot            Operation = "snapshot"
	OperationExportAuthBundle    Operation = "export_auth_bundle"
	OperationEncodeAuthBundle    Operation = "encode_auth_bundle"
	OperationDecodeAuthBundle    Operation = "decode_auth_bundle"
	OperationRestoreAuthBundle   Operation = "restore_auth_bundle"
)
const OperationExportAccountRefreshToken Operation = "export_account_refresh_token"

type Options

type Options struct {
	// Logger 接收调用方显式注入的诊断 logger;为空时 SDK 严格静默,绝不使用 slog.Default。
	Logger *slog.Logger
	// HTTPClient 同时承载 App、Web、OAuth 与资源请求;为空时 SDK 创建一个
	// 无整请求固定超时的专用 client,请求生命周期由 context 控制。
	HTTPClient *http.Client
	// AppAPIBaseURL 覆盖 App API 地址,主要用于代理与测试。
	AppAPIBaseURL string
	// WebAPIBaseURL 覆盖 Pixiv Web 地址,主要用于页面补全与测试。
	WebAPIBaseURL string
	// AccessToken 是调用 App API 使用的 bearer token。
	AccessToken string
	// RefreshToken 仅供 OpenDefault 的本次快照显式选择;NewClient 不读取它。
	RefreshToken string
	// UserID 仅供 OpenDefault 从本地 auth store 选择账号。
	UserID int64
	// OAuthBaseURL 覆盖 OAuth token endpoint,主要用于测试。
	OAuthBaseURL string
	// AuthFilePath 和 ConfigFilePath 指定本地状态路径。NewClient 不会读取它们;
	// OpenDefault 在为空时使用现有默认路径。
	AuthFilePath   string
	ConfigFilePath string
	// WebFallbackEnabled 允许无 access token 时显式使用匿名 Web API。
	WebFallbackEnabled bool
	// ResourcePolicy 追加调用方显式信任的资源镜像;Pixiv 官方资源规则始终启用。
	ResourcePolicy ResourcePolicy
}

Options 配置 Client 当前所需的传输端点与 App API 身份。

type Profile

type Profile struct {
	Webpage                    *string `json:"webpage,omitempty"`
	Gender                     string  `json:"gender"`
	Birth                      string  `json:"birth"`
	BirthDay                   string  `json:"birth_day"`
	BirthYear                  int     `json:"birth_year"`
	Region                     string  `json:"region"`
	AddressID                  int64   `json:"address_id"`
	CountryCode                string  `json:"country_code"`
	Job                        string  `json:"job"`
	JobID                      int64   `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,omitempty"`
	TwitterAccount             string  `json:"twitter_account"`
	TwitterURL                 *string `json:"twitter_url,omitempty"`
	PawooURL                   *string `json:"pawoo_url,omitempty"`
	IsPremium                  bool    `json:"is_premium"`
	IsUsingCustomProfileImage  bool    `json:"is_using_custom_profile_image"`
}

Profile 是用户公开档案的稳定字段集合;上游未公开数据保持零值。

type ProfileImageURLs

type ProfileImageURLs struct {
	Medium *string `json:"medium,omitempty"`
}

ProfileImageURLs 是用户头像的可选 URL 集合,不与作品 ImageURLs 混用。

type ProfilePublicity

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

ProfilePublicity 表示档案字段的公开状态。

type RankingMode

type RankingMode string
const (
	RankingModeDay          RankingMode = "day"
	RankingModeDayMale      RankingMode = "day_male"
	RankingModeDayFemale    RankingMode = "day_female"
	RankingModeWeek         RankingMode = "week"
	RankingModeWeekOriginal RankingMode = "week_original"
	RankingModeWeekRookie   RankingMode = "week_rookie"
	RankingModeMonth        RankingMode = "month"
)

type RecommendedUserPreview

type RecommendedUserPreview struct {
	User    User     `json:"user"`
	Illusts []Illust `json:"illusts"`
	Novels  []Novel  `json:"novels"`
}

RecommendedUserPreview 只公开用户与可用作品预览,不传递上游排名或 UI 策略字段。

type RemoveBookmarkRequest

type RemoveBookmarkRequest struct {
	IllustID int64 `json:"illust_id"`
}

RemoveBookmarkRequest 指定要取消收藏的作品。

type ResourceMirrorPolicy

type ResourceMirrorPolicy struct {
	Host         string   `json:"host"`
	PathPrefixes []string `json:"path_prefixes"`
}

ResourceMirrorPolicy 以精确 host 与绝对路径前缀限制一个镜像。

type ResourcePolicy

type ResourcePolicy struct {
	Mirrors []ResourceMirrorPolicy `json:"mirrors,omitempty"`
}

ResourcePolicy 声明除 Pixiv 官方资源域名外,调用方显式信任的镜像。

type ResourceRef

type ResourceRef struct {
	URL string `json:"url"`
}

ResourceRef 是可持久化的资源引用;使用前 OpenResource 会再次验证。

type ResourceResponse

type ResourceResponse struct {
	StatusCode int
	Header     http.Header
	Body       io.ReadCloser
}

ResourceResponse 暴露可代理的状态、白名单 header 与未预读响应流。

type Restrict

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

type SearchAIMode added in v0.4.0

type SearchAIMode string
const (
	SearchAIModeAll     SearchAIMode = "all"
	SearchAIModeExclude SearchAIMode = "exclude"
	SearchAIModeOnly    SearchAIMode = "only"
)

type SearchAspectRatio added in v0.4.0

type SearchAspectRatio string
const (
	SearchAspectRatioAll       SearchAspectRatio = "all"
	SearchAspectRatioLandscape SearchAspectRatio = "landscape"
	SearchAspectRatioPortrait  SearchAspectRatio = "portrait"
	SearchAspectRatioSquare    SearchAspectRatio = "square"
)

type SearchContentType added in v0.4.0

type SearchContentType string
const (
	SearchContentTypeAll             SearchContentType = "all"
	SearchContentTypeIllustAndUgoira SearchContentType = "illust-and-ugoira"
	SearchContentTypeIllust          SearchContentType = "illust"
	SearchContentTypeManga           SearchContentType = "manga"
	SearchContentTypeUgoira          SearchContentType = "ugoira"
)

type SearchIllustFilters added in v0.4.0

type SearchIllustFilters struct {
	Rating      SearchRating      `json:"rating,omitempty"`
	ContentType SearchContentType `json:"content_type,omitempty"`
	AIMode      SearchAIMode      `json:"ai_mode,omitempty"`
	AspectRatio SearchAspectRatio `json:"aspect_ratio,omitempty"`
	Resolution  SearchResolution  `json:"resolution,omitempty"`
	Tool        string            `json:"tool,omitempty"`
}

SearchIllustFilters 是独立于 App/Web wire 参数的稳定搜索筛选契约。

type SearchIllustOptionsRequest added in v0.4.0

type SearchIllustOptionsRequest struct {
	Word string `json:"word"`
}

type SearchIllustOptionsResult added in v0.4.0

type SearchIllustOptionsResult struct {
	Tools []string `json:"tools"`
}

type SearchIllustRequest

type SearchIllustRequest struct {
	Word     string              `json:"word"`
	Target   SearchTarget        `json:"search_target,omitempty"`
	Sort     SortMode            `json:"sort,omitempty"`
	Duration string              `json:"duration,omitempty"`
	Cursor   Cursor              `json:"cursor,omitempty"`
	Filters  SearchIllustFilters `json:"filters,omitempty"`
}

type SearchRating added in v0.4.0

type SearchRating string
const (
	SearchRatingAll    SearchRating = "all"
	SearchRatingSFW    SearchRating = "sfw"
	SearchRatingR18    SearchRating = "r18"
	SearchRatingR18G   SearchRating = "r18g"
	SearchRatingMature SearchRating = "mature"
)

type SearchResolution added in v0.4.0

type SearchResolution string

SearchResolution 是插画搜索使用的稳定分辨率档位。

const (
	SearchResolutionAll    SearchResolution = "all"
	SearchResolutionHigh   SearchResolution = "high"
	SearchResolutionMedium SearchResolution = "medium"
	SearchResolutionLow    SearchResolution = "low"
)

type SearchTarget

type SearchTarget string
const (
	SearchTargetPartialMatchForTags SearchTarget = "partial_match_for_tags"
	SearchTargetExactMatchForTags   SearchTarget = "exact_match_for_tags"
	SearchTargetTitleAndCaption     SearchTarget = "title_and_caption"
)

type SearchUserRequest

type SearchUserRequest struct {
	Word   string `json:"word"`
	Cursor Cursor `json:"cursor,omitempty"`
}

type SinglePage

type SinglePage struct {
	OriginalImageURL string `json:"original_image_url"`
}

SinglePage 保留 App API 单页作品的原图字段。

type SortMode

type SortMode string
const (
	SortModeDateDesc SortMode = "date_desc"
	SortModeDateAsc  SortMode = "date_asc"
)

type Tag

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

Tag 是作品标签及其翻译。

type TransportKind added in v0.4.0

type TransportKind string

TransportKind 标识不携带目标地址、证书或凭据的稳定传输失败子类。

const (
	TransportKindDNS               TransportKind = "dns"
	TransportKindTLS               TransportKind = "tls"
	TransportKindProxy             TransportKind = "proxy"
	TransportKindConnectionRefused TransportKind = "connection_refused"
	TransportKindConnectionReset   TransportKind = "connection_reset"
	TransportKindUnknown           TransportKind = "unknown"
)

type TrendTag

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

type TrendingTagsIllustResult

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

type UgoiraFrame

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

type UgoiraMetadata

type UgoiraMetadata struct {
	ZipURLs UgoiraZipURLs `json:"zip_urls"`
	Frames  []UgoiraFrame `json:"frames"`
}

type UgoiraMetadataResult

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

type UgoiraZipURLs

type UgoiraZipURLs struct {
	Medium   string `json:"medium"`
	Original string `json:"original"`
}

type UnfollowUserRequest

type UnfollowUserRequest struct {
	UserID int64 `json:"user_id"`
}

UnfollowUserRequest 指定要取消关注的用户。

type User

type User struct {
	ID               int64            `json:"id"`
	Name             string           `json:"name"`
	Account          string           `json:"account"`
	Comment          string           `json:"comment"`
	IsFollowed       bool             `json:"is_followed"`
	ProfileImageURLs ProfileImageURLs `json:"profile_image_urls"`
}

User 是作品作者的规范化摘要。

type UserArtworksRequest

type UserArtworksRequest struct {
	UserID int64      `json:"user_id"`
	Type   IllustType `json:"type,omitempty"`
	Cursor Cursor     `json:"cursor,omitempty"`
}

type UserBookmarksRequest

type UserBookmarksRequest struct {
	UserID   int64    `json:"user_id"`
	Restrict Restrict `json:"restrict,omitempty"`
	Tag      string   `json:"tag,omitempty"`
	Cursor   Cursor   `json:"cursor,omitempty"`
}

type UserDetailRequest

type UserDetailRequest struct {
	UserID int64 `json:"user_id"`
}

type UserDetailResult

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

UserDetailResult 是用户详情的稳定完整 envelope。

type UserFollowingRequest

type UserFollowingRequest struct {
	UserID   int64    `json:"user_id"`
	Restrict Restrict `json:"restrict,omitempty"`
	Cursor   Cursor   `json:"cursor,omitempty"`
}

type UserListResult

type UserListResult struct {
	UserPreviews []UserPreview `json:"user_previews"`
	NextCursor   Cursor        `json:"next_cursor,omitempty"`
}

type UserPreview

type UserPreview struct {
	User User `json:"user"`
}

UserPreview 是用户列表中的稳定 envelope。

type UserRecommendedRequest

type UserRecommendedRequest struct {
	Cursor Cursor `json:"cursor,omitempty"`
}

UserRecommendedRequest 仅包含本操作的 opaque continuation。

type UserRecommendedResult

type UserRecommendedResult struct {
	UserPreviews []RecommendedUserPreview `json:"user_previews"`
	NextCursor   Cursor                   `json:"next_cursor,omitempty"`
}

UserRecommendedResult 包含作者推荐批次与仅能续用到该操作的 opaque cursor。

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,omitempty"`
}

Workspace 是用户公开工作环境信息;图片 URL 可选。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL