pan123

package module
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 18 Imported by: 0

README

go-123pan

123 云盘开放平台 Go SDK（非官方）

Go Reference CI Release License

简体中文 | English

基于 123 云盘开放平台 官方文档实现的 Go SDK，覆盖全部开放接口：文件管理、上传（V1/V2/秒传）、分享、离线下载、直链、图床、视频转码与第三方 OAuth 授权。

✨ 特性

  • 开箱即用 —— pan123.New(clientID, clientSecret) 即可调用全部接口
  • Token 自动管理 —— 自动获取、缓存、过期前刷新，并发安全（避免触发同 client_id 最多 3 个 token 的踢下线机制）
  • 一行代码上传 —— UploadFile 自动完成 MD5 计算、秒传检测、分片并发上传与轮询
  • 内置限流与重试 —— 按官方 QPS 表做客户端限流，429 自动指数退避重试
  • 完整错误信息 —— 业务错误返回 *APIError（含 code、message、x-traceID），支持 errors.As
  • 全接口覆盖 —— 含 V1 旧版上传、旧版文件列表在内的全部文档接口
  • 零重量级依赖 —— 仅依赖标准库与 golang.org/x/time

📦 安装

go get github.com/okatu-loli/go-123pan

要求 Go 1.22+。

🚀 快速开始

前往 123 云盘开放平台 申请 clientID 与 clientSecret。

package main

import (
	"context"
	"fmt"
	"log"

	pan123 "github.com/okatu-loli/go-123pan"
)

func main() {
	client := pan123.New("your-client-id", "your-client-secret")
	ctx := context.Background()

	// 获取用户信息
	info, err := client.User.Info(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("你好,", info.Nickname)

	// 一行代码上传文件（自动秒传/分片/轮询）
	fileID, err := client.Upload.UploadFromPath(ctx, 0, "/path/to/file.zip")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("上传成功, fileID =", fileID)

	// 列出根目录全部文件（自动翻页）
	files, _ := client.File.ListAll(ctx, 0)
	for _, f := range files {
		fmt.Println(f.Filename)
	}
}

更多可运行示例见 examples/：

示例 说明
quickstart 用户信息 + 文件列表
upload 上传本地文件
download 下载文件到本地
share 创建分享链接
offline 离线下载 + 进度轮询
imagebed 图床上传 + 获取外链

🖥️ 命令行工具

SDK 附带 pan123 CLI，覆盖常用操作：

go install github.com/okatu-loli/go-123pan/cmd/pan123@latest

# 保存凭证（也可用环境变量 PAN123_CLIENT_ID / PAN123_CLIENT_SECRET）
pan123 login -client-id <ID> -client-secret <SECRET>

pan123 whoami                    # 用户信息与空间用量
pan123 ls                        # 列出根目录（可跟目录ID）
pan123 mkdir -parent 0 新目录     # 创建目录
pan123 upload -parent 0 a.zip    # 上传（自动秒传/分片）
pan123 download -o a.zip 123456  # 下载
pan123 rm 123456 123457          # 删除至回收站
pan123 mv -to 789 123456         # 移动
pan123 rename 123456 新名称       # 重命名
pan123 share -pwd 1234 123456    # 创建分享链接
pan123 offline https://…/f.mp4   # 离线下载并等待完成
pan123 link 123456               # 获取直链

access_token 会缓存在系统配置目录（macOS 为 ~/Library/Application Support/pan123/，Linux 为 ~/.config/pan123/）并跨进程复用，避免触发官方同 client_id 最多 3 个 token 的限制。

📚 API 覆盖

完整的「方法 ↔ 官方接口 ↔ 参数说明」对照表见 docs/API.md，逐方法的类型签名与注释见 pkg.go.dev。

服务 说明 主要方法
client.File 文件管理 Mkdir Rename BatchRename Trash Recover RecoverTo Copy AsyncCopy CopyProcess Move Detail Infos List ListAll ListV1 SafeboxID DownloadInfo DownloadTo
client.Upload 文件上传 UploadFile UploadFromPath（高级封装）；V2：Create UploadSlice Complete Domains SingleCreate Sha1Reuse；V1：CreateV1 GetUploadURLV1 PutSliceV1 ListUploadPartsV1 CompleteV1 AsyncResultV1
client.Share 分享管理 Create List Update CreatePaid ListPaid UpdatePaid
client.Offline 离线下载 Download Process
client.User 用户信息 Info
client.Link 直链 Enable Disable URL RefreshCache TrafficLog OfflineLogs SwitchIPBlacklist UpdateIPBlacklist IPBlacklist
client.Oss 图床 UploadFile UploadFromPath（高级封装）Mkdir CreateFile GetUploadURL UploadComplete UploadAsyncResult CopyFromDisk CopyProcess CopyFailList Move Delete Detail List OfflineDownload OfflineProcess
client.Transcode 视频转码 FolderInfo CloudVideoFiles SpaceFiles UploadFromCloudDisk Resolutions Transcode Records Results List Delete DownloadOriginal DownloadM3U8 DownloadTS DownloadAll
client.OAuth 三方授权 AuthURL TokenByCode RefreshToken

⚙️ 配置选项

client := pan123.New(id, secret,
	pan123.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}), // 自定义 HTTP 客户端
	pan123.WithMaxRetries(5),      // 429 限流重试次数（默认 3，0 关闭）
	pan123.WithoutRateLimit(),     // 关闭内置客户端限流
	pan123.WithBaseURL("..."),     // 覆盖接口域名（测试/代理）
)

// 三方挂载应用：使用 OAuth 授权得到的 token
client := pan123.NewWithToken(accessToken)

🧯 错误处理

_, err := client.File.DownloadInfo(ctx, fileID)
var apiErr *pan123.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Code, apiErr.Message, apiErr.TraceID)
}
if pan123.IsRateLimited(err) { /* 请求过于频繁 */ }
if pan123.IsTokenExpired(err) { /* token 失效 */ }

🤝 贡献

欢迎提交 Issue 和 Pull Request！

提交信息请遵循 Conventional Commits（feat:、fix:、docs: 等）——合并到 main 后 CI 会依据提交类型自动发布语义化版本（fix → patch、feat → minor、BREAKING CHANGE → major）。

贡献者
okatu-loli
千石

📄 许可证

MIT

本项目为社区实现，与 123 云盘官方无隶属关系。接口以官方文档为准。

Documentation

Overview

Package pan123 是 123 云盘开放平台（https://www.123pan.com）的非官方 Go SDK。

快速开始： 

client := pan123.New("your-client-id", "your-client-secret")
info, err := client.User.Info(ctx)

SDK 自动管理 access_token 的获取、缓存与过期刷新，并内置官方 QPS 限流与 429 退避重试。

Index

Constants

View Source 
const AuthBaseURL = "https://yun.123pan.com"

AuthBaseURL 是授权页面域名。

View Source 
const DefaultBaseURL = "https://open-api.123pan.com"

DefaultBaseURL 是开放平台的接口域名。

View Source 
const OAuthScope = "user:base,file:all:read,file:all:write"

OAuthScope 是授权固定 scope。

Variables

This section is empty.

Functions

func IsRateLimited 

func IsRateLimited(err error) bool

IsRateLimited 判断错误是否为请求过于频繁（code=429）。

func IsTokenExpired 

func IsTokenExpired(err error) bool

IsTokenExpired 判断错误是否为 access_token 无效（code=401）。

func ShareURL 

func ShareURL(uid int64, shareKey string) string

ShareURL 按官方规则拼接分享页面链接：https://{uid}.share.123pan.cn/123pan/{shareKey}。

参数说明：

  • uid：用户账号 ID，可通过 client.User.Info 返回的 UserInfo.UID 获取。
  • shareKey：分享码，由 Create/CreatePaid 返回（ShareCreateResult.ShareKey）。

该函数仅做字符串拼接，不发起网络请求。

Types

type APIError 

type APIError struct {
	// Code 是响应体中的业务错误码。
	Code int
	// Message 是平台返回的错误描述。
	Message string
	// TraceID 用于联系官方技术支持时定位问题。
	TraceID string
}

APIError 表示开放平台返回的业务错误（响应 code != 0）。

func (*APIError) Error 

func (e *APIError) Error() string

type AccessTokenResult 

type AccessTokenResult struct {
	AccessToken string    `json:"accessToken"`
	ExpiredAt   time.Time `json:"expiredAt"`
}

AccessTokenResult 是获取 access_token 接口的返回。

type BatchRenameResult 

type BatchRenameResult struct {
	// SuccessList 重命名成功的文件列表。
	SuccessList []struct {
		FileID   int64  `json:"fileID"`
		UpdateAt string `json:"updateAt"`
	} `json:"successList"`
	// FailList 重命名失败的文件列表及失败原因。
	FailList []struct {
		FileID  int64  `json:"fileID"`
		Message string `json:"message"`
	} `json:"failList"`
}

BatchRenameResult 是批量重命名的返回（可能为空）。

type Client 

type Client struct {

	// 服务分组
	File      *FileService
	Upload    *UploadService
	Share     *ShareService
	Offline   *OfflineService
	User      *UserService
	Link      *LinkService
	Oss       *OssService
	Transcode *TranscodeService
	OAuth     *OAuthService
	// contains filtered or unexported fields
}

Client 是 123 云盘开放平台的 API 客户端。 通过 New 或 NewWithToken 创建；零值不可用。

func New 

func New(clientID, clientSecret string, opts ...Option) *Client

New 创建客户端。SDK 会在首次调用 API 时自动获取 access_token， 并在过期前自动刷新（并发安全，同一时刻只会发起一次获取请求）。

func NewWithToken 

func NewWithToken(accessToken string, opts ...Option) *Client

NewWithToken 使用已有 access_token 创建客户端（例如三方挂载应用 OAuth 授权得到的 token）。 此模式下 SDK 不会自动刷新 token；过期后请调用 SetToken 更新。

func (*Client) RefreshToken 

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

RefreshToken 强制重新获取 access_token（clientID/clientSecret 模式）。 一般无需手动调用，SDK 会在过期前自动刷新。

func (*Client) SetToken 

func (c *Client) SetToken(token string, expiredAt time.Time)

SetToken 手动设置 access_token 及其过期时间。 传入零值 expiredAt 表示永不主动刷新。

func (*Client) Token 

func (c *Client) Token() string

Token 返回当前持有的 access_token（可能为空或已过期）。

func (*Client) TokenInfo added in v1.1.0 

func (c *Client) TokenInfo() (token string, expiredAt time.Time)

TokenInfo 返回当前持有的 access_token 及其过期时间。 可用于在进程间持久化复用 token（配合 SetToken）， 避免频繁重新获取触发同 client_id 最多 3 个 token 的踢下线机制。

type CopyResult 

type CopyResult struct {
	// SourceFileID 源文件 ID。
	SourceFileID int64 `json:"sourceFileId"`
	// TargetFileID 复制生成的新文件 ID。
	TargetFileID int64 `json:"targetFileId"`
}

CopyResult 是复制单个文件的返回。

type CopyTaskStatus 

type CopyTaskStatus int

CopyTaskStatus 是批量复制任务状态：0-待处理 1-进行中 2-已完成 3-失败。 

const (
	// CopyTaskPending 待处理。
	CopyTaskPending CopyTaskStatus = 0
	// CopyTaskRunning 进行中。
	CopyTaskRunning CopyTaskStatus = 1
	// CopyTaskDone 已完成。
	CopyTaskDone CopyTaskStatus = 2
	// CopyTaskFailed 失败。
	CopyTaskFailed CopyTaskStatus = 3
)

