文档 · WxCDN

快速开始

准备一个用户 Token 和资源 ID，下载你的第一个文件。

基础地址https://wxcdn.c3o.reHTTPS

bash

curl --fail-with-body \
  "https://wxcdn.c3o.re/download?fileid=YOUR_ENCODED_FILE_ID&type=file" \
  -H "Authorization: Bearer $WXCDN_TOKEN" \
  --output downloaded-file.bin

还没有 Token？先阅读获取授权。资源密钥建议在客户端本地处理。

认证与限频

用户接口通过 Authorization: Bearer <token> 认证。正式调用时把 Token 放在请求头中，避免它进入 URL、浏览器历史和日志。

/token：每个客户端 IP 每 10 秒最多 3 次。

/quota、/redeem、/download：鉴权后按账号、按端点，每 10 秒最多 30 次。

限频响应为 429，请遵守 Retry-After。401 invalid_token 需要重新授权；403 account_frozen 表示账号被冻结，请联系管理员。自动兑换锁只影响兑换功能。

套餐与计费

套餐	额度	周期	重置时间
Free	52,428,800 bytes（50 MiB）	UTC 自然日	次日 00:00 UTC
Plus	10,737,418,240 bytes（10 GiB）	UTC 自然月	次月 1 日 00:00 UTC
Pro	214,748,364,800 bytes（200 GiB）	UTC 自然月	次月 1 日 00:00 UTC
Ultra	不限量	永久累计	不重置

POST /token

读取客户端授权配置、创建或刷新账号并签发用户 Token。

请求必须是 multipart/form-data：

字段	类型	必填	说明
`weixinIDFolder`	string	是	账号目录标识
`fileBytes`	file	是	主授权文件
`crcBytes`	file	是	授权校验文件
`tokenDuration`	string	否	`short`、`medium`（默认）或 `long`

成功响应 200：

json

{
  "token": "v2....",
  "tokenDuration": "medium",
  "issuedAt": 1788537600,
  "expiresAt": 1788796800,
  "expiresIn": 259200,
  "account": {
    "nickname": "用户昵称",
    "avatarUrl": "https://...",
    "plan": "Free",
    "permanentPlan": "Free",
    "proExpiresAt": null
  },
  "quota": {
    "period": "day",
    "periodKey": "day:2026-09-05",
    "limitBytes": 52428800,
    "usedBytes": 0,
    "remainingBytes": 52428800,
    "resetsAt": 1788624000
  }
}

Token 时长：short 为 6 小时，medium 为 3 天，long 为 30 天。

GET /quota

查询用户当前套餐和额度。需要用户 Token，无请求体。

成功响应 200：

json

{
  "account": {
    "nickname": "用户昵称",
    "avatarUrl": null,
    "plan": "Plus",
    "permanentPlan": "Plus",
    "proExpiresAt": null
  },
  "quota": {
    "period": "month",
    "periodKey": "month:2026-09",
    "limitBytes": 10737418240,
    "usedBytes": 1048576,
    "remainingBytes": 10736369664,
    "resetsAt": 1790812800
  }
}

Ultra 会从获得 Ultra 权益后永久累计实际流量：usedBytes 持续增加，period 和 periodKey 均为 lifetime，resetsAt 为 null。因为没有额度上限，limitBytes 和 remainingBytes 也为 null。

account.plan 是此刻生效的套餐；permanentPlan 只可能是 Free、Plus、Ultra；proExpiresAt 是最近一次 Pro 权益到期时间，从未兑换或永久 Ultra 时为 null，过期后可能保留过去的时间戳。前端应以 plan 决定当前额度，以另外两个字段展示到期和回落信息。

POST /redeem

使用一次性兑换码授予永久 Plus/Ultra，或延长临时 Pro 权益。需要用户 Token。

http

Content-Type: application/json

json

{
  "code": "wx-7K9M-P4RX-2V8D-Q6YT-H3NC"
}

兑换码使用小写 wx- 前缀和 20 位 Crockford Base32 字符，约 100-bit 随机强度；输入不区分大小写，空格和连字符会被忽略，O/I/L 也会按 0/1/1 纠正。已有永久 Plus/Ultra 不会重复消耗同档永久码；永久 Ultra 不会消耗 Pro 延期码。

