ToAPIsToAPIs

接入方式

公共 API 用于读取当前账户的数据和管理自有普通模型 Key. 主账号不会自动获得子账号数据, 管理员也只能操作自身资源.

公共 API 用于读取当前账户的数据和管理自有普通模型 Key. 主账号不会自动获得子账号数据, 管理员也只能操作自身资源.

国际版使用 https://api.toapis.com, 国内版使用 https://api.toapis.cn. 这两个地址是 API 入口, 不要使用网站根域名调用本组接口.

获取系统访问令牌

登录账户设置, 在 "系统访问令牌" 中生成凭据. 重新生成会使旧令牌失效, 需要同步更新集成.

所有请求在 Authorization 头中携带 Bearer YOUR_SYSTEM_ACCESS_TOKEN, 每次请求只发送一个 Authorization 头. 不能用模型 API Key (sk-...), cookie, URL 凭据或 Agent/MCP 令牌代替身份, 也不需要 X-User-Id.

注意系统访问令牌可以执行 Key 写操作, 不是只读凭据.

可选请求头 X-Locale 支持 en, zh, zh-TW, ja, ko, ru; 未提供有效值时使用账户语言偏好及协商结果, 查询不会初始化账户偏好. 判断结果请用 HTTP 状态码和数字 code, 不要匹配可能随语言变化的 message.

curl https://api.toapis.com/api/v1/account \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

响应与金额

所有响应只有 code, message, data 三个顶层字段. 成功时 code=0, message="". HTTP 状态码: 常规成功为 200, 创建 Key 为 201, Webhook 测试入队和文件删除请求受理为 202.

失败时保留真实 HTTP 状态码, 错误 data 只包含 param, params, request_id 或 null, 不暴露内部错误细节.

资源 ID 和金额统一用十进制字符串表示; Webhook 的 api_key_id 使用整数; 时间为带时区的 RFC 3339 格式, 未知或不适用的值按字段约定返回 null. 余额与用量同时提供 USD 和 credits, 以响应中的 credits_per_usd 为换算基准; 支付金额保留原币种.

所有响应带 Cache-Control: private, no-store 和 X-Request-Id 头. X-Request-Id 标识本次 API 请求, 与用量 trace 中原生成请求的 ID 不是一回事.

{
  "code": 0,
  "message": "",
  "data": {
    "items": [],
    "has_more": false,
    "next_cursor": null,
    "meta": {}
  }
}

分页与时间范围

除用户文件列表外, 列表统一返回 data.items, has_more, next_cursor 和 meta. 空列表 items 为 [], 末页 next_cursor 为 null, 不返回总数. 翻页时将 next_cursor 原样作为 cursor 传入并保持原筛选条件; 修改筛选条件后要重新从第一页开始.

时间范围统一使用 UTC 半开区间 [from, to), 秒级存储的边界向上取整. 各接口的默认区间和上限不同: 用量查询每页都必须提供 from 和 to, 最长 31 天; 任务默认近 24 小时, 最长 31 天; 充值和发票默认近 31 天, 最长 366 天. 默认区间在初页确定后冻结, 翻页时可以继续省略. 未知参数, 重复参数或错误转义返回 400.

限流与错误处理

读取请求按用户共享每分钟 120 次的额度. 用量汇总, 发票和定价查询各有每分钟 6 次的额外限制, 发票列表与详情共用同一额度.

API Key, Webhook 和用户文件写操作共享每用户每分钟 10 次的额度, 不占用读取额度. 重新生成系统访问令牌不会重置限流, 新旧兼容路径也共用对应额度.

请求过于频繁或同时发送的请求过多时可能返回 429, 请按 Retry-After 加随机延迟退避. 收到 503 表示服务暂时不可用, 应降低请求频率后重试. 创建, 轮换或删除请求超时后, 不要盲目重复提交.