type DeleteMode 

type DeleteMode int

DeleteMode 控制删除转码视频时的删除范围。 

const (
	// DeleteOriginal 仅删除原文件。
	DeleteOriginal DeleteMode = 1
	// DeleteOriginalAndTranscoded 删除原文件及转码后的文件（不可逆）。
	DeleteOriginalAndTranscoded DeleteMode = 2
)

type DeveloperInfo 

type DeveloperInfo struct {
	// StartTime 权益开始时间。
	StartTime string `json:"startTime"`
	// EndTime 权益结束时间。
	EndTime string `json:"endTime"`
}

DeveloperInfo 是开发者权益信息（直链等接口多数需要开通该权益）。

type DownloadAllResult 

type DownloadAllResult struct {
	// IsDownloading 为 true 表示服务端仍在打包，需继续轮询（官方建议间隔 10s）。
	IsDownloading bool `json:"isDownloading"`
	// IsFull 转码空间容量是否已满（满则无法下载）。
	IsFull bool `json:"isFull"`
	// DownloadURL 打包 zip 的下载地址，仅在未满且打包完成时有值。
	DownloadURL string `json:"downloadUrl"`
}

DownloadAllResult 是打包下载全部转码文件接口的返回。

type FileDetail 

type FileDetail struct {
	// FileID 文件 ID。
	FileID int64 `json:"fileID"`
	// Filename 文件名。
	Filename string `json:"filename"`
	// Type 0-文件 1-文件夹。
	Type int `json:"type"`
	// Size 文件大小（字节）；查询文件夹时为文件夹内文件累计大小。
	Size int64 `json:"size"`
	// Etag 文件 MD5。
	Etag string `json:"etag"`
	// Status 文件审核状态，大于 100 为审核驳回文件。
	Status int `json:"status"`
	// ParentFileID 父目录 ID，根目录为 0。
	ParentFileID int64 `json:"parentFileID"`
	// CreateAt 创建时间。
	CreateAt string `json:"createAt"`
	// Trashed 是否在回收站：0-否 1-是。
	Trashed int `json:"trashed"`
}

FileDetail 是单个文件详情。

type FileInfo 

type FileInfo struct {
	// FileID 文件 ID。
	FileID int64 `json:"fileId"`
	// Filename 文件名。
	Filename string `json:"filename"`
	// Type 0-文件 1-文件夹。
	Type int `json:"type"`
	// Size 文件大小（字节）。
	Size int64 `json:"size"`
	// Etag 文件 MD5。
	Etag string `json:"etag"`
	// Status 文件审核状态，大于 100 为审核驳回文件。
	Status int `json:"status"`
	// ParentFileID 父目录 ID，根目录为 0。
	ParentFileID int64 `json:"parentFileId"`
	// Category 文件分类：0-未知 1-音频 2-视频 3-图片。
	Category int `json:"category"`
	// Trashed 是否在回收站：0-否 1-是。
	Trashed int `json:"trashed"`
	// PunishFlag 文件处罚标记，非 0 表示文件被处罚（如违规封禁）。
	PunishFlag int `json:"punishFlag"`
	// S3KeyFlag 文件存储 Key 标识，转存/分享等场景使用。
	S3KeyFlag string `json:"s3KeyFlag"`
	// StorageNode 文件所在存储节点。
	StorageNode string `json:"storageNode"`
	// CreateAt 创建时间，格式如 2006-01-02 15:04:05。
	CreateAt string `json:"createAt"`
	// UpdateAt 更新时间，格式如 2006-01-02 15:04:05。
	UpdateAt string `json:"updateAt"`
}

FileInfo 是 v2 文件列表及多文件详情返回的文件信息。

type FileInfoV1 

type FileInfoV1 struct {
	// FileID 文件 ID。
	FileID int64 `json:"fileID"`
	// Filename 文件名。
	Filename string `json:"filename"`
	// Type 0-文件 1-文件夹。
	Type int `json:"type"`
	// Size 文件大小（字节）。
	Size int64 `json:"size"`
	// Etag 文件 MD5。
	Etag string `json:"etag"`
	// Status 文件审核状态，大于 100 为审核驳回文件。
	Status int `json:"status"`
	// ParentFileID 父目录 ID，根目录为 0。
	ParentFileID int64 `json:"parentFileId"`
	// ParentName 父目录名称。
	ParentName string `json:"parentName"`
	// Category 文件分类：0-未知 1-音频 2-视频 3-图片。
	Category int `json:"category"`
	// CreateAt 创建时间。
	CreateAt string `json:"createAt"`
	// UpdateAt 更新时间。
	UpdateAt string `json:"updateAt"`
	// Thumbnail 缩略图地址（图片/视频等有缩略图时返回）。
	Thumbnail string `json:"thumbnail"`
	// DownloadURL 下载地址（可能为空）。
	DownloadURL string `json:"downloadUrl"`
}

FileInfoV1 是 v1 旧版文件列表的文件信息。

type FileListRequest 

type FileListRequest struct {
	// ParentFileID 文件夹 ID，根目录为 0。
	ParentFileID int64
	// Limit 每页数量，最大 100；0 时默认 100。
	Limit int
	// SearchData 搜索关键字；非空时忽略 ParentFileID 做全局搜索。
	SearchData string
	// SearchMode 0-模糊搜索 1-精准搜索。
	SearchMode int
	// LastFileID 翻页游标，取上一页返回的 LastFileID。
	LastFileID int64
}

FileListRequest 是 v2 文件列表（推荐）的查询参数。

type FileListResult 

type FileListResult struct {
	// LastFileID 为 -1 表示最后一页；否则作为下一页的翻页游标。
	LastFileID int64 `json:"lastFileId"`
	// FileList 当前页的文件列表。
	FileList []FileInfo `json:"fileList"`
}

FileListResult 是 v2 文件列表的返回。

type FileListV1Request 

type FileListV1Request struct {
	// ParentFileID 文件夹 ID，根目录为 0。
	ParentFileID int64
	// Page 页码，从 1 开始。
	Page int
	// Limit 每页数量，最大 100；0 时默认 100。
	Limit int
	// OrderBy 排序字段：file_id、size、file_name；空时默认 file_id。
	OrderBy string
	// OrderDirection 排序方向：asc、desc；空时默认 asc。
	OrderDirection string
	// Trashed 是否查看回收站文件。
	Trashed bool
	// SearchData 搜索关键字。
	SearchData string
}

FileListV1Request 是 v1 旧版文件列表的查询参数。

type FileListV1Result 

type FileListV1Result struct {
	// Total 符合条件的文件总数。
	Total int `json:"total"`
	// FileList 当前页的文件列表。
	FileList []FileInfoV1 `json:"fileList"`
}

FileListV1Result 是 v1 旧版文件列表的返回。

type FileService 

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

FileService 提供文件管理相关接口：目录、重命名、删除/还原、复制、移动、详情、列表、保险箱、下载。

func (*FileService) AsyncCopy 

func (s *FileService) AsyncCopy(ctx context.Context, fileIDs []int64, targetDirID int64) (taskID int64, err error)

AsyncCopy 批量复制文件（异步），返回任务 ID。

接口: POST /api/v1/file/async/copy

参数:

  • fileIDs: 要复制的文件 ID 列表，单级最多 3000 个。
  • targetDirID: 目标目录 ID，复制到根目录时填 0。

提交后接口立即返回，需用 CopyProcess 携带任务 ID 轮询复制进度。

func (*FileService) BatchRename 

func (s *FileService) BatchRename(ctx context.Context, renames map[int64]string) (*BatchRenameResult, error)

BatchRename 批量重命名文件。

接口: POST /api/v1/file/rename

参数:

  • renames: 重命名映射，key 为文件 ID、value 为新文件名，一次最多 30 个。

注意：部分成功部分失败时不会返回错误，需检查返回值中的 FailList。

func (*FileService) Copy 

func (s *FileService) Copy(ctx context.Context, fileID, targetDirID int64) (*CopyResult, error)

Copy 复制单个文件到目标目录（同步接口）。

接口: POST /api/v1/file/copy

参数:

  • fileID: 要复制的文件 ID。
  • targetDirID: 目标目录 ID，复制到根目录时填 0。

批量复制请使用 AsyncCopy。

func (*FileService) CopyProcess 

func (s *FileService) CopyProcess(ctx context.Context, taskID int64) (CopyTaskStatus, error)

CopyProcess 查询批量复制任务进度。

接口: GET /api/v1/file/async/copy/process

参数:

  • taskID: AsyncCopy 返回的任务 ID。

返回任务状态，见 CopyTaskStatus 枚举（0-待处理 1-进行中 2-已完成 3-失败）。

func (*FileService) Detail 

func (s *FileService) Detail(ctx context.Context, fileID int64) (*FileDetail, error)

Detail 获取单个文件详情。

接口: GET /api/v1/file/detail

参数:

  • fileID: 文件 ID。

查询文件夹时返回的 Size 为文件夹累计大小。

func (*FileService) DownloadInfo 

func (s *FileService) DownloadInfo(ctx context.Context, fileID int64) (string, error)

DownloadInfo 获取文件的临时下载直链。

接口: GET /api/v1/file/download_info

参数:

  • fileID: 文件 ID（须为文件，不能是文件夹）。

注意：免费账号每日自用下载流量 1GB，超限返回 code 5113； 文件不存在返回 code 5066。直链有时效性，建议即取即用。

func (*FileService) DownloadTo 

func (s *FileService) DownloadTo(ctx context.Context, fileID int64, w io.Writer) (int64, error)

DownloadTo 获取下载直链并把文件内容写入 w，返回写入的字节数。

接口: GET /api/v1/file/download_info 获取直链后，直接 GET 直链下载

参数:

  • fileID: 文件 ID。
  • w: 文件内容的写入目标。

流量限制与错误码同 DownloadInfo（超流量 5113、文件不存在 5066）。

func (*FileService) Infos 

func (s *FileService) Infos(ctx context.Context, fileIDs []int64) ([]FileInfo, error)

Infos 批量获取文件详情。

接口: POST /api/v1/file/infos

参数:

  • fileIDs: 要查询的文件 ID 列表。

func (*FileService) List 

func (s *FileService) List(ctx context.Context, req *FileListRequest) (*FileListResult, error)

List 获取文件列表（v2 推荐接口，lastFileId 游标翻页）。

接口: GET /api/v2/file/list (QPS 15)

参数:

  • req: 查询参数，见 FileListRequest；为 nil 时按根目录、每页 100 处理。

翻页：返回的 LastFileID 为 -1 表示最后一页，否则填入下一次请求的 req.LastFileID 继续拉取。 注意：结果包含回收站文件，需按 Trashed 字段过滤；ListAll 已代为处理。

func (*FileService) ListAll 

func (s *FileService) ListAll(ctx context.Context, parentFileID int64) ([]FileInfo, error)

ListAll 自动翻页拉取目录下全部文件（已过滤回收站中的文件）。

接口: GET /api/v2/file/list (QPS 15)，内部循环调用 List 直至最后一页

参数:

  • parentFileID: 目录 ID，根目录为 0。

注意：目录下文件很多时会产生多次请求，客户端限流可能使耗时变长。

func (*FileService) ListV1 

