pan123

package module
v1.0.0 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 Go Report Card 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 图床上传 + 获取外链

📚 API 覆盖

服务 说明 主要方法
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 可通过 client.User.Info 获取。

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 []struct {
		FileID   int64  `json:"fileID"`
		UpdateAt string `json:"updateAt"`
	} `json:"successList"`
	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（可能为空或已过期）。

type CopyResult 

type CopyResult struct {
	SourceFileID int64 `json:"sourceFileId"`
	TargetFileID int64 `json:"targetFileId"`
}

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

type CopyTaskStatus 

type CopyTaskStatus int

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

const (
	CopyTaskPending CopyTaskStatus = 0
	CopyTaskRunning CopyTaskStatus = 1
	CopyTaskDone    CopyTaskStatus = 2
	CopyTaskFailed  CopyTaskStatus = 3
)

type DeleteMode 

type DeleteMode int

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

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

type DeveloperInfo 

type DeveloperInfo struct {
	StartTime string `json:"startTime"`
	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       int64  `json:"fileID"`
	Filename     string `json:"filename"`
	Type         int    `json:"type"`
	Size         int64  `json:"size"`
	Etag         string `json:"etag"`
	Status       int    `json:"status"`
	ParentFileID int64  `json:"parentFileID"`
	CreateAt     string `json:"createAt"`
	Trashed      int    `json:"trashed"`
}

FileDetail 是单个文件详情。

type FileInfo 

type FileInfo struct {
	FileID   int64  `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"`
	ParentFileID int64 `json:"parentFileId"`
	// Category 文件分类：0-未知 1-音频 2-视频 3-图片。
	Category int `json:"category"`
	// Trashed 是否在回收站：0-否 1-是。
	Trashed     int    `json:"trashed"`
	PunishFlag  int    `json:"punishFlag"`
	S3KeyFlag   string `json:"s3KeyFlag"`
	StorageNode string `json:"storageNode"`
	CreateAt    string `json:"createAt"`
	UpdateAt    string `json:"updateAt"`
}

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

type FileInfoV1 

type FileInfoV1 struct {
	FileID       int64  `json:"fileID"`
	Filename     string `json:"filename"`
	Type         int    `json:"type"`
	Size         int64  `json:"size"`
	Etag         string `json:"etag"`
	Status       int    `json:"status"`
	ParentFileID int64  `json:"parentFileId"`
	ParentName   string `json:"parentName"`
	Category     int    `json:"category"`
	CreateAt     string `json:"createAt"`
	UpdateAt     string `json:"updateAt"`
	Thumbnail    string `json:"thumbnail"`
	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   []FileInfo `json:"fileList"`
}

FileListResult 是 v2 文件列表的返回。

type FileListV1Request 

type FileListV1Request struct {
	ParentFileID int64
	// Page 页码，从 1 开始。
	Page  int
	Limit int
	// OrderBy 排序字段：file_id、size、file_name。
	OrderBy string
	// OrderDirection 排序方向：asc、desc。
	OrderDirection string
	// Trashed 是否查看回收站文件。
	Trashed    bool
	SearchData string
}

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

type FileListV1Result 