HTTPcode处理方式
40010001 / 10004 / 13002 / 13028 / 16014修正请求体, 参数或游标.
40111032 / 11059检查系统访问令牌.
40311023 / 12001 / 12002 / 12006 / 13003检查账户状态, 资源权限及 Key 分组.
40413001 / 16008资源不存在或不属于当前账户.
40913004 / 13005 / 13006 / 15045 / 16015 / 16016处理 Key 上限, 到期, 额度或账单关联条件.
42910002按 Retry-After 退避.
50010000 / 13029保留 request_id 排查.
50311001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029退避, 必要时缩小用量查询区间.

数据范围

主账号只能看到自身数据, 不包含成员 (子账号) 数据; 子账号不能读取账单. 用量记录是消费日志的实时快照, 会随后续结算和退款变化, 不等于最终净支出. 任务接口只返回持久化的任务元数据和可确认的账务, 不返回生成结果, 也不会主动轮询上游, 执行结算或发起退款. 充值记录不包含人工赠送额度和独立的线下退款; 发票仅覆盖当前已验证的 Stripe Customer.

Key 的资源 ID 使用列表或详情中的数字 id, 不能使用密钥字符串 (sk-...). 完整密钥只在创建和轮换响应中返回一次, 之后所有读取接口都不再返回. 写操作成功表示设置已保存, 生效可能有短暂延迟. 停用, 轮换或吊销 Key 可能使正在进行的请求或任务失败: 系统不会自动取消任务或退款, 也不提供新旧密钥的并行有效期.

接口目录

接口使用下列主要路径. 兼容期内的旧 /api/v1/account/... GET 路径及旧接口迁移方法见 变更历史.

用户文件接口管理已登记文件, 用户保留期和异步删除请求. 文件列表是分页例外: 仅返回 items, next_cursor, 末页游标为 "", 没有 has_more 或 meta. 删除请求受理返回 HTTP 202. 文件保留期设置与删除请求共用账户写预算; 用户期限依赖平台自动清理开关, 手动删除不受该开关影响. 具体范围和调用示例见下方用户文件接口.

HTTP
GET /api/v1/account获取账户资料
GET /api/v1/account/balance查询账户余额
GET /api/v1/api-keys列出 API Key
GET /api/v1/api-keys/{api_key_id}获取 API Key 详情
GET /api/v1/api-keys/{api_key_id}/balance查询 Key 余额
POST /api/v1/api-keys创建 API Key
PATCH /api/v1/api-keys/{api_key_id}更新 API Key
DELETE /api/v1/api-keys/{api_key_id}吊销 API Key
POST /api/v1/api-keys/{api_key_id}/rotate轮换 API Key
GET /api/v1/webhook查询 Webhook 配置
PATCH /api/v1/webhook更新 Webhook 配置
POST /api/v1/webhook/rotate-secret轮换 Webhook 签名密钥
POST /api/v1/webhook/test测试 Webhook
GET /api/v1/webhook/events列出 Webhook 事件
GET /api/v1/webhook/events/{event_id}查询 Webhook 事件
GET /api/v1/usage/records查询用量明细
GET /api/v1/usage/summary查询用量汇总
GET /api/v1/tasks列出账户任务
GET /api/v1/tasks/{task_id}获取账户任务详情
GET /api/v1/billing/topups列出充值订单
GET /api/v1/billing/topups/{trade_no}获取充值订单详情
GET /api/v1/billing/payment-method查询支付方式
GET /api/v1/billing/auto-topup查询自动充值配置
GET /api/v1/billing/stripe/invoices列出发票
GET /api/v1/billing/stripe/invoices/{invoice_id}获取发票详情
GET /api/v1/pricing查询模型定价
GET /api/v1/user/file列出用户文件
GET /api/v1/user/file/retention查询文件保留期
PUT /api/v1/user/file/retention设置文件保留期
POST /api/v1/user/file/deletion-requests创建文件删除请求
GET /api/v1/user/file/deletion-requests/{id}查询文件删除进度

Webhook

接入顺序:

  1. 调用 POST /api/v1/webhook/rotate-secret 生成签名密钥并保存到接收端.
  2. 调用 PATCH /api/v1/webhook 设置回调地址并启用.
  3. 调用 POST /api/v1/webhook/test 发送测试事件或查询事件列表确认投递结果.

验签规则与完整步骤见查询 Webhook 配置.

On this page