func (s *FileService) ListV1(ctx context.Context, req *FileListV1Request) (*FileListV1Result, error)

ListV1 获取文件列表（旧版 v1，page 页码翻页）。官方推荐使用 List（v2）。

接口: GET /api/v1/file/list (QPS 10)

参数:

  • req: 查询参数，见 FileListV1Request；为 nil 时按根目录、第 1 页、 每页 100、file_id 升序处理。

func (*FileService) Mkdir 

func (s *FileService) Mkdir(ctx context.Context, parentID int64, name string) (int64, error)

Mkdir 创建目录，返回新目录 ID。

接口: POST /upload/v1/file/mkdir (QPS 20)

参数:

  • parentID: 父目录 ID，创建到根目录时填 0。
  • name: 目录名，不能与同级目录重名，且不能包含 "\/:*?|>< 等非法字符。

func (*FileService) Move 

func (s *FileService) Move(ctx context.Context, fileIDs []int64, toParentFileID int64) error

Move 批量移动文件到目标目录。

接口: POST /api/v1/file/move (QPS 20)

参数:

  • fileIDs: 要移动的文件 ID 列表，单级最多 100 个。
  • toParentFileID: 目标目录 ID，移动到根目录时填 0。

func (*FileService) Recover 

func (s *FileService) Recover(ctx context.Context, fileIDs []int64) (abnormalFileIDs []int64, err error)

Recover 从回收站恢复文件至原位置。

接口: POST /api/v1/file/recover

参数:

  • fileIDs: 要恢复的文件 ID 列表，一次最多 100 个。

返回父级目录已不存在的异常文件 ID 列表，这些文件可用 RecoverTo 还原到指定目录。

func (*FileService) RecoverTo 

func (s *FileService) RecoverTo(ctx context.Context, fileIDs []int64, parentFileID int64) error

RecoverTo 将回收站文件还原到指定目录。

接口: POST /api/v1/file/recover/by_path

参数:

  • fileIDs: 要还原的文件 ID 列表，一次最多 100 个。
  • parentFileID: 还原目标目录 ID，根目录为 0。

func (*FileService) Rename 

func (s *FileService) Rename(ctx context.Context, fileID int64, newName string) error

Rename 重命名单个文件。

接口: PUT /api/v1/file/name

参数:

  • fileID: 要重命名的文件 ID。
  • newName: 新文件名，须小于 255 字符，不能包含 "\/:*?|>< 等非法字符。

func (*FileService) SafeboxID 

func (s *FileService) SafeboxID(ctx context.Context, password string) (int64, error)

SafeboxID 解锁保险箱并获取保险箱目录 ID。

接口: GET /api/v1/safebox/id

参数:

  • password: 保险箱密码。

返回的目录 ID 可作为 parentFileID 用于列表、上传等接口访问保险箱内容。

func (*FileService) Trash 

func (s *FileService) Trash(ctx context.Context, fileIDs []int64) error

Trash 删除文件至回收站。

接口: POST /api/v1/file/trash

参数:

  • fileIDs: 要删除的文件 ID 列表，一次最多 100 个。

注意：文件进入回收站后仍会出现在 v2 文件列表中（Trashed=1）， 可用 Recover / RecoverTo 恢复；彻底删除需在回收站中操作。

type IPBlacklistStatus 

type IPBlacklistStatus int

IPBlacklistStatus IP 黑名单开关状态。 枚举值：1 启用；2 禁用。 

const (
	// IPBlacklistEnabled 黑名单启用。
	IPBlacklistEnabled IPBlacklistStatus = 1
	// IPBlacklistDisabled 黑名单禁用。
	IPBlacklistDisabled IPBlacklistStatus = 2
)

type LinkService 

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

LinkService 提供直链相关接口：直链空间启停、直链获取、缓存刷新、 流量/离线日志查询、IP 黑名单配置。多数接口需要开通开发者权益。

func (*LinkService) Disable 

func (s *LinkService) Disable(ctx context.Context, folderID int64) (string, error)

Disable 对文件夹禁用直链空间，返回该文件夹的名称。

接口: POST /api/v1/direct-link/disable

参数说明：

  • folderID：要禁用直链空间的文件夹（目录）ID。

注意事项：需要开通开发者权益；禁用后该目录下已生成的直链将失效。

func (*LinkService) Enable 

func (s *LinkService) Enable(ctx context.Context, folderID int64) (string, error)

Enable 对文件夹启用直链空间，返回该文件夹的名称。

接口: POST /api/v1/direct-link/enable

参数说明：

  • folderID：要启用直链空间的文件夹（目录）ID。

注意事项：需要开通开发者权益；启用后该目录下的文件才能通过 URL 获取直链。

func (*LinkService) IPBlacklist 

func (s *LinkService) IPBlacklist(ctx context.Context) (ips []string, status IPBlacklistStatus, err error)

IPBlacklist 获取直链 IP 黑名单列表及当前开关状态。

接口: GET /api/v1/developer/config/forbide-ip/list

返回说明：

  • ips：当前黑名单中的 IPv4 地址列表（上限 2000 个）。
  • status：黑名单开关状态，1 启用；2 禁用。

注意事项：需要开通开发者权益。

func (*LinkService) OfflineLogs 

func (s *LinkService) OfflineLogs(ctx context.Context, pageNum, pageSize int, startHour, endHour string) (*OfflineLogResult, error)

OfflineLogs 分页查询直链离线日志文件列表（按小时打包的 .gz 文件）。

接口: GET /api/v1/direct-link/offline/logs

参数说明：

  • pageNum：页码，从 1 开始。
  • pageSize：每页数量。
  • startHour/endHour：查询时间范围，精确到小时，格式为 "2025010115" （即 yyyyMMddHH）。

注意事项：需要开通开发者权益；离线日志仅可查询最近 30 天的数据， 日志内容需通过条目中的 DownloadURL 自行下载解压。

func (*LinkService) RefreshCache 

func (s *LinkService) RefreshCache(ctx context.Context) error

RefreshCache 全量刷新直链 CDN 缓存。

接口: POST /api/v1/direct-link/cache/refresh

注意事项：需要开通开发者权益；为全量刷新，不支持按文件粒度刷新， 文件内容更新后调用可使 CDN 尽快回源取新内容。

func (*LinkService) SwitchIPBlacklist 

func (s *LinkService) SwitchIPBlacklist(ctx context.Context, status IPBlacklistStatus) (bool, error)

SwitchIPBlacklist 开启或关闭直链 IP 黑名单，返回操作是否完成。

接口: POST /api/v1/developer/config/forbide-ip/switch

参数说明：

  • status：目标开关状态，IPBlacklistEnabled（1 启用）或 IPBlacklistDisabled（2 禁用）。

注意事项：需要开通开发者权益；黑名单条目通过 UpdateIPBlacklist 维护， 仅当状态为启用时黑名单才会生效。

func (*LinkService) TrafficLog 

func (s *LinkService) TrafficLog(ctx context.Context, pageNum, pageSize int, startTime, endTime string) (*TrafficLogResult, error)

TrafficLog 分页查询直链流量消耗明细日志。

接口: GET /api/v1/direct-link/log

参数说明：

  • pageNum：页码，从 1 开始。
  • pageSize：每页数量。
  • startTime/endTime：查询时间范围（闭区间）， 格式为 "2025-01-01 00:00:00"。

注意事项：需要开通开发者权益；流量日志仅可查询最近 3 天的数据， 更早的明细请通过 OfflineLogs 下载离线日志文件。

func (*LinkService) URL 

func (s *LinkService) URL(ctx context.Context, fileID int64) (string, error)

URL 获取文件的直链链接。

接口: GET /api/v1/direct-link/url

参数说明：

  • fileID：文件 ID。前提是该文件所在目录已通过 Enable 启用直链空间， 否则接口会返回错误。

注意事项：需要开通开发者权益；直链访问会消耗直链流量 （剩余流量见 UserInfo.DirectTraffic）。

func (*LinkService) UpdateIPBlacklist 

func (s *LinkService) UpdateIPBlacklist(ctx context.Context, ips []string) error

UpdateIPBlacklist 全量覆盖更新直链 IP 黑名单列表。

接口: POST /api/v1/developer/config/forbide-ip/update

参数说明：

  • ips：黑名单 IP 列表，仅支持 IPv4 地址，最多 2000 个。

注意事项：需要开通开发者权益；本接口为全量覆盖更新， 传入的列表会替换现有全部黑名单条目（追加/删除需先经 IPBlacklist 取回现有列表合并后再提交）。

type OAuthService 

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

OAuthService 提供第三方挂载应用的 OAuth 授权接口。 接入需先通过官方资质审核获得 appId 与 secretId（暂不支持个人开发者）。

func (*OAuthService) AuthURL 

func (s *OAuthService) AuthURL(clientID, redirectURI, state string) string

AuthURL 构造用户授权页面地址（浏览器跳转用，本方法不发起 HTTP 请求）。

接口: GET https://yun.123pan.com/auth（授权页面，域名固定为 yun.123pan.com）

参数:

  • clientID: 应用的 appId。
  • redirectURI: 授权后的回跳地址，须与应用注册的回调地址一致。
  • state: 自定义透传参数，回跳时原样带回，可用于防 CSRF。

注意: scope 固定为 OAuthScope；用户授权后将携带 code（与 state）回跳 redirectURI，随后用 TokenByCode 换取 access_token。

func (*OAuthService) RefreshToken 

func (s *OAuthService) RefreshToken(ctx context.Context, clientID, clientSecret, refreshToken string) (*OAuthToken, error)

RefreshToken 用 refresh_token 刷新令牌。

接口: POST /api/v1/oauth2/access_token (QPS 限制 100 次/分钟)

参数:

  • clientID: 应用的 appId。
  • clientSecret: 应用的 secretId。
  • refreshToken: 上次颁发的 refresh_token（单次有效，有效期 90 天）。

注意: 刷新成功后旧 access_token 立即失效，refresh_token 同时换新（旧值 作废），必须持久化新返回的 RefreshToken，否则后续将无法再次刷新。 该接口返回扁平 JSON，不包裹统一响应结构。

func (*OAuthService) TokenByCode 

func (s *OAuthService) TokenByCode(ctx context.Context, clientID, clientSecret, code, redirectURI string) (*OAuthToken, error)

TokenByCode 用授权 code 换取 access_token。

接口: POST /api/v1/oauth2/access_token (QPS 限制 100 次/分钟)

参数:

  • clientID: 应用的 appId。
  • clientSecret: 应用的 secretId。
  • code: 授权回跳携带的授权码，一次性使用。
  • redirectURI: 必须与应用注册的回调地址一致。

注意: 该接口返回扁平 JSON，不包裹统一响应结构。access_token 有效期见 ExpiresIn（秒）；refresh_token 单次有效、90 天有效期，务必持久化保存。

type OAuthToken 

type OAuthToken struct {
	TokenType   string `json:"token_type"`
	AccessToken string `json:"access_token"`
	// RefreshToken 单次有效，90 天有效期；每次刷新都会返回新的 refresh_token，必须持久化替换旧值。
	RefreshToken string `json:"refresh_token"`
	// ExpiresIn access_token 过期时间（秒）。
	ExpiresIn int64  `json:"expires_in"`
	Scope     string `json:"scope"`
}

OAuthToken 是 OAuth 接口返回的令牌。

type OfflineDownloadRequest 