type FileListV1Result struct {
	Total    int          `json:"total"`
	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 批量复制文件（异步），单级最多 3000 个，返回任务 ID。 用 CopyProcess 轮询进度。

func (*FileService) BatchRename 

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

BatchRename 批量重命名，key 为文件 ID、value 为新文件名，一次最多 30 个。

func (*FileService) Copy 

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

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

func (*FileService) CopyProcess 

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

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

func (*FileService) Detail 

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

Detail 获取单个文件详情；查询文件夹时 size 为文件夹累计大小。

func (*FileService) DownloadInfo 

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

DownloadInfo 获取文件的临时下载直链。 免费账号每日自用下载流量 1GB，超限返回 code 5113；文件不存在返回 code 5066。

func (*FileService) DownloadTo 

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

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

func (*FileService) Infos 

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

Infos 批量获取文件详情。

func (*FileService) List 

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

List 获取文件列表（v2 推荐接口，lastFileId 游标翻页）。 注意：结果包含回收站文件，需按 Trashed 字段过滤。

func (*FileService) ListAll 

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

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

func (*FileService) ListV1 

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

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

func (*FileService) Mkdir 

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

Mkdir 创建目录，返回新目录 ID。上传到根目录时 parentID 填 0。目录名不能与同级重名。

func (*FileService) Move 

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

Move 批量移动文件，单级最多 100 个。移动到根目录时 toParentFileID 填 0。

func (*FileService) Recover 

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

Recover 从回收站恢复文件至原位置，一次最多 100 个。 返回父级目录已不存在的异常文件 ID，可用 RecoverTo 还原到指定目录。

func (*FileService) RecoverTo 

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

RecoverTo 将回收站文件还原到指定目录，一次最多 100 个。

func (*FileService) Rename 

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

Rename 重命名单个文件。

func (*FileService) SafeboxID 

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

SafeboxID 解锁保险箱并获取保险箱目录 ID，可作为 parentFileID 使用。

func (*FileService) Trash 

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

Trash 删除文件至回收站，一次最多 100 个。

type IPBlacklistStatus 

type IPBlacklistStatus int

IPBlacklistStatus IP 黑名单状态：1 启用，2 禁用。 

const (
	IPBlacklistEnabled  IPBlacklistStatus = 1
	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 对文件夹禁用直链空间，返回文件夹名称。

func (*LinkService) Enable 

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

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

func (*LinkService) IPBlacklist 

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

IPBlacklist 获取 IP 黑名单列表及开关状态。

func (*LinkService) OfflineLogs 

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

OfflineLogs 查询直链离线日志（仅近 30 天）。 startHour/endHour 格式精确到小时："2025010115"；pageNum 从 1 开始。

func (*LinkService) RefreshCache 

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

RefreshCache 全量刷新直链 CDN 缓存。

func (*LinkService) SwitchIPBlacklist 

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

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

func (*LinkService) TrafficLog 

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

TrafficLog 查询直链流量日志（仅近 3 天）。 startTime/endTime 格式："2025-01-01 00:00:00"；pageNum 从 1 开始。

func (*LinkService) URL 

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

URL 获取文件的直链链接。文件必须位于已启用直链空间的目录下。

func (*LinkService) UpdateIPBlacklist 

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

UpdateIPBlacklist 全量覆盖更新 IP 黑名单列表，最多 2000 个 IPv4 地址。

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 构造用户授权页面地址。用户授权后将携带 code 回跳 redirectURI。

func (*OAuthService) RefreshToken 

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

RefreshToken 用 refresh_token 刷新令牌。 刷新成功后旧 access_token 立即失效，refresh_token 换新（旧值作废）。

func (*OAuthService) TokenByCode 

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

TokenByCode 用授权 code 换取 access_token。 redirectURI 必须与应用注册的回调地址一致。

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 文档标 string，实际可能返回数字，用 Number 兼容。
	ID           any    `json:"id"`
	FileName     string `json:"fileName"`
	FileSize     int64  `json:"fileSize"`
	LogTimeRange string `json:"logTimeRange"`
	DownloadURL  string `json:"downloadURL"`
}

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

type OfflineLogResult 

type OfflineLogResult struct {
	Total int64             `json:"total"`
	List  []OfflineLogEntry `json:"list"`
}

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

type OfflineProcessResult 

type OfflineProcessResult struct {
	// Process 下载进度百分比；下载失败时会归零。
	Process float64       `json:"process"`
	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。

func (*OfflineService) Process 

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

Process 查询离线下载任务进度。 注意 Status 为 3（重试中）时仍未终结，不能仅凭 Process 判断结果。

type OfflineStatus 

type OfflineStatus int

OfflineStatus 离线下载状态：0 进行中、1 下载失败、2 下载成功、3 重试中。 

const (
	OfflineRunning  OfflineStatus = 0
	OfflineFailed   OfflineStatus = 1
	OfflineSuccess  OfflineStatus = 2
	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 分页查询复制失败的文件列表，page 从 1 开始，limit 最大 100。

func (*OssService) CopyFromDisk 

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

CopyFromDisk 创建"复制云盘图片到图床"任务，返回任务 ID。 fileIDs 为云盘文件/目录 ID（最多 100 个）；toParentFileID 为空表示图床根目录。 限制：并发任务 3 个，单任务图片总数 1000 张，单图 100M。

func (*OssService) CopyProcess 

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

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

func (*OssService) CreateFile 

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

CreateFile 图床创建文件（预上传）。parentFileID 为空字符串表示根目录；etag 为文件 MD5。

func (*OssService) Delete 

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

Delete 批量删除图片，一次最多 100 个。

func (*OssService) Detail 

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

Detail 获取图片详情。

func (*OssService) GetUploadURL 

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

GetUploadURL 获取图床分片的预签名上传地址，sliceNo 从 1 开始。 获取后向该地址 PUT 分片二进制（可复用 Upload.PutSliceV1）。

func (*OssService) List 

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

List 获取图片列表（lastFileId 游标翻页，注意游标为字符串，"-1" 表示结束）。

func (*OssService) Mkdir 

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

Mkdir 创建图床目录，parentID 为空字符串表示根目录。返回新目录 ID。

func (*OssService) Move 

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

Move 批量移动图片到目标目录（toParentFileID 不能为空），单级最多 100 个。

func (*OssService) OfflineDownload 

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

OfflineDownload 创建图床离线迁移任务（从 URL 拉取图片到图床），返回任务 ID。 仅支持 http/https；支持 png/gif/jpeg/tiff/webp/jpg/tif/svg/bmp，单图 100M。

func (*OssService) OfflineProcess 

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

OfflineProcess 查询图床离线迁移任务进度。 状态枚举与云盘离线下载一致：0 进行中、1 失败、2 成功、3 重试中。

func (*OssService) UploadAsyncResult 

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

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

func (*OssService) UploadComplete 

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

UploadComplete 通知图床上传完毕。

func (*OssService) UploadFile 

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

UploadFile 上传图片到图床，返回文件 ID。r 需要支持随机读。

func (*OssService) UploadFromPath 

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

UploadFromPath 上传本地图片到图床，返回文件 ID。 parentFileID 为空字符串表示根目录。自动完成 MD5、秒传检测、分片上传与轮询。

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 int64 `json:"fileID"`
	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  int64  `json:"shareID"`
	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           string `json:"sharePwd"`
	TrafficSwitch      int    `json:"trafficSwitch"`
	TrafficLimitSwitch int    `json:"trafficLimitSwitch"`
	TrafficLimit       int64  `json:"trafficLimit"`
	// BytesCharge 分享已使用流量（字节）。
	BytesCharge   int64 `json:"bytesCharge"`
	PreviewCount  int64 `json:"previewCount"`
	DownloadCount int64 `json:"downloadCount"`
	SaveCount     int64 `json:"saveCount"`
	// 以下字段仅付费分享返回。
	PayAmount float64 `json:"payAmount"`
	// Amount 分享收益。
	Amount   float64 `json:"amount"`
	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 创建分享链接。

func (*ShareService) CreatePaid 

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

CreatePaid 创建付费分享链接。

func (*ShareService) List 

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

List 获取分享链接列表（lastShareId 游标翻页，返回 -1 表示结束）。

func (*ShareService) ListPaid 

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

ListPaid 获取付费分享链接列表（lastShareId 游标翻页，返回 -1 表示结束）。

func (*ShareService) Update 

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

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

func (*ShareService) UpdatePaid 

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

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

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    int64 `json:"fileID"`
	Completed bool  `json:"completed"`
}

SingleCreateResult 是单步上传的返回。

type TrafficLogEntry 

type TrafficLogEntry struct {
	UniqueID      string `json:"uniqueID"`
	FileName      string `json:"fileName"`
	FileSize      int64  `json:"fileSize"`
	FilePath      string `json:"filePath"`
	DirectLinkURL string `json:"directLinkURL"`
	// FileSource 文件来源：1 全部文件，2 图床。
	FileSource int `json:"fileSource"`
	// TotalTraffic 消耗流量（字节）。
	TotalTraffic int64 `json:"totalTraffic"`
}

TrafficLogEntry 是直链流量日志条目。

type TrafficLogResult 

type TrafficLogResult struct {
	Total int64             `json:"total"`
	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 获取云盘空间中的视频文件（category=2），用于后续 UploadFromCloudDisk。

func (*TranscodeService) Delete 

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

Delete 删除转码视频。

func (*TranscodeService) DownloadAll 

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

DownloadAll 打包下载某个视频的全部转码文件。 IsDownloading 为 true 时需轮询；返回的 URL 含 access_token，注意日志脱敏。

func (*TranscodeService) DownloadM3U8 

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

DownloadM3U8 获取某分辨率 m3u8 文件的下载地址。分辨率 P 大写，如 "1080P"。

func (*TranscodeService) DownloadOriginal 

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

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

func (*TranscodeService) DownloadTS 

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

DownloadTS 获取某分辨率单个 ts 分片的下载地址。 tsName 不含 ".ts" 后缀（Results 返回的 FileName 为 "000.ts" 时传 "000"）。

func (*TranscodeService) FolderInfo 

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

FolderInfo 获取转码空间文件夹 ID（本地上传视频时作为 parentFileID 使用）。

func (*TranscodeService) List 

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

List 视频转码列表（仅限三方挂载应用授权 access_token 调用）。

func (*TranscodeService) Records 

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

Records 查询某个视频的转码记录。

func (*TranscodeService) Resolutions 

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

Resolutions 获取视频文件可转码的分辨率。 IsGetResolution 为 true 时结果尚未就绪，需轮询（建议 10s 间隔）。

func (*TranscodeService) Results 

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

Results 查询某个视频的转码结果（含产物文件列表）。

func (*TranscodeService) SpaceFiles 

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

SpaceFiles 获取转码空间的文件列表（businessType=2）。

func (*TranscodeService) Transcode 

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

Transcode 发起视频转码操作。

func (*TranscodeService) UploadFromCloudDisk 

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

UploadFromCloudDisk 将云盘空间的视频文件上传到转码空间，一次最多 100 个文件。 注意：官方 QPS 限制为 1。

type UploadCompleteResult 

type UploadCompleteResult struct {
	Completed bool  `json:"completed"`
	FileID    int64 `json:"fileID"`
}

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

type UploadCompleteResultV1 

type UploadCompleteResultV1 struct {
	// Async 为 true 时需调用 AsyncResultV1 轮询最终结果。
	Async     bool  `json:"async"`
	Completed bool  `json:"completed"`
	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 文件名是否携带路径。
	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      int64  `json:"fileID"`
	PreuploadID string `json:"preuploadID"`
	Reuse       bool   `json:"reuse"`
	SliceSize   int64  `json:"sliceSize"`
}

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

type UploadService 

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

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

func (*UploadService) AsyncResultV1 

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

AsyncResultV1 异步轮询获取上传结果（V1）。Completed 为 false 时至少间隔 1 秒再调用。

func (*UploadService) Complete 

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

Complete 通知上传完毕（V2）。Completed 为 false 时需间隔 1 秒重复调用轮询。

func (*UploadService) CompleteV1 

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

CompleteV1 通知上传完毕（V1）。

func (*UploadService) Create 

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

Create 创建文件（V2 预上传）。单文件上限 10GB。 返回 Reuse 为 true 时秒传成功；否则按 SliceSize 切分后调用 UploadSlice。

func (*UploadService) CreateV1 

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

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

func (*UploadService) Domains 

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

Domains 获取单步上传的上传域名列表。

func (*UploadService) GetUploadURLV1 

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

GetUploadURLV1 获取分片的预签名上传地址（V1），sliceNo 从 1 开始。

func (*UploadService) ListUploadPartsV1 

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

ListUploadPartsV1 列举已上传分片（V1，非必需），用于本地 MD5 比对。 文件小于 sliceSize 时返回空。

func (*UploadService) PutSliceV1 

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

PutSliceV1 向预签名地址 PUT 上传分片二进制（V1）。 注意：此请求不携带 Authorization/Platform 头（官方要求）。

func (*UploadService) Sha1Reuse 

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

Sha1Reuse 通过文件 sha1 尝试秒传。Reuse 为 false 时需改走正常上传流程。 duplicate：0 默认，1 保留两者，2 覆盖原文件。

func (*UploadService) SingleCreate 

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

SingleCreate 单步上传：一次请求完成小文件上传，单文件上限 1GB。 server 取 Domains 返回的域名之一；req.Etag 为整个文件的 MD5。

func (*UploadService) UploadFile 

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

UploadFile 上传文件到指定目录，返回文件 ID。 r 需要支持随机读（*os.File、*bytes.Reader 等均满足）；size 为文件总大小。 自动完成：MD5 计算、秒传检测、分片并发上传、轮询完成。

func (*UploadService) UploadFromPath 

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

UploadFromPath 上传本地文件到指定目录，返回文件 ID。 自动完成：MD5 计算、秒传检测、按服务端分片大小切分并发上传、轮询完成。

func (*UploadService) UploadSlice 

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

UploadSlice 上传单个分片（V2）。server 取 Create 返回的 Servers 之一；sliceNo 从 1 开始。

type UploadedPart 

type UploadedPart struct {
	// PartNumber 分片编号（服务端可能返回字符串，用 json.Number 兼容）。
	PartNumber json.Number `json:"partNumber"`
	Size       int64       `json:"size"`
	Etag       string      `json:"etag"`
}

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

type UserInfo 

type UserInfo struct {
	// UID 用户账号 ID，也用于拼接分享链接（见 ShareURL）。
	UID       int64  `json:"uid"`
	Nickname  string `json:"nickname"`
	HeadImage string `json:"headImage"`
	// Passport 手机号码。
	Passport string `json:"passport"`
	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           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 获取当前用户信息。

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、2、3 分别对应 VIP、SVIP、长期VIP。
	VipLevel  int    `json:"vipLevel"`
	VipLabel  string `json:"vipLabel"`
	StartTime string `json:"startTime"`
	EndTime   string `json:"endTime"`
}

VipInfo 是会员信息。

Source Files

View all Source files

Directories

Path Synopsis
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.