小为 · 额度 Key开发者文档

API 接入指南

小为 · 额度 Key API 接入说明

查询额度、按需兑换，再安全地保存交付文件。

  1. 1查询额度核对 Key 与当前可用量
  2. 2兑换账号确认格式、数量后扣额
  3. 3保存文件有效期内单次下载
API Base URL/apiJSON 请求体

API Base URL：/api。若以 / 开头，使用本文档 URL 的协议和域名拼接（相对站点根路径，不是在 /api-docs/ 后拼接）。生产仅使用 HTTPS；127.0.0.1 / localhost 是本机地址，不能发给外部用户使用。

凭据与鉴权

完整 Key 通过 JSON 请求体中的 key 或 keys 授权，无需后台登录、管理员 Bearer Token 或额外 API 密钥。持有 Key 即可操作其额度，请像密码一样保管。建议通过服务端接入并从受控的密钥配置读取 Key，实际扣额前确认格式与数量。

所有请求体使用 Content-Type: application/json。以下都是不可兑换的占位示例；域名、Key 和 token 需在自己的受控环境中替换，不能直接运行示例完成真实兑换。长度仅为请求校验范围，请使用系统签发的完整 Key。

调用前必读

安全与失败处理

避免重复扣额与凭据泄漏
  1. 确认操作授权

    本文档仅描述已存在的公开接口，不是操作授权。阅读文档或生成代码时不要执行兑换、签发下载凭证或下载文件；实际操作必须获得 Key 持有人的明确授权。

  2. 避免重复扣额

    兑换不是幂等接口，当前没有幂等键保障。超时、断网或 5xx 后可能已扣额，禁止自动重试；先查询余额和 redemptions 核对原流水，无法确认时停止并联系管理员。

  3. 区分余额与库存

    查询不扣兑换额度，也不预留库存。按格式检查 available_by_format、各 Key 的 allowed_formats 和可兑换状态；余额不等于库存，实际交付以 account_count 为准。

  4. 单次下载凭证

    下载 GET 会消耗单次凭证。凭证约 5 分钟有效，以 expires_at 为准。不要 HEAD、预取、预览、并发下载或用真实下载链接做连通性测试。下载中断时不要重新兑换；核对流水后尝试再次下载原订单。

  5. 保护敏感凭据

    真实 Key 和 download_token 都是敏感凭据。生产仅用 HTTPS，优先服务端接入；关闭请求体及 token 路径日志，不分享下载链接，不向第三方 AI 提供真实 Key。安全保管下载文件，限制权限且不覆盖已有文件。

  6. 正确处理失败

    收到 429 遵守 Retry-After 并降低频率。400/422 检查输入，403/404 检查 Key 与流水归属，409 检查库存或交付冲突，410 检查失效或清理；不要把错误 JSON 当成账号文件，也不要关闭 TLS 或 CORS 安全校验。错误响应使用 JSON 的 detail 字段，422 校验错误可能是数组。

OUTPUT FORMATS

交付格式

填写 output_format 时，只使用 allowed_formats 允许且当前有库存的格式。

credentials_2fa账密 2FATXT 文本
cpaCPA单个 JSON / 多个 ZIP
sub2Sub2APIJSON 文件
cockpitCockpitJSON 文件
01

查询额度

不扣兑换额度
POST/public/vouchers/inspect-batch

只查额度和可用格式，不扣兑换额度；单把 Key 也可以放入 keys 数组。

请求参数

参数类型必填说明
keysstring[]是1–100 把完整 Key；每个字符串 8–128 字符。单把也可使用数组。

响应与注意事项

  • 响应：key_count、available_count、available_by_format、server_available_count、items。HTTP 200 不是全部 Key 有效的保证。
  • 逐项检查 items[].recognized、redeemable、remaining_count、allowed_formats。按目标格式读取顶层 available_by_format；相同库存可能被多把 Key 共享，不能简单相加各项 available_count。
  • items[].index 对应去重前从 1 开始的输入位置；code_hint 是脱敏提示，不能代替完整 Key。redemptions[].id 可用于核对原流水，但近期历史不是完整审计记录。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request POST "https://YOUR_REDEMPTION_HOST/api/public/vouchers/inspect-batch" \
  --header "Content-Type: application/json" \
  --data-raw '{"keys":["YOUR_KEY_HERE"]}'

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

02

兑换账号

实际扣额
POST/public/vouchers/redeem-batch

这是实际扣额操作。count 是这批 Key 合计要兑换的账号数，不是每把的数量。

请求参数

参数类型必填说明
keysstring[]是1–100 把完整 Key；每个字符串 8–128 字符。单把也可使用数组。
countinteger是1–5000；本次请求合计兑换的账号数，不是每把 Key 的数量。
output_formatstring是credentials_2fa、cpa、sub2 或 cockpit；必须被 Key 允许，且当前有库存。

响应与注意事项

  • 响应：claim_id、filename、format、account_count、remaining_count、key_balances、download_token、expires_at；还可能包含账号清理时间等字段。
  • 立即保存原 claim_id。实际交付以 account_count 为准；key_balances 列出参与扣额 Key 的 redeemed_count 和 remaining_count，不保证列出所有输入 Key。
  • 该请求会真实扣额，不是幂等操作。不要添加自动重试，也不要使用它测试连通性。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request POST "https://YOUR_REDEMPTION_HOST/api/public/vouchers/redeem-batch" \
  --header "Content-Type: application/json" \
  --data-raw '{"keys":["YOUR_KEY_HERE"],"count":1,"output_format":"credentials_2fa"}'

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