type OfflineDownloadRequest struct {
	// URL 下载资源地址，仅支持 http/https。
	URL string `json:"url"`
	// FileName 自定义文件名称（可选）。
	FileName string `json:"fileName,omitempty"`
	// DirID 下载到的目标目录 ID（可选）。不支持根目录，
	// 默认下载到名为"来自:离线下载"的目录。
	DirID int64 `json:"dirID,omitempty"`
	// CallBackURL 回调地址（可选）。下载成功或失败时以 POST 通知：
	// {"url":"...","status":0,"failReason":"","fileID":100}，status 0 成功 1 失败。
	CallBackURL string `json:"callBackUrl,omitempty"`
}

OfflineDownloadRequest 是创建离线下载任务的参数。

type OfflineLogEntry 

type OfflineLogEntry struct {
	// ID 日志文件 ID（文档标 string，实际可能返回数字，用 any 兼容）。
	ID any `json:"id"`
	// FileName 日志文件名称。
	FileName string `json:"fileName"`
	// FileSize 日志文件大小（字节）。
	FileSize int64 `json:"fileSize"`
	// LogTimeRange 该日志文件覆盖的时间范围。
	LogTimeRange string `json:"logTimeRange"`
	// DownloadURL 日志文件（.gz）下载地址。
	DownloadURL string `json:"downloadURL"`
}

OfflineLogEntry 是直链离线日志文件条目（按小时打包的 .gz 日志）。

type OfflineLogResult 

type OfflineLogResult struct {
	// Total 日志文件总数。
	Total int64 `json:"total"`
	// List 当前页的日志文件条目。
	List []OfflineLogEntry `json:"list"`
}

OfflineLogResult 是直链离线日志的返回。

type OfflineProcessResult 

type OfflineProcessResult struct {
	// Process 下载进度百分比（0-100）；下载失败时会归零。
	Process float64 `json:"process"`
	// Status 任务状态：0 进行中；1 下载失败；2 下载成功；3 重试中。
	Status OfflineStatus `json:"status"`
}

OfflineProcessResult 是离线下载进度。

type OfflineService 

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

OfflineService 提供离线下载相关接口：创建离线下载任务并查询任务进度。

func (*OfflineService) Download 

func (s *OfflineService) Download(ctx context.Context, req *OfflineDownloadRequest) (taskID int64, err error)

Download 创建离线下载任务，返回任务 ID（可用于 Process 查询进度）。

接口: POST /api/v1/offline/download

参数说明（见 OfflineDownloadRequest 各字段）：

  • URL：下载资源地址，必填，仅支持 http/https 协议。
  • FileName：自定义文件名称，可选。
  • DirID：下载到的目标目录 ID，可选；不支持根目录， 不填时默认下载到名为"来自:离线下载"的目录。
  • CallBackURL：回调地址，可选；任务结束（成功或失败）时以 POST 通知， 回调体形如 {"url":"...","status":0,"failReason":"","fileID":100}， 其中 status 0 成功、1 失败。

注意事项：接口返回成功仅表示任务创建成功，下载结果需通过 Process 轮询或回调地址获知。

func (*OfflineService) Process 

func (s *OfflineService) Process(ctx context.Context, taskID int64) (*OfflineProcessResult, error)

Process 查询离线下载任务的进度与状态。

接口: GET /api/v1/offline/download/process

参数说明：

  • taskID：离线下载任务 ID，由 Download 返回。

注意事项：应以 Status 判断任务结果，不能仅凭 Process 判断—— 失败时 Process 会归零；Status 为 3（重试中）时任务仍未终结， 需要继续轮询直至变为 1（失败）或 2（成功）。

type OfflineStatus 

type OfflineStatus int

OfflineStatus 离线下载状态。 枚举值：0 进行中；1 下载失败；2 下载成功；3 重试中。 其中 3（重试中）不是终态，任务仍可能转为成功或失败。 

const (
	// OfflineRunning 进行中。
	OfflineRunning OfflineStatus = 0
	// OfflineFailed 下载失败（终态）。
	OfflineFailed OfflineStatus = 1
	// OfflineSuccess 下载成功（终态）。
	OfflineSuccess OfflineStatus = 2
	// OfflineRetrying 重试中，仍未终结。
	OfflineRetrying OfflineStatus = 3
)

type Option 

type Option func(*Client)

Option 配置 Client。

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL 覆盖接口域名（用于测试或代理网关）。

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient 使用自定义 *http.Client（超时、代理等）。

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries 设置遇到限流（code=429）时的最大重试次数，0 表示不重试。

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent 设置请求 User-Agent。

func WithoutRateLimit 

func WithoutRateLimit() Option

WithoutRateLimit 关闭内置的客户端 QPS 限流。

type OssAsyncResult 

type OssAsyncResult struct {
	// Completed 为 false 时至少间隔 1 秒再轮询。
	Completed bool   `json:"completed"`
	FileID    string `json:"fileID"`
}

OssAsyncResult 是图床异步轮询上传结果的返回。

type OssCopyFailResult 

type OssCopyFailResult struct {
	Total int64 `json:"total"`
	List  []struct {
		FileID   int64  `json:"fileId"`
		Filename string `json:"filename"`
	} `json:"list"`
}

OssCopyFailResult 是复制失败文件列表的返回。

type OssCopyStatus 

type OssCopyStatus int

OssCopyStatus 复制任务状态：1 进行中，2 结束，3 失败，4 等待。 

const (
	OssCopyRunning OssCopyStatus = 1
	OssCopyDone    OssCopyStatus = 2
	OssCopyFailed  OssCopyStatus = 3
	OssCopyWaiting OssCopyStatus = 4
)

type OssCreateResult 

type OssCreateResult struct {
	// FileID 秒传成功时返回的文件 ID。
	FileID string `json:"fileID"`
	// PreuploadID 预上传 ID（Reuse 为 true 时不存在）。
	PreuploadID string `json:"preuploadID"`
	// Reuse 为 true 表示秒传成功。
	Reuse bool `json:"reuse"`
	// SliceSize 分片大小，必须按此大小切分。
	SliceSize int64 `json:"sliceSize"`
}

OssCreateResult 是图床创建文件（预上传）的返回。

type OssFile 

type OssFile struct {
	FileID   string `json:"fileId"`
	Filename string `json:"filename"`
	// Type 0-文件 1-文件夹。
	Type int    `json:"type"`
	Size int64  `json:"size"`
	Etag string `json:"etag"`
	// Status 文件审核状态，大于 100 为审核驳回文件。
	Status   int    `json:"status"`
	CreateAt string `json:"createAt"`
	UpdateAt string `json:"updateAt"`
	// DownloadURL 图片下载/外链地址。
	DownloadURL string `json:"downloadURL"`
	// UserSelfURL 自定义域名链接。
	UserSelfURL string `json:"userSelfURL"`
	// TotalTraffic 流量统计（字节）。
	TotalTraffic   int64  `json:"totalTraffic"`
	ParentFileID   string `json:"parentFileId"`
	ParentFilename string `json:"parentFilename"`
	// Extension 后缀名，如 jpg。
	Extension string `json:"extension"`
}

OssFile 是图床文件信息。

type OssListRequest 

type OssListRequest struct {
	// ParentFileID 父目录 ID，空表示根目录。
	ParentFileID string `json:"parentFileId,omitempty"`
	// Limit 每页数量，最大 100。
	Limit int `json:"limit"`
	// StartTime/EndTime 按创建时间筛选（Unix 时间戳，可选）。
	StartTime int64 `json:"startTime,omitempty"`
	EndTime   int64 `json:"endTime,omitempty"`
	// LastFileID 翻页游标，取上一页返回值；返回 "-1" 表示最后一页。
	LastFileID string `json:"lastFileId,omitempty"`
}

OssListRequest 是图片列表的查询参数。

type OssListResult 

type OssListResult struct {
	// LastFileID 为 "-1" 表示最后一页。
	LastFileID string    `json:"lastFileId"`
	FileList   []OssFile `json:"fileList"`
}

OssListResult 是图片列表的返回。

type OssService 

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

OssService 提供图床相关接口：目录/图片上传、云盘图片复制、移动、删除、 图片信息查询、离线迁移。注意：图床的文件/目录 ID 为字符串类型。

func (*OssService) CopyFailList 

func (s *OssService) CopyFailList(ctx context.Context, taskID string, page, limit int) (*OssCopyFailResult, error)

CopyFailList 分页查询复制失败的文件列表。

接口: GET /api/v1/oss/source/copy/fail

参数:

  • taskID: CopyFromDisk 返回的任务 ID。
  • page: 页码，从 1 开始。
  • limit: 每页数量，最大 100。

func (*OssService) CopyFromDisk 

func (s *OssService) CopyFromDisk(ctx context.Context, fileIDs []int64, toParentFileID string) (taskID string, err error)

CopyFromDisk 创建"复制云盘图片到图床"任务，返回任务 ID。

接口: POST /api/v1/oss/source/copy

参数:

  • fileIDs: 云盘文件/目录 ID（int64，与图床的字符串 ID 不同），一次最多 100 个。
  • toParentFileID: 图床目标目录 ID（字符串），空字符串表示图床根目录。

注意: 并发任务上限 3 个；单任务图片总数上限 1000 张；单图上限 100M。 任务进度用 CopyProcess 查询，失败明细用 CopyFailList 查询。

func (*OssService) CopyProcess 

func (s *OssService) CopyProcess(ctx context.Context, taskID string) (OssCopyStatus, string, error)

CopyProcess 查询复制任务的状态与失败原因。

接口: GET /api/v1/oss/source/copy/process

参数:

  • taskID: CopyFromDisk 返回的任务 ID。

注意: 状态枚举见 OssCopyStatus：1 进行中、2 结束、3 失败、4 等待； 失败时可用 CopyFailList 分页获取失败文件明细。

func (*OssService) CreateFile 

func (s *OssService) CreateFile(ctx context.Context, parentFileID, filename, etag string, size int64) (*OssCreateResult, error)

CreateFile 图床创建文件（预上传），是图床上传流程的第一步。

接口: POST /upload/v1/oss/file/create

参数:

  • parentFileID: 图床父目录 ID（字符串），空字符串表示根目录。
  • filename: 文件名，仅支持 png/gif/jpeg/tiff/webp/jpg/tif/svg/bmp 格式。
  • etag: 文件内容的 MD5（十六进制字符串）。
  • size: 文件大小，单位字节，单图上限 100M。

注意: 返回 Reuse 为 true 表示秒传成功，无需再上传分片。相同 etag+size 视为同一张图片，重复上传会覆盖。上传流程与云盘 V1 相同： CreateFile → GetUploadURL（逐片预签名）→ PUT 二进制 → UploadComplete。

func (*OssService) Delete 

func (s *OssService) Delete(ctx context.Context, fileIDs []string) error

Delete 批量删除图床图片。

接口: POST /api/v1/oss/file/delete

参数:

  • fileIDs: 图床文件 ID 列表（字符串），一次最多 100 个。

func (*OssService) Detail 

func (s *OssService) Detail(ctx context.Context, fileID string) (*OssFile, error)

Detail 获取单张图床图片的详情。

接口: GET /api/v1/oss/file/detail

参数:

  • fileID: 图床文件 ID（字符串）。

func (*OssService) GetUploadURL 

func (s *OssService) GetUploadURL(ctx context.Context, preuploadID string, sliceNo int64) (string, error)

