API contract 工作样本 · 非官方，mock 数据
API Reference
OpenAI 兼容。一把 key，一个余额，provider fallback 内置。
Base URL
https://api.sub2api.com/v1所有请求走 HTTPS。Base URL 与 OpenAI 兼容——改 host 即可迁移现有代码。
Authentication
所有请求需携带 Bearer token。在 Dashboard → API Keys 获取。
Authorization: Bearer $SUB2API_KEY密钥勿泄露。随时可在 dashboard 更换。无有效 key 的请求返回 401 invalid_api_key。
Quickstart
Contract 级示例，展示完整的请求与响应格式——非真实端点。
请求
curl https://api.sub2api.com/v1/chat/completions \
-H "Authorization: Bearer $SUB2API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello"}]
}'Chat Completions
POST /v1/chat/completions
OpenAI 兼容的 chat 端点。响应中包含 Sub2API 特有字段：provider、routing、fallback、billing。
请求体
{
"model": "gpt-4o", // 必填 — 模型 ID，来自 /v1/models
"messages": [ // 必填
{"role": "user", "content": "Hello"}
],
"provider": "auto", // 可选 — "auto" 或指定 provider id
"fallback": true, // 可选 — 默认 true
"max_tokens": 1024, // 可选
"temperature": 0.7 // 可选
}响应
{
"id": "chatcmpl-9a8b7c6d5e4f",
"object": "chat.completion",
"model": "gpt-4o",
"provider": "openai",
"routing": "auto",
"fallback": false,
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "Hi! How can I help you today?"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 8,
"completion_tokens": 9,
"total_tokens": 17
},
"billing": {
"credits_used": 0.04,
"balance_after": 18.73,
"currency": "USD"
}
}List Models
GET /v1/models
返回可用模型列表，含 provider、定价和状态。
{
"object": "list",
"data": [{
"id": "gpt-4o",
"provider": "openai",
"status": "live",
"pricing": {
"input": 2.50,
"output": 10.00,
"unit": "per 1M tokens"
}
}, {
"id": "claude-sonnet-4-6",
"provider": "anthropic",
"status": "live",
"pricing": {
"input": 3.00,
"output": 15.00,
"unit": "per 1M tokens"
}
}]
}Usage
GET /v1/usage
返回当前计费周期的用量摘要。支持可选参数 ?days=7 或 ?days=30。
{
"period": "2026-06-01 to 2026-06-26",
"total_credits_used": 12.84,
"total_requests": 342,
"by_model": [{
"model": "gpt-4o",
"requests": 210,
"credits_used": 8.15
}, {
"model": "claude-sonnet-4-6",
"requests": 98,
"credits_used": 3.92
}],
"balance_remaining": 18.73
}Error Codes
| Status | Code | 说明 |
|---|---|---|
| 401 | invalid_api_key | API key 缺失或无效 |
| 402 | insufficient_balance | 余额不足，请在 dashboard 充值 |
| 429 | rate_limited | 请求过于频繁，查看 Retry-After 响应头 |
| 503 | provider_unavailable | Provider 故障且无可用 fallback |
| 500 | internal_error | 我方内部错误，正在处理 |
Rate Limits
| Plan | 请求 / 分钟 | Token / 分钟 |
|---|---|---|
| Free | 10 | 10,000 |
| Starter | 100 | 200,000 |
| Pro | 1,000 | 2,000,000 |
超出限制返回 429 rate_limited。查看 Retry-After 响应头获取等待秒数。
Billing 字段
每个消耗 credits 的 API 响应都包含 billing 对象，无需额外调用 dashboard 即可追踪消费。
{
"billing": {
"credits_used": 0.42, // 本次请求消耗的 credits
"balance_after": 18.73, // 本次请求后的剩余余额
"currency": "USD", // 计费币种
"model": "gpt-4o", // 本次请求使用的模型
"provider": "openai", // 实际服务的 provider
"routing": "auto" // 路由模式："auto" 或 "manual"
}
}