接入说明
使用系统访问令牌查询账户资料, 余额, API Key, 用量, 任务和账单
国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://toapis.com 请替换为 https://toapis.cn.
这组 GET 接口只读取当前账户的数据. 主账号不自动获得子账号数据, 管理员也只能查询自身. 账户查询使用系统访问令牌, 与模型调用使用的 API Key 不同.
获取系统访问令牌
登录控制台, 在 设置 的 "系统访问令牌" 中生成令牌. 重新生成会使旧令牌失效, 需要同步更新已有集成. 这里查询操作是只读的, 但该令牌在旧接口上仍保留原有权限, 不应视为严格只读凭据.
每个请求只发送一个 Authorization 请求头. 不接受 cookie, URL 凭据, 模型 API Key, Agent 或 MCP 令牌代替身份, 无需 X-User-Id. 可选 X-Locale 支持 en, zh, zh-TW, ja, ko, ru; 未提供有效值时按账户偏好及语言协商规则处理.
curl --request GET \
--url 'https://toapis.com/api/v1/account' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'响应与金额
成功时 HTTP 200, code=0, message=""; 失败保留真实 HTTP 状态, code 为数字错误码. 客户端按 HTTP 状态和 code 判断, 不匹配可能翻译的 message. ID 和金额使用字符串, 时间为带时区的 RFC 3339, 未知或不适用的字段按契约返回 null.
余额和用量同时提供 USD 与 credits, 使用同一额度快照换算. 以 credits_per_usd 为实际基准, 不硬编码旧余额接口中的换算值. 支付金额保留原币种, 不与 credits 混用.
响应包含 Cache-Control: private, no-store 和 X-Request-Id. 后者标识本次查询, 与用量记录 trace 中原生成请求的 ID 不同.
{"code": 0, "message": "", "data": {"items": [], "has_more": false, "next_cursor": null, "meta": {}}}分页与时间范围
列表统一返回 data.items, has_more, next_cursor, meta. 空列表为 [], 末页游标为 null. 将 next_cursor 原样作为下一页的 cursor, 保留筛选条件, 不解析游标. 改变筛选后重新开始, 不默认计算总数.
时间按 UTC 半开区间 [from,to) 比较, 秒级存储的两端边界向上取整. from 和 to 成对提供, 用量查询两者始终必填. 任务默认近 24 小时, 最长 31 天; 充值和发票默认近 31 天, 最长 366 天. 默认区间在初页冻结, 翻页时可继续省略时间. 未知参数, 重复标量和错误转义均返回 400.
限流与错误处理
同一用户合计 120 次/分钟, 用量汇总额外 6 次/分钟, 发票列表与详情另共享 6 次/分钟. 收到 429 时按 Retry-After 退避并加入随机抖动. Redis 不可用时, 轻查询降级为每节点每 IP 桶和每用户各 30 次/分钟, 汇总和发票返回 503.
| HTTP | code | 处理 |
|---|---|---|
| 400 | 10004 / 13028 | 修正参数或游标, 不原样重试. |
| 401 | 11032 / 11059 | 检查系统访问令牌是否缺失, 无效或已轮换. |
| 403 | 11023 / 12001 / 12002 / 12006 | 检查账户状态和权限; 子账号不能读取账单. |
| 404 | 13001 | 资源不存在或不属于当前账户. |
| 429 | 10002 | 按 Retry-After 退避. |
| 500 | 10000 / 13029 | 保留请求 ID 排查内部错误或金额换算配置. |
| 503 | 11001 / 13030 / 13032 | 退避; 用量超时时可缩小时间范围. |
| 409 | 15045 | 通过现有交互流程关联账单账户, 不原样重试. |
| 503 | 15046 / 15047 | 退避或联系支持核查 Stripe 配置和 Customer 映射. |
{
"code": 10004,
"message": "Invalid query parameters.",
"data": {
"param": "limit",
"request_id": "request_example_query"
}
}数据范围
用量是可变消费日志快照, 结算和退款可能更新旧记录, 不代表完整净支出账本. 任务只返回持久化元数据与可确认账务, 不返回生成结果, 不主动轮询, 结算或退款. 充值仅含订单, 不含人工赠送或独立线下退款. 发票仅覆盖当前已验证的 Stripe Customer.
| GET | 使用说明 |
|---|---|
/api/v1/account | 获取账户资料 |
/api/v1/account/balance | 查询账户余额 |
/api/v1/account/api-keys | 列出 API Key |
/api/v1/account/api-keys/{api_key_id} | 获取 API Key 详情 |
/api/v1/account/usage/records | 查询用量明细 |
/api/v1/account/usage/summary | 查询用量汇总 |
/api/v1/account/tasks | 列出账户任务 |
/api/v1/account/tasks/{task_id} | 获取账户任务详情 |
/api/v1/account/billing/topups | 列出充值订单 |
/api/v1/account/billing/topups/{trade_no} | 获取充值订单详情 |
/api/v1/account/billing/payment-method | 查询支付方式 |
/api/v1/account/billing/auto-topup | 查询自动充值配置 |
/api/v1/account/billing/invoices | 列出发票 |
/api/v1/account/billing/invoices/{invoice_id} | 获取发票详情 |
与现有接口的区别
现有 令牌余额, 用户余额 和 创建令牌 保留各自的接口约定. 本组 API 使用系统访问令牌和 code/message/data 响应, 不与旧接口混用. 账户任务查询不替代生成接口的结果查询.