GetUploadURL 获取图床分片的预签名上传地址。

接口: POST /upload/v1/oss/file/get_upload_url

参数:

  • preuploadID: CreateFile 返回的预上传 ID。
  • sliceNo: 分片序号，从 1 开始；分片须严格按 CreateFile 返回的 SliceSize 切分。

注意: 获取后向该地址直接 PUT 分片二进制，不携带任何鉴权头 （可复用 Upload.PutSliceV1）。

func (*OssService) List 

func (s *OssService) List(ctx context.Context, req *OssListRequest) (*OssListResult, error)

List 获取图床图片列表，使用 lastFileId 游标翻页。

接口: POST /api/v1/oss/file/list

参数:

  • req: 查询参数，见 OssListRequest；为 nil 时查询根目录，Limit 未设置时默认 100（上限）。

注意: 游标为字符串类型（与云盘不同）；返回的 LastFileID 为 "-1" 表示已到 最后一页，否则将其回传到下一页请求的 LastFileID 继续翻页。

func (*OssService) Mkdir 

func (s *OssService) Mkdir(ctx context.Context, parentID, name string) (string, error)

Mkdir 创建图床目录，返回新目录 ID。

接口: POST /upload/v1/oss/file/mkdir

参数:

  • parentID: 父目录 ID（图床 ID 为字符串类型，与云盘的 int64 不同），空字符串表示根目录。
  • name: 目录名称。

注意: 返回的目录 ID 同样为字符串类型，可作为后续上传、移动等操作的父目录 ID。

func (*OssService) Move 

func (s *OssService) Move(ctx context.Context, fileIDs []string, toParentFileID string) error

Move 批量移动图床图片到目标目录。

接口: POST /api/v1/oss/file/move

参数:

  • fileIDs: 图床文件 ID 列表（字符串），单级最多 100 个。
  • toParentFileID: 目标目录 ID（字符串），不能为空。

func (*OssService) OfflineDownload 

func (s *OssService) OfflineDownload(ctx context.Context, req *OfflineDownloadRequest) (taskID int64, err error)

OfflineDownload 创建图床离线迁移任务（从 URL 拉取图片到图床），返回任务 ID。

接口: POST /api/v1/oss/offline/download

参数:

  • req: 任务参数。URL 为图片直链，仅支持 http/https；FileName 可选，自定义 保存文件名；DirID 可选，目标图床目录 ID（0 表示根目录）；CallBackURL 可选， 任务完成后的回调通知地址。

注意: 仅支持 png/gif/jpeg/tiff/webp/jpg/tif/svg/bmp 格式，单图上限 100M； 任务进度用 OfflineProcess 查询。

func (*OssService) OfflineProcess 

func (s *OssService) OfflineProcess(ctx context.Context, taskID int64) (*OfflineProcessResult, error)

OfflineProcess 查询图床离线迁移任务的进度。

接口: GET /api/v1/oss/offline/download/process

参数:

  • taskID: OfflineDownload 返回的任务 ID。

注意: 状态枚举与云盘离线下载一致：0 进行中、1 失败、2 成功、3 重试中。

func (*OssService) UploadAsyncResult 

func (s *OssService) UploadAsyncResult(ctx context.Context, preuploadID string) (*OssAsyncResult, error)

UploadAsyncResult 图床异步轮询获取上传最终结果。

接口: POST /upload/v1/oss/file/upload_async_result

参数:

  • preuploadID: CreateFile 返回的预上传 ID。

注意: Completed 为 false 表示尚未完成，需继续轮询，间隔至少 1 秒。

func (*OssService) UploadComplete 

func (s *OssService) UploadComplete(ctx context.Context, preuploadID string) (*OssUploadCompleteResult, error)

UploadComplete 通知图床所有分片上传完毕。

接口: POST /upload/v1/oss/file/upload_complete

参数:

  • preuploadID: CreateFile 返回的预上传 ID。

注意: 返回 Async 为 true 时服务端仍在异步处理，需调用 UploadAsyncResult 轮询最终结果（轮询间隔至少 1 秒）；否则可直接使用返回的 FileID。

func (*OssService) UploadFile 

func (s *OssService) UploadFile(ctx context.Context, parentFileID, filename string, r io.ReaderAt, size int64) (string, error)

UploadFile 上传图片到图床，返回文件 ID。

组合流程: 内部依次调用 CreateFile → GetUploadURL（逐片）→ PUT 分片 → UploadComplete（必要时 UploadAsyncResult 每秒轮询），无单独 HTTP 接口。

参数:

  • parentFileID: 图床父目录 ID（字符串），空字符串表示根目录。
  • filename: 文件名，仅支持 png/gif/jpeg/tiff/webp/jpg/tif/svg/bmp 格式。
  • r: 文件内容，需支持随机读（MD5 计算与分片上传会多次读取）。
  • size: 文件大小，单位字节，单图上限 100M。

注意: 秒传（Reuse）命中时直接返回已有的 FileID，不再上传分片； 相同 etag+size 视为同一张图片，重复上传会覆盖。

func (*OssService) UploadFromPath 

func (s *OssService) UploadFromPath(ctx context.Context, parentFileID, path string) (string, error)

UploadFromPath 上传本地图片到图床，返回文件 ID。

组合流程: 内部依次调用 CreateFile → GetUploadURL（逐片）→ PUT 分片 → UploadComplete（必要时 UploadAsyncResult 每秒轮询），无单独 HTTP 接口。

参数:

  • parentFileID: 图床父目录 ID（字符串），空字符串表示根目录。
  • path: 本地文件路径，文件名取路径的最后一段。

注意: 自动完成 MD5 计算与秒传检测；仅支持 png/gif/jpeg/tiff/webp/jpg/tif/svg/bmp 格式，单图上限 100M；相同 etag+size 视为同一张图片，重复上传会覆盖。

type OssUploadCompleteResult 

type OssUploadCompleteResult struct {
	FileID string `json:"fileID"`
	// Async 为 true 时需调用 UploadAsyncResult 轮询最终结果。
	Async     bool `json:"async"`
	Completed bool `json:"completed"`
}

OssUploadCompleteResult 是图床上传完毕的返回。

type PaidShareCreateRequest 

type PaidShareCreateRequest struct {
	// ShareName 分享链接名称，小于 35 字符且不含特殊字符。
	ShareName string
	// FileIDs 分享的文件 ID 列表，最多 100 个。
	FileIDs []int64
	// PayAmount 付费金额（整数元），1-1000。
	PayAmount int
	// IsReward 是否开启打赏：0 否，1 是。
	IsReward int
	// ResourceDesc 资源描述（可选）。
	ResourceDesc string
	// TrafficSwitch 分享提取流量包开关（可选）。
	TrafficSwitch TrafficSwitch
	// TrafficLimitSwitch 流量限制开关（可选）。
	TrafficLimitSwitch int
	// TrafficLimit 限制流量，单位字节（可选）。
	TrafficLimit int64
}

PaidShareCreateRequest 是创建付费分享链接的参数。

type ResolutionsResult 

type ResolutionsResult struct {
	// IsGetResolution 为 true 表示服务端仍在解析，需继续轮询（官方建议间隔 10s）。
	IsGetResolution bool `json:"IsGetResolution"`
	// Resolutions 可转码的分辨率，逗号分隔，如 "480p,720p,1080p"。
	Resolutions string `json:"Resolutions"`
	// NowOrFinishedResolutions 正在或已完成转码的分辨率；转码时应排除，避免重复转码。
	NowOrFinishedResolutions string `json:"NowOrFinishedResolutions"`
	// CodecNames 编码方式，如 "H.264"。
	CodecNames string `json:"CodecNames"`
	// VideoTime 视频时长，单位秒。
	VideoTime int64 `json:"VideoTime"`
}

ResolutionsResult 是获取可转码分辨率接口的返回。

type Sha1ReuseResult 

type Sha1ReuseResult struct {
	// FileID 秒传成功后的文件 ID（Reuse 为 true 时有效）。
	FileID int64 `json:"fileID"`
	// Reuse 为 true 表示秒传成功。
	Reuse bool `json:"reuse"`
}

Sha1ReuseResult 是 sha1 秒传的返回。

type ShareCreateRequest 

type ShareCreateRequest struct {
	// ShareName 分享链接名称。
	ShareName string `json:"shareName"`
	// ShareExpire 有效期天数，枚举：1、7、30、0（0 为永久）。
	ShareExpire int `json:"shareExpire"`
	// FileIDs 分享的文件 ID 列表，最多 100 个。
	FileIDs []int64 `json:"-"`
	// SharePwd 提取码（可选）。
	SharePwd string `json:"sharePwd,omitempty"`
	// TrafficSwitch 分享提取流量包开关（可选）。
	TrafficSwitch TrafficSwitch `json:"trafficSwitch,omitempty"`
	// TrafficLimitSwitch 流量限制开关：1 关闭限制；2 打开限制（可选）。
	TrafficLimitSwitch int `json:"trafficLimitSwitch,omitempty"`
	// TrafficLimit 限制流量，单位字节（可选）。
	TrafficLimit int64 `json:"trafficLimit,omitempty"`
}

ShareCreateRequest 是创建分享链接的参数。

type ShareCreateResult 

type ShareCreateResult struct {
	// ShareID 分享链接 ID，用于后续修改分享设置。
	ShareID int64 `json:"shareID"`
	// ShareKey 分享码，可配合 ShareURL 拼接完整分享页面链接。
	ShareKey string `json:"shareKey"`
}

ShareCreateResult 是创建分享链接的返回。

type ShareInfo 

type ShareInfo struct {
	ShareID   int64  `json:"shareId"`
	ShareKey  string `json:"shareKey"`
	ShareName string `json:"shareName"`
	// Expiration 过期时间。
	Expiration string `json:"expiration"`
	// Expired 是否失效：0 未失效；1 失效。
	Expired int `json:"expired"`
	// SharePwd 提取码，空字符串表示公开分享。
	SharePwd string `json:"sharePwd"`
	// TrafficSwitch 分享提取流量包开关：1 全部关闭；2 打开游客免登录提取；3 打开超流量用户提取；4 全部开启。
	TrafficSwitch int `json:"trafficSwitch"`
	// TrafficLimitSwitch 流量限制开关：1 关闭限制；2 打开限制。
	TrafficLimitSwitch int `json:"trafficLimitSwitch"`
	// TrafficLimit 限制流量上限（字节）。
	TrafficLimit int64 `json:"trafficLimit"`
	// BytesCharge 分享已使用流量（字节）。
	BytesCharge int64 `json:"bytesCharge"`
	// PreviewCount 预览次数。
	PreviewCount int64 `json:"previewCount"`
	// DownloadCount 下载次数。
	DownloadCount int64 `json:"downloadCount"`
	// SaveCount 转存次数。
	SaveCount int64 `json:"saveCount"`
	// PayAmount 付费金额（元）。以下字段仅付费分享返回。
	PayAmount float64 `json:"payAmount"`
	// Amount 分享收益（元）。
	Amount float64 `json:"amount"`
	// OrderCnt 付费订单数量。
	OrderCnt int64 `json:"orderCnt"`
}

ShareInfo 是分享链接信息。

type ShareListResult 

type ShareListResult struct {
	// LastShareID 为 -1 表示最后一页；否则作为下一页的翻页游标。
	LastShareID int64       `json:"lastShareId"`
	ShareList   []ShareInfo `json:"shareList"`
}