同一账号在滚动 15 分钟窗口内连续 5 次提交无效、已使用、已撤销或已过期的兑换码后，/redeem 会锁定 24 小时。锁定只影响兑换，不影响查询额度和下载；成功兑换会清除失败计数，plan_not_upgraded 不计入失败次数。不要在前端显示还剩几次尝试，避免帮助枚举攻击。

成功响应 200：

json

{
  "redemption": {
    "plan": "Pro",
    "durationMonths": 1,
    "redeemedAt": 1788566400
  },
  "account": {
    "nickname": "用户昵称",
    "avatarUrl": null,
    "plan": "Pro",
    "permanentPlan": "Plus",
    "proExpiresAt": 1791158400
  },
  "quota": {
    "period": "month",
    "periodKey": "month:2026-09",
    "limitBytes": 214748364800,
    "usedBytes": 1048576,
    "remainingBytes": 214747316224,
    "resetsAt": 1790812800
  }
}

常见错误：

HTTP	`code`	含义
400	`invalid_redeem_code`	格式错误或兑换码不存在
409	`redeem_code_used`	已被兑换
409	`plan_not_upgraded`	当前永久权益不适用该码，码未消耗
410	`redeem_code_expired`	已过期
410	`redeem_code_revoked`	已被管理员撤销
429	`redeem_locked`	兑换失败次数过多，暂时锁定兑换

redeem_locked 会带 Retry-After Header，并提供机器可读的锁定时间：

json

{
  "error": "兑换功能因连续失败已临时锁定",
  "code": "redeem_locked",
  "lockedUntil": 1788624000,
  "retryAfterSeconds": 86400
}

GET /download 和 POST /download

下载文件。fileid、type、key 必须放在 URL 查询参数中：

参数	必填	说明
`fileid`	是	待下载资源的 ID，最大 4096 字符
`type`	否	文件类型名称，默认 `file`；只接受下表中的字符串，不接受数字
`key`	否	资源密钥的 hex 字符串，必须为 16、24 或 32 字节；仅建议短期测试使用
`token`	否	短期测试 Token；正式调用推荐 Authorization Header
`anon`	否	`1` 请求匿名模式，`0` 或省略表示关闭；仅当前有效套餐为 Ultra 时启用，其他套餐忽略

type 可选值：

名称	内容
`orig`	原始图片
`normal`	默认图片
`thumb`	缩略图片
`video`	视频
`file`	文件、笔记或笔记附件（默认）
`bigfile`	大文件
`voice`	语音
`live`	默认实况图的视频部分
`origlive`	原始实况图的视频部分

GET 示例：

http

GET /download?fileid=<encoded-file-id>&type=file
Authorization: Bearer <token>

POST 可通过 application/json、application/x-www-form-urlencoded 或 multipart/form-data 补充 token。URL 中的 token 和 key 会进入浏览器历史及服务端私有日志，因此只允许用于短期 Token 的联调；正式前端应使用 Authorization Header，并优先在浏览器本地处理资源密钥。

成功响应是 application/octet-stream，并包含：

Header	说明
`Content-Length`	完整文件字节数
`X-WXCDN-Cache`	`HIT`、`MISS`；文件超过 512 MiB 时为 `BYPASS`
`X-WXCDN-Anonymous`	`enabled` 表示 Ultra 隐私下载模式已启用，`disabled` 表示未启用
`X-Quota-Limit`	字节额度，Ultra 为 `unlimited`
`X-Quota-Used`	本次下载计入后，当前周期累计使用字节数（包括 Ultra）
`X-Quota-Remaining`	本次扣减后的剩余字节，Ultra 为 `unlimited`
`X-Quota-Reset`	当前周期用量统计的下次重置 Unix 秒

额度不足返回 429、code: "quota_exceeded"，响应中同时包含最新 quota 对象。

调用建议

下载结束后刷新额度，兑换成功后直接使用返回的新权益。遇到限频时等待后重试，避免重复发送下载请求产生额外用量。

回到下载