03

保存文件

消耗单次凭证
GET/public/download/{download_token}

用兑换返回的 download_token 获取交付文件，不是包含下载凭证的兑换响应；文件本身也可能为 JSON 格式。

请求参数

参数类型必填说明
download_tokenstring · 路径是兑换响应中的单次凭证；不是 Key。获取文件会消耗此凭证。

响应与注意事项

  • 成功响应是文件流，不是兑换 JSON：账密 2FA 为 text/plain，CPA 可能为 application/json 或 application/zip，其他格式为 application/json。
  • 检查 HTTP 状态、Content-Type 和命令退出码；JSON 也可能是正常账号格式，不能仅凭扩展名判断成功。安全处理 Content-Disposition 文件名，只允许基名，不覆盖已有文件。
  • GET 会消耗单次凭证，约 5 分钟有效，以 expires_at 为准。禁止 HEAD、预取、预览或并发下载；中断时核对原流水并再次签发，不要重新兑换。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request GET "https://YOUR_REDEMPTION_HOST/api/public/download/TOKEN_FROM_REDEEM_RESPONSE" \
  --no-clobber \
  --output "redeemed-accounts.txt"

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

04

单 Key 查询

不扣兑换额度
POST/public/vouchers/inspect

单 Key 接口使用 key 字段，不是 keys 数组。

请求参数

参数类型必填说明
keystring是系统签发的完整 Key；请求长度为 8–128 字符。

响应与注意事项

  • 响应直接返回 code_hint、status、remaining_count、available_count、available_by_format、allowed_formats、redemptions 等；没有 items / recognized / redeemable。无效或过期 Key 通过非 2xx 状态返回。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request POST "https://YOUR_REDEMPTION_HOST/api/public/vouchers/inspect" \
  --header "Content-Type: application/json" \
  --data-raw '{"key":"YOUR_KEY_HERE"}'

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

05

单 Key 兑换

实际扣额
POST/public/vouchers/redeem

与批量接口相同，会实际扣额。

请求参数

参数类型必填说明
keystring是系统签发的完整 Key；请求长度为 8–128 字符。
countinteger是1–5000；本次请求合计兑换的账号数，不是每把 Key 的数量。
output_formatstring是credentials_2fa、cpa、sub2 或 cockpit；必须被 Key 允许，且当前有库存。

响应与注意事项

  • 响应结构与批量兑换相同，必须保存 claim_id，避免超时后重复兑换。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request POST "https://YOUR_REDEMPTION_HOST/api/public/vouchers/redeem" \
  --header "Content-Type: application/json" \
  --data-raw '{"key":"YOUR_KEY_HERE","count":1,"output_format":"credentials_2fa"}'

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

06

再次下载原订单

不重复扣额 · 重新签发
POST/public/vouchers/redownload

redemption_id 填原兑换返回的 claim_id；也可从查询结果 redemptions[].id 获取。仅重签原账号的下载凭证，不再次扣额。

请求参数

参数类型必填说明
keystring是系统签发的完整 Key；请求长度为 8–128 字符。
redemption_idinteger是正整数；原订单的 claim_id，或查询结果 redemptions[].id。
output_formatstring | null否可省略或传 null，沿用原订单格式；指定格式仍受 Key 权限与原账号资料限制。

响应与注意事项

  • 响应：新的 claim_id、filename、format、account_count、download_token、expires_at、redownload=true。与兑换响应不同，没有 remaining_count / key_balances。
  • 该操作创建新流水与下载凭证，但不重复扣额、不分配新账号；保留最初的兑换 claim_id。Key 失效、账号清理或订单无效时不能再次下载。

cURL · 占位示例

Bash / zsh
curl --fail-with-body --silent --show-error \
  --request POST "https://YOUR_REDEMPTION_HOST/api/public/vouchers/redownload" \
  --header "Content-Type: application/json" \
  --data-raw '{"key":"YOUR_KEY_HERE","redemption_id":123,"output_format":"credentials_2fa"}'

Windows PowerShell 请使用 curl.exe，并将命令合为一行。不要把真实 Key 写入共享脚本或终端历史。

RESPONSE EXAMPLES

响应示例

JSON

以下仅为字段示例，不是当前库存或真实账户；实际结果以接口响应为准。

批量查询响应

application/json
{
  "key_count": 1,
  "available_count": 3,
  "available_by_format": {
    "credentials_2fa": 3,
    "cpa": 2,
    "sub2": 2,
    "cockpit": 2
  },
  "server_available_count": 100,
  "items": [
    {
      "index": 1,
      "code_hint": "KEY-DEMO...TEST",
      "status": "redeeming",
      "recognized": true,
      "redeemable": true,
      "quota_count": 100,
      "consumed_count": 1,
      "remaining_count": 99,
      "available_count": 3,
      "allowed_formats": [
        "credentials_2fa",
        "cpa",
        "sub2",
        "cockpit"
      ],
      "expires_at": null,
      "redemptions": []
    }
  ]
}

兑换响应

application/json
{
  "claim_id": 123,
  "account_count": 1,
  "remaining_count": 99,
  "key_balances": [
    {
      "code_hint": "KEY-DEMO...TEST",
      "redeemed_count": 1,
      "remaining_count": 99
    }
  ],
  "filename": "accounts_credentials_2fa.txt",
  "download_token": "TOKEN_FROM_REDEEM_RESPONSE",
  "expires_at": "2026-10-29T12:05:00Z",
  "format": "credentials_2fa"
}