ShareListResult 是分享链接列表的返回。

type ShareService 

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

ShareService 提供分享管理相关接口：免费/付费分享链接的创建、列表与修改。

func (*ShareService) Create 

func (s *ShareService) Create(ctx context.Context, req *ShareCreateRequest) (*ShareCreateResult, error)

Create 创建免费分享链接，返回分享 ID 与分享码。

接口: POST /api/v1/share/create

参数说明（见 ShareCreateRequest 各字段）：

  • ShareName：分享链接名称，必填。
  • ShareExpire：有效期天数，枚举 1、7、30、0（0 为永久），必填。
  • FileIDs：分享的文件 ID 列表，必填，最多 100 个。
  • SharePwd：提取码，可选，不填为公开分享。
  • TrafficSwitch：分享提取流量包开关，可选，含义见 TrafficSwitch 类型。
  • TrafficLimitSwitch：流量限制开关，可选：1 关闭限制；2 打开限制。
  • TrafficLimit：限制流量上限，单位字节，可选。

注意事项：完整分享页面链接需按 https://{uid}.share.123pan.cn/123pan/{shareKey} 规则拼接（见 ShareURL），uid 来自 client.User.Info。

func (*ShareService) CreatePaid 

func (s *ShareService) CreatePaid(ctx context.Context, req *PaidShareCreateRequest) (*ShareCreateResult, error)

CreatePaid 创建付费分享链接，返回分享 ID 与分享码。

接口: POST /api/v1/share/content-payment/create

参数说明（见 PaidShareCreateRequest 各字段）：

  • ShareName：分享链接名称，必填，小于 35 字符且不含特殊字符。
  • FileIDs：分享的文件 ID 列表，必填，最多 100 个。
  • PayAmount：付费金额，必填，整数元，取值范围 1-1000。
  • IsReward：是否开启打赏，0 否，1 是。
  • ResourceDesc：资源描述，可选。
  • TrafficSwitch：分享提取流量包开关，可选，含义见 TrafficSwitch 类型。
  • TrafficLimitSwitch：流量限制开关，可选：1 关闭限制；2 打开限制。
  • TrafficLimit：限制流量上限，单位字节，可选。

注意事项：完整分享页面链接拼接规则与免费分享相同（见 ShareURL）。

func (*ShareService) List 

func (s *ShareService) List(ctx context.Context, limit int, lastShareID int64) (*ShareListResult, error)

List 获取免费分享链接列表，按 lastShareId 游标翻页。

接口: GET /api/v1/share/list

参数说明：

  • limit：每页数量，最大 100；传 0 或负数时默认按 100 请求。
  • lastShareID：翻页游标，首页传 0，下一页传上一页返回的 LastShareID。

注意事项：返回的 LastShareID 为 -1 表示已到最后一页，翻页应就此结束。

func (*ShareService) ListPaid 

func (s *ShareService) ListPaid(ctx context.Context, limit int, lastShareID int64) (*ShareListResult, error)

ListPaid 获取付费分享链接列表，按 lastShareId 游标翻页。

接口: GET /api/v1/share/payment/list

参数说明：

  • limit：每页数量，最大 100；传 0 或负数时默认按 100 请求。
  • lastShareID：翻页游标，首页传 0，下一页传上一页返回的 LastShareID。

注意事项：返回的 LastShareID 为 -1 表示已到最后一页； 付费分享条目会额外返回 PayAmount、Amount、OrderCnt 等收益字段。

func (*ShareService) Update 

func (s *ShareService) Update(ctx context.Context, req *ShareUpdateRequest) error

Update 批量修改免费分享链接的流量设置。

接口: PUT /api/v1/share/list/info

参数说明（见 ShareUpdateRequest 各字段）：

  • ShareIDs：待修改的分享链接 ID 列表，必填，最多 100 个。
  • TrafficSwitch：分享提取流量包开关，可选，含义见 TrafficSwitch 类型。
  • TrafficLimitSwitch：流量限制开关，可选：1 关闭限制；2 打开限制。
  • TrafficLimit：限制流量上限，单位字节，可选。

注意事项：仅支持修改以上三项流量相关设置， 分享名称、有效期、提取码创建后均不可修改。

func (*ShareService) UpdatePaid 

func (s *ShareService) UpdatePaid(ctx context.Context, req *ShareUpdateRequest) error

UpdatePaid 批量修改付费分享链接的流量设置。

接口: PUT /api/v1/share/list/payment/info

参数说明（见 ShareUpdateRequest 各字段）：

  • ShareIDs：待修改的分享链接 ID 列表，必填，最多 100 个。
  • TrafficSwitch：分享提取流量包开关，可选，含义见 TrafficSwitch 类型。
  • TrafficLimitSwitch：流量限制开关，可选：1 关闭限制；2 打开限制。
  • TrafficLimit：限制流量上限，单位字节，可选。

注意事项：与 Update 相同，仅支持修改以上三项流量相关设置， 分享名称、付费金额、资源描述创建后均不可修改。

type ShareUpdateRequest 

type ShareUpdateRequest struct {
	// ShareIDs 分享链接 ID 列表，最多 100 个。
	ShareIDs []int64 `json:"shareIdList"`
	// TrafficSwitch 分享提取流量包开关（可选）。
	TrafficSwitch TrafficSwitch `json:"trafficSwitch,omitempty"`
	// TrafficLimitSwitch 流量限制开关：1 关闭限制；2 打开限制（可选）。
	TrafficLimitSwitch int `json:"trafficLimitSwitch,omitempty"`
	// TrafficLimit 限制流量，单位字节（可选）。
	TrafficLimit int64 `json:"trafficLimit,omitempty"`
}

ShareUpdateRequest 是修改分享链接的参数（仅支持修改流量相关设置）。

type SingleCreateResult 

type SingleCreateResult struct {
	// FileID 上传成功后的文件 ID。
	FileID int64 `json:"fileID"`
	// Completed 为 true 表示上传完成。
	Completed bool `json:"completed"`
}

SingleCreateResult 是单步上传的返回。

type TrafficLogEntry 

type TrafficLogEntry struct {
	// UniqueID 记录唯一 ID。
	UniqueID string `json:"uniqueID"`
	// FileName 文件名称。
	FileName string `json:"fileName"`
	// FileSize 文件大小（字节）。
	FileSize int64 `json:"fileSize"`
	// FilePath 文件路径。
	FilePath string `json:"filePath"`
	// DirectLinkURL 直链链接。
	DirectLinkURL string `json:"directLinkURL"`
	// FileSource 文件来源：1 全部文件，2 图床。
	FileSource int `json:"fileSource"`
	// TotalTraffic 消耗流量（字节）。
	TotalTraffic int64 `json:"totalTraffic"`
}

TrafficLogEntry 是直链流量日志条目。

type TrafficLogResult 

type TrafficLogResult struct {
	// Total 记录总数。
	Total int64 `json:"total"`
	// List 当前页的日志条目。
	List []TrafficLogEntry `json:"list"`
}

TrafficLogResult 是直链流量日志的返回。

type TrafficSwitch 

type TrafficSwitch int

TrafficSwitch 分享提取流量包开关。 枚举值：1 全部关闭；2 打开游客免登录提取；3 打开超流量用户提取；4 全部开启。

type TranscodeDownloadResult 

type TranscodeDownloadResult struct {
	// DownloadURL 下载地址；转码空间已满时为空。
	DownloadURL string `json:"downloadUrl"`
	// IsFull 转码空间容量是否已满。
	IsFull bool `json:"isFull"`
}

TranscodeDownloadResult 是转码空间下载类接口的返回。

type TranscodeFile 

type TranscodeFile struct {
	FileName string `json:"FileName"`
	// FileSize 为带单位的字符串，如 "497.17KB"。
	FileSize   string `json:"FileSize"`
	Resolution string `json:"Resolution"`
	CreateAt   string `json:"CreateAt"`
	// URL 播放地址，仅 m3u8 文件有值。
	URL string `json:"Url"`
}

TranscodeFile 是转码产物文件。

type TranscodeRecord 

type TranscodeRecord struct {
	CreateAt   string `json:"create_at"`
	Resolution string `json:"resolution"`
	// Status 1:准备转码 2:正在转码中 3-254:转码失败 255:转码成功
	Status int `json:"status"`
	// Link 转码成功后的 m3u8 链接（仅 Status=255 时有值）。
	Link string `json:"link"`
}

TranscodeRecord 是单条转码记录。

type TranscodeRequest 

type TranscodeRequest struct {
	FileID int64 `json:"fileId"`
	// CodecName 编码方式，取自 Resolutions 返回的 CodecNames。
	CodecName string `json:"codecName"`
	// VideoTime 视频时长（秒），取自 Resolutions 返回的 VideoTime。
	VideoTime int64 `json:"videoTime"`
	// Resolutions 要转码的分辨率，逗号分隔且 P 大写，如 "2160P,1080P,720P"。
	// 已转码过的分辨率无需再传。
	Resolutions string `json:"resolutions"`
}

TranscodeRequest 是发起视频转码的参数。

type TranscodeResult 

type TranscodeResult struct {
	UID        int64  `json:"Uid"`
	Resolution string `json:"Resolution"`
	// Status 1:准备转码 2:正在转码中 3-254:转码失败 255:转码成功
	Status int             `json:"Status"`
	Files  []TranscodeFile `json:"Files"`
}

TranscodeResult 是某分辨率的转码结果。

type TranscodeService 

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

TranscodeService 提供视频转码相关接口。

本地上传视频到转码空间：先调用 FolderInfo 获取转码空间目录 ID， 再使用 Upload.UploadFile 将视频上传到该目录。

func (*TranscodeService) CloudVideoFiles 

func (s *TranscodeService) CloudVideoFiles(ctx context.Context, req *FileListRequest) (*FileListResult, error)

CloudVideoFiles 获取云盘空间中的视频文件列表。

接口: GET /api/v2/file/list（固定 category=2，仅返回视频）

参数:

  • req: 文件列表查询参数，见 FileListRequest（分页、目录、搜索等）。

注意: 查询结果中的文件 ID 可用于 UploadFromCloudDisk 将视频转入转码空间。

func (*TranscodeService) Delete 

func (s *TranscodeService) Delete(ctx context.Context, fileID int64, mode DeleteMode) error

Delete 删除转码空间中的视频。

接口: POST /api/v1/transcode/delete (QPS 10)

参数:

  • fileID: 转码空间中的视频文件 ID。
  • mode: 删除范围。DeleteOriginal(1) 仅删除原文件； DeleteOriginalAndTranscoded(2) 删除原文件及转码后的文件。

注意: 删除转码后文件的操作不可逆，请谨慎使用 DeleteOriginalAndTranscoded。

func (*TranscodeService) DownloadAll 

func (s *TranscodeService) DownloadAll(ctx context.Context, fileID int64, zipName string) (*DownloadAllResult, error)

DownloadAll 打包下载某个视频的全部转码文件（zip）。

接口: POST /api/v1/transcode/file/download/all (QPS 1)

参数:

  • fileID: 转码空间中的视频文件 ID。
  • zipName: 打包生成的 zip 文件名。

注意: IsDownloading 为 true 表示服务端仍在打包，需轮询，官方建议间隔 10 秒；转码空间容量已满（IsFull 为 true）时不返回下载地址；返回的 DownloadURL 中携带 access_token，日志打印时注意脱敏。

func (*TranscodeService) DownloadM3U8 

