接入方式
公共 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 表示服务暂时不可用, 应降低请求频率后重试. 创建, 轮换或删除请求超时后, 不要盲目重复提交.
| HTTP | code | 处理方式 |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | 修正请求体, 参数或游标. |
| 401 | 11032 / 11059 | 检查系统访问令牌. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | 检查账户状态, 资源权限及 Key 分组. |
| 404 | 13001 / 16008 | 资源不存在或不属于当前账户. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | 处理 Key 上限, 到期, 额度或账单关联条件. |
| 429 | 10002 | 按 Retry-After 退避. |
| 500 | 10000 / 13029 | 保留 request_id 排查. |
| 503 | 11001 / 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
接入顺序:
- 调用
POST /api/v1/webhook/rotate-secret生成签名密钥并保存到接收端. - 调用
PATCH /api/v1/webhook设置回调地址并启用. - 调用
POST /api/v1/webhook/test发送测试事件或查询事件列表确认投递结果.
验签规则与完整步骤见查询 Webhook 配置.