func (s *TranscodeService) DownloadM3U8(ctx context.Context, fileID int64, resolution string) (*TranscodeDownloadResult, error)

DownloadM3U8 获取某分辨率 m3u8 文件的下载地址。

接口: POST /api/v1/transcode/m3u8_ts/download (QPS 20)

参数:

  • fileID: 转码空间中的视频文件 ID。
  • resolution: 分辨率，P 必须大写，如 "1080P"。

注意: 转码空间容量已满（IsFull 为 true）时不返回下载地址。

func (*TranscodeService) DownloadOriginal 

func (s *TranscodeService) DownloadOriginal(ctx context.Context, fileID int64) (*TranscodeDownloadResult, error)

DownloadOriginal 获取转码空间原文件的下载地址。

接口: POST /api/v1/transcode/file/download (QPS 10)

参数:

  • fileID: 转码空间中的视频文件 ID。

注意: 转码空间容量已满（IsFull 为 true）时不返回下载地址，DownloadURL 为空。

func (*TranscodeService) DownloadTS 

func (s *TranscodeService) DownloadTS(ctx context.Context, fileID int64, resolution, tsName string) (*TranscodeDownloadResult, error)

DownloadTS 获取某分辨率单个 ts 分片的下载地址。

接口: POST /api/v1/transcode/m3u8_ts/download (QPS 20)

参数:

  • fileID: 转码空间中的视频文件 ID。
  • resolution: 分辨率，P 必须大写，如 "1080P"。
  • tsName: 分片名，不含 ".ts" 后缀（Results 返回的 FileName 为 "000.ts" 时传 "000"）。

注意: 转码空间容量已满（IsFull 为 true）时不返回下载地址。

func (*TranscodeService) FolderInfo 

func (s *TranscodeService) FolderInfo(ctx context.Context) (int64, error)

FolderInfo 获取转码空间文件夹 ID。

接口: POST /api/v1/transcode/folder/info (QPS 20)

注意: 本地上传视频到转码空间时，将返回的文件夹 ID 作为 Upload.UploadFile 的 parentFileID 使用。

func (*TranscodeService) List 

func (s *TranscodeService) List(ctx context.Context, fileID int64) (*VideoTranscodeList, error)

List 获取视频转码列表。

接口: GET /api/v1/video/transcode/list

参数:

  • fileID: 视频文件 ID。

注意: 仅限三方挂载应用授权（OAuth）获取的 access_token 调用； 返回 Status：1 待转码、3 转码失败、254 部分成功、255 全部成功。

func (*TranscodeService) Records 

func (s *TranscodeService) Records(ctx context.Context, fileID int64) ([]TranscodeRecord, error)

Records 查询某个视频各分辨率的转码记录。

接口: POST /api/v1/transcode/video/record (QPS 20)

参数:

  • fileID: 转码空间中的视频文件 ID。

注意: 记录状态 Status：1 准备转码、2 正在转码中、3-254 转码失败、255 转码成功； 仅 Status=255 时 Link 返回 m3u8 播放链接。

func (*TranscodeService) Resolutions 

func (s *TranscodeService) Resolutions(ctx context.Context, fileID int64) (*ResolutionsResult, error)

Resolutions 获取视频文件可转码的分辨率。

接口: POST /api/v1/transcode/video/resolutions (QPS 1)

参数:

  • fileID: 转码空间中的视频文件 ID。

注意: 返回 IsGetResolution 为 true 表示服务端仍在解析，结果尚未就绪， 需轮询，官方建议间隔 10 秒。返回的 Resolutions 为小写（如 "1080p"）， 发起转码时 P 必须转为大写（如 "1080P"）；NowOrFinishedResolutions 中的 分辨率正在转码或已完成，无需重复提交。

func (*TranscodeService) Results 

func (s *TranscodeService) Results(ctx context.Context, fileID int64) ([]TranscodeResult, error)

Results 查询某个视频的转码结果，含各分辨率的产物文件列表。

接口: POST /api/v1/transcode/video/result (QPS 20)

参数:

  • fileID: 转码空间中的视频文件 ID。

注意: Status 含义同 Records：1 准备转码、2 正在转码中、3-254 转码失败、 255 转码成功。产物中仅 m3u8 文件带播放 URL，ts 分片需用 DownloadTS 获取下载地址。

func (*TranscodeService) SpaceFiles 

func (s *TranscodeService) SpaceFiles(ctx context.Context, req *FileListRequest) (*FileListResult, error)

SpaceFiles 获取转码空间的文件列表。

接口: GET /api/v2/file/list（固定 businessType=2，即转码空间）

参数:

  • req: 文件列表查询参数，见 FileListRequest（分页、目录、搜索等）。

func (*TranscodeService) Transcode 

func (s *TranscodeService) Transcode(ctx context.Context, req *TranscodeRequest) error

Transcode 发起视频转码操作。

接口: POST /api/v1/transcode/video (QPS 3)

参数:

  • req: 转码参数。FileID 为转码空间中的视频文件 ID；CodecName、VideoTime 取自 Resolutions 的返回；Resolutions 为要转码的分辨率，逗号分隔且 P 必须大写（如 "2160P,1080P,720P"）。

注意: 已转码或转码中的分辨率（见 NowOrFinishedResolutions）无需重复提交； 转码进度可通过 Records 或 Results 查询。

func (*TranscodeService) UploadFromCloudDisk 

func (s *TranscodeService) UploadFromCloudDisk(ctx context.Context, fileIDs []int64) error

UploadFromCloudDisk 将云盘空间的视频文件上传（转存）到转码空间。

接口: POST /api/v1/transcode/upload/from_cloud_disk (QPS 1)

参数:

  • fileIDs: 云盘视频文件 ID 列表，一次最多 100 个。

注意: 官方 QPS 限制为 1，频繁调用时需自行限流。

type UploadCompleteResult 

type UploadCompleteResult struct {
	// Completed 为 true 表示服务端合并校验完成，上传成功。
	Completed bool `json:"completed"`
	// FileID 上传成功后的文件 ID（Completed 为 true 时有效）。
	FileID int64 `json:"fileID"`
}

UploadCompleteResult 是上传完毕（V2）的返回。

type UploadCompleteResultV1 

type UploadCompleteResultV1 struct {
	// Async 为 true 时需调用 AsyncResultV1 轮询最终结果。
	Async bool `json:"async"`
	// Completed 为 true 表示上传完成。
	Completed bool `json:"completed"`
	// FileID 上传成功后的文件 ID（Completed 为 true 时有效）。
	FileID int64 `json:"fileID"`
}

UploadCompleteResultV1 是上传完毕（V1）的返回。

type UploadCreateRequest 

type UploadCreateRequest struct {
	// ParentFileID 父目录 ID，根目录为 0。
	ParentFileID int64 `json:"parentFileID"`
	// Filename 文件名，小于 255 字符且不能包含 "\/:*?|>< 。
	// ContainDir 为 true 时传入"路径+文件名"，如 /你好/123/测试文件.mp4。
	Filename string `json:"filename"`
	// Etag 文件 MD5。
	Etag string `json:"etag"`
	// Size 文件大小（字节）。
	Size int64 `json:"size"`
	// Duplicate 重名处理策略：0 默认，1 保留两者（自动加后缀），2 覆盖原文件。
	Duplicate int `json:"duplicate,omitempty"`
	// ContainDir 文件名是否携带路径，为 true 时自动创建不存在的中间目录。
	ContainDir bool `json:"containDir,omitempty"`
}

UploadCreateRequest 是创建文件（预上传）的参数。

type UploadCreateResult 

type UploadCreateResult struct {
	// FileID 秒传成功时返回的文件 ID。
	FileID int64 `json:"fileID"`
	// PreuploadID 预上传 ID（Reuse 为 true 时不存在），后续分片上传与完成接口凭此标识。
	PreuploadID string `json:"preuploadID"`
	// Reuse 为 true 表示秒传成功，上传结束。
	Reuse bool `json:"reuse"`
	// SliceSize 分片大小（字节），必须按此大小切分文件。
	SliceSize int64 `json:"sliceSize"`
	// Servers 上传域名（V2），后续上传分片必须使用其中之一。
	Servers []string `json:"servers"`
}

UploadCreateResult 是创建文件（V2）的返回。

type UploadCreateResultV1 

type UploadCreateResultV1 struct {
	// FileID 秒传成功时返回的文件 ID。
	FileID int64 `json:"fileID"`
	// PreuploadID 预上传 ID（Reuse 为 true 时不存在）。
	PreuploadID string `json:"preuploadID"`
	// Reuse 为 true 表示秒传成功，上传结束。
	Reuse bool `json:"reuse"`
	// SliceSize 分片大小（字节），必须按此大小切分文件。
	SliceSize int64 `json:"sliceSize"`
}

UploadCreateResultV1 是创建文件（V1 旧版）的返回。

type UploadService 

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

UploadService 提供文件上传相关接口：V2 分片上传（推荐）、单步上传、V1 旧版流程、sha1 秒传， 以及一行代码上传的高级封装 UploadFile / UploadFromPath。

V2 分片上传流程：Create（预上传，返回 Reuse 为 true 即秒传结束）→ UploadSlice（按 SliceSize 逐片上传到上传域名）→ Complete（轮询直至 Completed）。 单步上传流程（≤1GB 小文件）：Domains 获取上传域名 → SingleCreate 一次上传。 V1 旧版流程：CreateV1 → GetUploadURLV1（每片换预签名 URL）→ PutSliceV1 → ListUploadPartsV1（可选比对）→ CompleteV1（Async 为 true 时转 AsyncResultV1 轮询）。

func (*UploadService) AsyncResultV1 

func (s *UploadService) AsyncResultV1(ctx context.Context, preuploadID string) (*UploadCompleteResult, error)

AsyncResultV1 异步轮询获取上传结果（V1）。

接口: POST /upload/v1/file/upload_async_result

参数:

  • preuploadID: CreateV1 返回的预上传 ID。

返回 Completed 为 false 时至少间隔 1 秒再调用，直至 Completed 为 true 并取得 FileID。

func (*UploadService) Complete 

func (s *UploadService) Complete(ctx context.Context, preuploadID string) (*UploadCompleteResult, error)

Complete 通知上传完毕（V2），是 V2 分片上传流程的最后一步。

接口: POST /upload/v2/file/upload_complete（主域名）

参数:

  • preuploadID: Create 返回的预上传 ID。

返回 Completed 为 false 时表示服务端仍在合并校验，需间隔 1 秒重复调用轮询， 直至 Completed 为 true 并取得 FileID。

func (*UploadService) CompleteV1 

func (s *UploadService) CompleteV1(ctx context.Context, preuploadID string) (*UploadCompleteResultV1, error)

CompleteV1 通知上传完毕（V1）。

接口: POST /upload/v1/file/upload_complete

参数:

  • preuploadID: CreateV1 返回的预上传 ID。

返回 Async 为 true 时表示服务端异步合并，需转 AsyncResultV1 轮询最终结果 （间隔至少 1 秒）；Completed 为 true 时直接取 FileID。

func (*UploadService) Create 

func (s *UploadService) Create(ctx context.Context, req *UploadCreateRequest) (*UploadCreateResult, error)

Create 创建文件（V2 预上传），是 V2 分片上传流程的第一步。

接口: POST /upload/v2/file/create（主域名）

参数:

  • req: 预上传参数，见 UploadCreateRequest；Etag 为整个文件的 MD5， Size 单位字节，单文件上限 10GB。

返回 Reuse 为 true 时秒传成功、上传结束（FileID 即结果）； 否则按 SliceSize 切分文件，用返回的 Servers 之一调用 UploadSlice， 全部分片传完后调用 Complete。

func (*UploadService) CreateV1 

func (s *UploadService) CreateV1(ctx context.Context, req *UploadCreateRequest) (*UploadCreateResultV1, error)

CreateV1 创建文件（V1 旧版预上传）。推荐使用 Create（V2）。

接口: POST /upload/v1/file/create

参数:

  • req: 预上传参数，见 UploadCreateRequest；Etag 为整个文件的 MD5。

返回 Reuse 为 true 时秒传成功；否则按 SliceSize 切分，逐片经 GetUploadURLV1 换取预签名地址并 PutSliceV1 上传，最后调用 CompleteV1。

func (*UploadService) Domains 

func (s *UploadService) Domains(ctx context.Context) ([]string, error)

Domains 获取单步上传的上传域名列表，是单步上传流程的第一步。

接口: GET /upload/v2/file/domain

返回的域名任选其一作为 SingleCreate 的 server 参数。

func (*UploadService) GetUploadURLV1 

func (s *UploadService) GetUploadURLV1(ctx context.Context, preuploadID string, sliceNo int64) (string, error)

GetUploadURLV1 获取分片的预签名上传地址（V1）。每个分片都需单独换取。

接口: POST /upload/v1/file/get_upload_url

参数:

  • preuploadID: CreateV1 返回的预上传 ID。
  • sliceNo: 分片编号，从 1 开始。

返回的预签名地址交给 PutSliceV1 上传分片内容。

func (*UploadService) ListUploadPartsV1 

func (s *UploadService) ListUploadPartsV1(ctx context.Context, preuploadID string) ([]UploadedPart, error)

ListUploadPartsV1 列举已上传分片（V1，非必需步骤），用于本地 MD5 比对校验。

接口: POST /upload/v1/file/list_upload_parts

参数:

  • preuploadID: CreateV1 返回的预上传 ID。

注意：文件小于 sliceSize（即未真正分片）时返回空列表。

func (*UploadService) PutSliceV1 

func (s *UploadService) PutSliceV1(ctx context.Context, presignedURL string, slice io.Reader, size int64) error

PutSliceV1 向预签名地址 PUT 上传分片二进制（V1）。

接口: PUT {presignedURL}（预签名地址，非开放平台域名）

参数:

  • presignedURL: GetUploadURLV1 返回的预签名上传地址。
  • slice: 分片内容。
  • size: 分片字节数，用于设置 Content-Length。

注意：此请求不携带 Authorization/Platform 头（官方要求）， Content-Type 为 application/octet-stream。

func (*UploadService) Sha1Reuse 

func (s *UploadService) Sha1Reuse(ctx context.Context, parentFileID int64, filename, sha1 string, size int64, duplicate int) (*Sha1ReuseResult, error)

Sha1Reuse 通过文件 sha1 尝试秒传。

接口: POST /upload/v2/file/sha1_reuse

参数:

  • parentFileID: 父目录 ID，根目录为 0。
  • filename: 文件名，小于 255 字符且不能包含 "\/:*?|>< 。
  • sha1: 整个文件的 SHA1（注意：此接口用 SHA1，其余上传接口均用 MD5）。
  • size: 文件大小（字节）。
  • duplicate: 重名处理策略：0 默认，1 保留两者（自动加后缀），2 覆盖原文件。

返回 Reuse 为 false 时表示服务端无此文件，需改走正常上传流程（Create 或 SingleCreate）。

func (*UploadService) SingleCreate 

func (s *UploadService) SingleCreate(ctx context.Context, server string, req *UploadCreateRequest, file io.Reader) (*SingleCreateResult, error)

SingleCreate 单步上传：一次 multipart 请求完成小文件上传。

接口: POST {server}/upload/v2/file/single/create（上传域名，非主域名）

参数:

  • server: 上传域名，取 Domains 返回的域名之一。
  • req: 上传参数，见 UploadCreateRequest；Etag 为整个文件的 MD5。
  • file: 文件内容，单文件上限 1GB；更大文件请走 Create 分片上传（上限 10GB）。

func (*UploadService) UploadFile 

func (s *UploadService) UploadFile(ctx context.Context, parentFileID int64, filename string, r io.ReaderAt, size int64) (int64, error)

UploadFile 上传文件到指定目录，返回文件 ID。

接口: 组合调用 V2 分片上传流程 POST /upload/v2/file/create → POST {server}/upload/v2/file/slice → POST /upload/v2/file/upload_complete

参数:

  • parentFileID: 目标目录 ID，根目录为 0。
  • filename: 文件名，小于 255 字符且不能包含 "\/:*?|>< 。
  • r: 文件内容，需要支持随机读（*os.File、*bytes.Reader 等均满足）。
  • size: 文件总大小（字节），单文件上限 10GB。

自动完成：MD5 计算、秒传检测（Reuse 命中即直接返回）、分片并发上传 （并发数 3）、Complete 轮询（间隔 1 秒）直至服务端合并完成。

func (*UploadService) UploadFromPath 

func (s *UploadService) UploadFromPath(ctx context.Context, parentFileID int64, path string) (int64, error)

UploadFromPath 上传本地文件到指定目录，返回文件 ID。

接口: 组合调用 V2 分片上传流程（Create → UploadSlice → Complete），见 UploadFile

参数:

  • parentFileID: 目标目录 ID，根目录为 0。
  • path: 本地文件路径，文件名取自路径的 basename；单文件上限 10GB。

自动完成：MD5 计算、秒传检测、按服务端分片大小切分并发上传、轮询完成。

func (*UploadService) UploadSlice 

func (s *UploadService) UploadSlice(ctx context.Context, server, preuploadID string, sliceNo int64, sliceMD5 string, slice io.Reader) error

UploadSlice 上传单个分片（V2），multipart/form-data 格式。

接口: POST {server}/upload/v2/file/slice（上传域名，非主域名）

参数:

  • server: 上传域名，取 Create 返回的 Servers 之一。
  • preuploadID: Create 返回的预上传 ID。
  • sliceNo: 分片编号，从 1 开始。
  • sliceMD5: 该分片内容的 MD5。
  • slice: 分片内容，长度须等于 Create 返回的 SliceSize（末片可小于）。

type UploadedPart 

type UploadedPart struct {
	// PartNumber 分片编号（服务端可能返回字符串，用 json.Number 兼容）。
	PartNumber json.Number `json:"partNumber"`
	// Size 分片大小（字节）。
	Size int64 `json:"size"`
	// Etag 分片 MD5，可与本地计算值比对校验。
	Etag string `json:"etag"`
}

UploadedPart 是已上传分片信息（V1）。

type UserInfo 

type UserInfo struct {
	// UID 用户账号 ID，也用于拼接分享链接（见 ShareURL）。
	UID int64 `json:"uid"`
	// Nickname 昵称。
	Nickname string `json:"nickname"`
	// HeadImage 头像地址。
	HeadImage string `json:"headImage"`
	// Passport 手机号码。
	Passport string `json:"passport"`
	// Mail 邮箱。
	Mail string `json:"mail"`
	// SpaceUsed 已用空间（字节）。
	SpaceUsed int64 `json:"spaceUsed"`
	// SpacePermanent 永久空间（字节）。
	SpacePermanent int64 `json:"spacePermanent"`
	// SpaceTemp 临时空间（字节）。
	SpaceTemp int64 `json:"spaceTemp"`
	// SpaceTempExpr 临时空间到期日（文档标 string，实际可能返回数字，用 RawMessage 兼容）。
	SpaceTempExpr json.RawMessage `json:"spaceTempExpr"`
	// Vip 是否为会员。
	Vip bool `json:"vip"`
	// DirectTraffic 剩余直链流量（字节）。
	DirectTraffic int64 `json:"directTraffic"`
	// IsHideUID 直链链接是否隐藏 UID。
	IsHideUID bool `json:"isHideUID"`
	// HTTPSCount https 数量。
	HTTPSCount int `json:"httpsCount"`
	// VipInfoList 会员信息，非会员为 nil。
	VipInfoList []VipInfo `json:"vipInfo"`
	// DeveloperInfo 开发者权益信息。
	DeveloperInfo *DeveloperInfo `json:"developerInfo"`
}

UserInfo 是用户信息。

type UserService 

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

UserService 提供用户信息接口。

func (*UserService) Info 

func (s *UserService) Info(ctx context.Context) (*UserInfo, error)

Info 获取当前用户信息，包括账号、空间用量、会员及开发者权益等。

接口: GET /api/v1/user/info (QPS 10)

注意事项：返回的 UID 用于拼接分享页面链接 https://{uid}.share.123pan.cn/123pan/{shareKey}（见 ShareURL）； 该接口有 QPS 10 限制，建议缓存结果，避免高频调用。

type VideoTranscodeItem 

type VideoTranscodeItem struct {
	URL        string  `json:"url"`
	Resolution string  `json:"resolution"`
	Duration   float64 `json:"duration"`
	Height     int     `json:"height"`
	Status     int     `json:"status"`
	MC         string  `json:"mc"`
	BitRate    int64   `json:"bitRate"`
	Progress   int     `json:"progress"`
	UpdateAt   string  `json:"updateAt"`
}

VideoTranscodeItem 是三方挂载应用授权场景的转码列表项。

type VideoTranscodeList 

type VideoTranscodeList struct {
	// Status 转码状态：1 待转码；3 转码失败；254 部分成功；255 全部成功。
	Status int                  `json:"status"`
	List   []VideoTranscodeItem `json:"list"`
}

VideoTranscodeList 是三方挂载应用授权场景的转码列表返回。

type VipInfo 

type VipInfo struct {
	// VipLevel 会员等级：1 VIP；2 SVIP；3 长期VIP。
	VipLevel int `json:"vipLevel"`
	// VipLabel 会员等级名称，如"月卡"。
	VipLabel string `json:"vipLabel"`
	// StartTime 会员开始时间。
	StartTime string `json:"startTime"`
	// EndTime 会员结束时间。
	EndTime string `json:"endTime"`
}

VipInfo 是会员信息。

Source Files

View all Source files

Directories

Path Synopsis
cmd
pan123 command
pan123 是 123 云盘开放平台的命令行工具。
 pan123 是 123 云盘开放平台的命令行工具。
examples
download command
download 演示：获取下载直链并保存文件到本地。
 download 演示：获取下载直链并保存文件到本地。
imagebed command
imagebed 演示：上传本地图片到图床并获取外链。
 imagebed 演示：上传本地图片到图床并获取外链。
offline command
offline 演示：创建离线下载任务并轮询进度直到完成。
 offline 演示：创建离线下载任务并轮询进度直到完成。
quickstart command
quickstart 演示：创建客户端、获取用户信息、列出根目录文件。
 quickstart 演示：创建客户端、获取用户信息、列出根目录文件。
share command
share 演示：创建分享链接并拼接可访问的分享地址。
 share 演示：创建分享链接并拼接可访问的分享地址。
upload command
upload 演示：一行代码上传本地文件（自动 MD5、秒传检测、分片并发上传、轮询完成）。
 upload 演示：一行代码上传本地文件（自动 MD5、秒传检测、分片并发上传、轮询完成）。

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.