Skip to content

API.md

Latest commit

 

History

History
1232 lines (992 loc) · 24.9 KB

API.md

File metadata and controls

1232 lines (992 loc) · 24.9 KB

Codex2API API 文档

本文档详细描述 Codex2API 的所有 API 端点、请求/响应格式以及错误码说明。

目录

概述

Codex2API 提供兼容 OpenAI 风格的 API 接口，同时包含完整的管理后台 API。

Base URL: http://localhost:8080 (默认端口)

请求格式:

  • 请求头: Content-Type: application/json
  • 认证头: Authorization: Bearer <api_key>

认证

API Key 认证

公共 API (/v1/*) 需要 API Key 进行认证。

请求头:

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

配置方式:

  1. 通过管理后台 /admin/settings 页面配置
  2. 如果没有配置任何 API Key，则 /v1/* 接口跳过鉴权（开发模式）

Admin Secret 认证

管理 API (/api/admin/*) 需要 Admin Secret 进行认证。

请求头:

X-Admin-Key: your-admin-secret

或

Authorization: Bearer your-admin-secret

配置方式:

  • 环境变量: ADMIN_SECRET
  • 数据库: 通过管理后台设置

公共 API

1. Chat Completions

端点: POST /v1/chat/completions

说明: OpenAI 风格的 Chat Completions 接口，支持流式和非流式响应。

请求示例:

{
  "model": "gpt-5.4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "reasoning_effort": "medium",
  "service_tier": "fast"
}

参数说明:

参数 类型 必填 说明
model string 是 模型名称，见 支持模型
messages array 是 消息列表
stream boolean 否 是否启用流式响应，默认 false
reasoning_effort string 否 推理强度: low/medium/high
service_tier string 否 服务等级: fast/auto
max_tokens integer 否 最大输出 token 数（Codex 不支持，会被过滤）
temperature float 否 温度参数（Codex 不支持，会被过滤）

非流式响应示例:

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 15,
    "total_tokens": 40
  }
}

流式响应示例:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.4","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1712345678,"model":"gpt-5.4","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

2. Responses

端点: POST /v1/responses

说明: Codex 原生 Responses 接口，直接透传，无需协议翻译。

请求示例:

{
  "model": "gpt-5.4",
  "input": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "reasoning": {
    "effort": "medium"
  },
  "service_tier": "fast",
  "include": ["reasoning.encrypted_content"]
}

参数说明:

参数 类型 必填 说明
model string 是 模型名称
input array/string 是 输入内容（支持数组或字符串）
stream boolean 否 是否启用流式响应，默认 false。仅当显式传 stream=true 时返回 SSE（流式响应），否则返回普通 JSON。
reasoning.effort string 否 推理强度: low/medium/high
service_tier string 否 服务等级: fast/auto
include array 否 包含的额外字段
previous_response_id string 否 上一响应 ID，用于上下文连续

响应示例:

{
  "id": "resp_xxxxxxxx",
  "object": "response",
  "created": 1712345678,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 15,
    "total_tokens": 40
  }
}

3. List Models

端点: GET /v1/models

说明: 获取支持的模型列表。

响应示例:

{
  "object": "list",
  "data": [
    {"id": "gpt-5.4", "object": "model", "owned_by": "openai"},
    {"id": "gpt-5.4-mini", "object": "model", "owned_by": "openai"},
    {"id": "gpt-5", "object": "model", "owned_by": "openai"}
  ]
}

4. Health Check

端点: GET /health

说明: 健康检查端点，返回服务状态。

响应示例:

{
  "status": "ok",
  "available": 5,
  "total": 8
}

管理 API

所有管理 API 需要 X-Admin-Key 请求头进行认证。

统计接口

GET /api/admin/stats

获取仪表盘统计数据。

响应:

{
  "total": 10,
  "available": 8,
  "error": 2,
  "today_requests": 1234
}

GET /api/admin/health

系统健康检查（扩展版）。

响应:

{
  "status": "ok",
  "available": 8,
  "total": 10
}

账号管理

GET /api/admin/accounts

获取账号列表。

响应:

{
  "accounts": [
    {
      "id": 1,
      "name": "account-1",
      "email": "user@example.com",
      "plan_type": "pro",
      "status": "ready",
      "health_tier": "healthy",
      "scheduler_score": 100,
      "dynamic_concurrency_limit": 2,
      "proxy_url": "http://proxy.example.com:8080",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z",
      "active_requests": 0,
      "total_requests": 100,
      "last_used_at": "2024-01-01T11:00:00Z",
      "success_requests": 95,
      "error_requests": 5,
      "usage_percent_7d": 45.2,
      "usage_percent_5h": 12.5,
      "reset_5h_at": "2024-01-01T17:00:00Z",
      "reset_7d_at": "2024-01-08T00:00:00Z",
      "scheduler_breakdown": {
        "unauthorized_penalty": 0,
        "rate_limit_penalty": 0,
        "timeout_penalty": 0,
        "server_penalty": 0,
        "failure_penalty": 0,
        "success_bonus": 12,
        "usage_penalty_7d": -5,
        "latency_penalty": 0,
        "success_rate_penalty": 0
      }
    }
  ]
}

POST /api/admin/accounts

添加 Refresh Token 账号（支持批量）。

请求:

{
  "name": "my-account",
  "refresh_token": "rt_xxxxxxxxxxxx",
  "proxy_url": "http://proxy.example.com:8080"
}

参数说明:

参数 类型 必填 说明
name string 否 账号名称，批量时自动追加序号，默认 account-{n}
refresh_token string 是 Refresh Token，多个用 \n 换行分隔（单次最多 100 个）
proxy_url string 否 代理 URL

批量添加（使用换行分隔）:

{
  "name": "batch",
  "refresh_token": "rt_xxx1\nrt_xxx2\nrt_xxx3",
  "proxy_url": ""
}

响应:

{
  "message": "成功添加 3 个账号",
  "success": 3,
  "failed": 0
}

curl 示例:

单个添加:

curl -X POST http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-account", "refresh_token": "rt_xxxxxxxxxxxx", "proxy_url": ""}'

批量添加（换行分隔）:

curl -X POST http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "batch", "refresh_token": "rt_xxx1\nrt_xxx2\nrt_xxx3"}'

添加后系统自动在后台刷新 Access Token，无需手动触发。

POST /api/admin/accounts/at

添加 Access Token（AT-only）账号（支持批量）。适用于只有 AT 没有 RT 的场景。

请求:

{
  "name": "my-at-account",
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "proxy_url": "http://proxy.example.com:8080"
}

参数说明:

参数 类型 必填 说明
name string 否 账号名称，批量时自动追加序号，默认 at-account-{n}
access_token string 是 Access Token，多个用 \n 换行分隔（单次最多 100 个）
proxy_url string 否 代理 URL

批量添加:

{
  "name": "batch-at",
  "access_token": "eyJtoken1...\neyJtoken2...\neyJtoken3...",
  "proxy_url": ""
}

响应:

{
  "message": "成功添加 3 个 AT 账号",
  "success": 3,
  "failed": 0
}

curl 示例:

curl -X POST http://localhost:8080/api/admin/accounts/at \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-at", "access_token": "eyJhbGciOiJSUzI1NiIs..."}'

AT-only 账号无法自动刷新，过期后需重新添加。系统会自动解析 JWT 提取 email、plan_type 等信息。

DELETE /api/admin/accounts/:id

删除账号（软删除，标记为 deleted）。

响应:

{
  "message": "账号已删除"
}

POST /api/admin/accounts/:id/refresh

手动刷新账号 Access Token。

响应:

{
  "message": "账号刷新成功"
}

GET /api/admin/accounts/:id/test

测试账号连接。

响应:

{
  "success": true,
  "latency_ms": 523,
  "message": "连接正常"
}

GET /api/admin/accounts/:id/usage

获取单个账号用量统计。

响应:

{
  "id": 1,
  "name": "account-1",
  "total_requests": 100,
  "total_tokens": 5000,
  "last_7d_requests": 500,
  "last_7d_tokens": 25000
}

POST /api/admin/accounts/import

批量导入账号（支持 TXT/JSON/AT-TXT 三种格式）。

请求:

  • Method: POST
  • Content-Type: multipart/form-data

Form 字段:

字段 类型 必填 说明
file file 是 上传文件（最大 2MB，JSON 格式支持多文件）
format string 否 文件格式：txt（默认）、json、at_txt
proxy_url string 否 代理 URL

format 格式说明:

  • txt — 每行一个 Refresh Token:

    rt_xxxxxx1
rt_xxxxxx2
rt_xxxxxx3

  • json — CLIProxyAPI 凭证 JSON 格式（支持数组或单对象）:

    [
  {"refresh_token": "rt_xxx1", "email": "user1@example.com"},
  {"refresh_token": "rt_xxx2", "email": "user2@example.com"}
]

  • at_txt — 每行一个 Access Token（AT-only 模式）:

    eyJhbGciOiJSUzI1NiIs...token1
eyJhbGciOiJSUzI1NiIs...token2

所有格式均自动文件内去重 + 数据库去重，已存在的 Token 计入 duplicate 不重复导入。

curl 示例:

导入 RT（TXT 格式）:

curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@tokens.txt" \
  -F "format=txt" \
  -F "proxy_url=http://proxy.example.com:8080"

导入 RT（JSON 格式）:

curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@credentials.json" \
  -F "format=json"

导入 AT（AT-TXT 格式）:

curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@access_tokens.txt" \
  -F "format=at_txt"

响应: SSE 流式进度

data: {"type":"progress","current":5,"total":10,"success":3,"duplicate":1,"failed":1}

data: {"type":"complete","current":10,"total":10,"success":8,"duplicate":1,"failed":1}

若所有 Token 均已存在，返回普通 JSON（非 SSE）:

{
  "message": "所有 10 个 RT 已存在，无需导入",
  "success": 0,
  "duplicate": 10,
  "failed": 0,
  "total": 10
}

POST /api/admin/accounts/batch-test

批量测试账号连接。

请求:

{
  "ids": [1, 2, 3],
  "concurrency": 5
}

响应: SSE 流式进度

data: {"type":"progress","current":3,"total":3,"success":2,"failed":1}

data: {"type":"complete","current":3,"total":3,"success":2,"failed":1}

POST /api/admin/accounts/clean-banned

清理 Unauthorized（401）账号。

响应:

{
  "message": "已清理 5 个账号",
  "cleaned": 5
}

POST /api/admin/accounts/clean-rate-limited

清理 Rate Limited（429）账号。

POST /api/admin/accounts/clean-error

清理 Error 状态账号。

GET /api/admin/accounts/export

导出账号（标准 JSON 格式）。

查询参数:

  • filter: healthy (只导出健康账号)
  • ids: 1,2,3 (指定 ID 列表)
  • remote: true (远程迁移模式)

响应:

[
  {
    "type": "codex",
    "email": "user@example.com",
    "expired": "2024-12-31T23:59:59Z",
    "id_token": "id_xxx",
    "account_id": "acc_xxx",
    "access_token": "at_xxx",
    "last_refresh": "2024-01-01T12:00:00Z",
    "refresh_token": "rt_xxx"
  }
]

POST /api/admin/accounts/migrate

从远程 codex2api 实例迁移账号。

请求:

{
  "url": "http://remote-instance:8080",
  "admin_key": "remote-admin-secret"
}

响应: SSE 流式进度

GET /api/admin/accounts/event-trend

获取账号增删趋势。

查询参数:

  • start: RFC3339 格式开始时间
  • end: RFC3339 格式结束时间
  • bucket_minutes: 聚合桶大小（默认 60）

响应:

{
  "trend": [
    {"timestamp": "2024-01-01T00:00:00Z", "added": 5, "deleted": 0}
  ]
}

用量统计

GET /api/admin/usage/stats

获取使用统计。

响应:

{
  "total_requests": 10000,
  "total_tokens": 500000,
  "today_requests": 500,
  "today_tokens": 25000,
  "rpm": 50,
  "tpm": 2500,
  "error_rate": 0.02
}

GET /api/admin/usage/logs

获取使用日志。

查询参数:

  • start: RFC3339 开始时间
  • end: RFC3339 结束时间
  • page: 页码
  • page_size: 每页条数 (最大 200)
  • email: 按账号邮箱过滤
  • model: 按模型过滤
  • endpoint: 按端点过滤
  • api_key_id: 按 API 密钥 ID 过滤
  • fast: true/false (是否 fast 服务)
  • stream: true/false (是否流式)

响应:

{
  "logs": [
    {
      "id": 1,
      "account_id": 1,
      "account_email": "user@example.com",
      "api_key_id": 3,
      "api_key_name": "Team A",
      "api_key_masked": "sk-t****...****1234",
      "endpoint": "/v1/chat/completions",
      "model": "gpt-5.4",
      "status_code": 200,
      "duration_ms": 523,
      "first_token_ms": 150,
      "prompt_tokens": 25,
      "completion_tokens": 15,
      "total_tokens": 40,
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 1000
}

GET /api/admin/usage/chart-data

获取图表聚合数据。

查询参数:

  • start: RFC3339 开始时间
  • end: RFC3339 结束时间
  • bucket_minutes: 聚合桶大小（默认 5）

响应:

{
  "buckets": [
    {
      "time": "2024-01-01T12:00:00Z",
      "requests": 50,
      "tokens": 2500,
      "latency_ms": 500
    }
  ],
  "total_requests": 1000,
  "total_tokens": 50000
}

DELETE /api/admin/usage/logs

清空使用日志。

响应:

{
  "message": "日志已清空"
}

API Key 管理

GET /api/admin/keys

获取所有 API 密钥。

响应:

{
  "keys": [
    {
      "id": 1,
      "name": "default",
      "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/admin/keys

创建新 API 密钥。

请求:

{
  "name": "production",
  "key": "sk-custom-key"  // 可选，不填则自动生成
}

响应:

{
  "id": 2,
  "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "production"
}

DELETE /api/admin/keys/:id

删除 API 密钥。

响应:

{
  "message": "已删除"
}

系统设置

GET /api/admin/settings

获取系统设置。

响应:

{
  "max_concurrency": 2,
  "global_rpm": 0,
  "test_model": "gpt-5.4",
  "test_concurrency": 50,
  "proxy_url": "",
  "pg_max_conns": 50,
  "redis_pool_size": 30,
  "auto_clean_unauthorized": false,
  "auto_clean_rate_limited": false,
  "auto_clean_full_usage": false,
  "auto_clean_error": false,
  "proxy_pool_enabled": false,
  "fast_scheduler_enabled": false,
  "max_retries": 3,
  "allow_remote_migration": false,
  "database_driver": "postgres",
  "database_label": "PostgreSQL",
  "cache_driver": "redis",
  "cache_label": "Redis",
  "admin_secret": "",
  "admin_auth_source": "env"
}

PUT /api/admin/settings

更新系统设置。

请求:

{
  "max_concurrency": 4,
  "global_rpm": 100,
  "test_model": "gpt-5.4",
  "test_concurrency": 50,
  "proxy_url": "http://proxy.example.com:8080",
  "auto_clean_unauthorized": true,
  "auto_clean_rate_limited": false,
  "fast_scheduler_enabled": true
}

响应: 更新后的完整设置对象

代理池管理

GET /api/admin/proxies

获取代理列表。

响应:

{
  "proxies": [
    {
      "id": 1,
      "url": "http://proxy1.example.com:8080",
      "label": "US Proxy",
      "enabled": true,
      "last_tested_at": "2024-01-01T12:00:00Z",
      "last_test_result": "ok",
      "latency_ms": 150
    }
  ]
}

POST /api/admin/proxies

添加代理（支持批量）。

请求:

{
  "urls": ["http://proxy1.example.com:8080", "http://proxy2.example.com:8080"],
  "label": "Batch Add"
}

或单条:

{
  "url": "http://proxy.example.com:8080",
  "label": "US Proxy"
}

DELETE /api/admin/proxies/:id

删除代理。

PATCH /api/admin/proxies/:id

更新代理。

请求:

{
  "label": "New Label",
  "enabled": false
}

POST /api/admin/proxies/batch-delete

批量删除代理。

请求:

{
  "ids": [1, 2, 3]
}

POST /api/admin/proxies/test

测试代理连通性。

请求:

{
  "url": "http://proxy.example.com:8080",
  "id": 1,  // 可选，用于持久化测试结果
  "lang": "zh-CN"
}

响应:

{
  "success": true,
  "ip": "1.2.3.4",
  "country": "United States",
  "region": "California",
  "city": "Los Angeles",
  "isp": "Example ISP",
  "latency_ms": 150,
  "location": "United States·California·Los Angeles"
}

运维监控

GET /api/admin/ops/overview

获取系统运维概览。

响应:

{
  "updated_at": "2024-01-01T12:00:00Z",
  "uptime_seconds": 86400,
  "database_driver": "postgres",
  "database_label": "PostgreSQL",
  "cache_driver": "redis",
  "cache_label": "Redis",
  "cpu": {
    "percent": 25.5,
    "cores": 8
  },
  "memory": {
    "percent": 60.2,
    "used_bytes": 6442450944,
    "total_bytes": 10737418240
  },
  "runtime": {
    "goroutines": 50,
    "available_accounts": 8,
    "total_accounts": 10
  },
  "requests": {
    "active": 5,
    "total": 10000
  },
  "postgres": {
    "healthy": true,
    "open": 10,
    "in_use": 5,
    "idle": 5,
    "max_open": 50,
    "wait_count": 0,
    "usage_percent": 20
  },
  "redis": {
    "healthy": true,
    "total_conns": 10,
    "idle_conns": 5,
    "stale_conns": 0,
    "pool_size": 30,
    "usage_percent": 33.3
  },
  "traffic": {
    "qps": 10.5,
    "qps_peak": 50.0,
    "tps": 500.0,
    "tps_peak": 2000.0,
    "rpm": 600,
    "tpm": 30000,
    "error_rate": 0.02,
    "today_requests": 5000,
    "today_tokens": 250000,
    "rpm_limit": 0
  }
}

模型管理

GET /api/admin/models

获取支持的模型列表。

响应:

{
  "models": [
    "gpt-5.4",
    "gpt-5.4-mini",
    "gpt-5",
    "gpt-5-codex",
    "gpt-5-codex-mini"
  ]
}

OAuth 授权

通过 OAuth PKCE 流程授权获取 Codex 账号的 Refresh Token，适用于无法手动获取 RT 的场景。

流程: 生成授权 URL → 用户在浏览器中完成授权 → 用授权码兑换 Token 并写入系统

POST /api/admin/oauth/generate-auth-url

生成 OAuth 授权 URL（PKCE 模式）。

请求:

{
  "proxy_url": "http://proxy.example.com:8080",
  "redirect_uri": "https://example.com/callback"
}

参数说明:

参数 类型 必填 说明
proxy_url string 否 账号使用的代理 URL
redirect_uri string 否 回调地址，默认为系统内置地址

响应:

{
  "auth_url": "https://auth.openai.com/authorize?response_type=code&client_id=...&state=...",
  "session_id": "a1b2c3d4e5f6..."
}

将 auth_url 在浏览器中打开，完成授权后获取回调 URL 中的 code 和 state 参数。session_id 有效期 30 分钟。

POST /api/admin/oauth/exchange-code

用授权码兑换 Token，自动创建新账号并加入号池。

请求:

{
  "session_id": "a1b2c3d4e5f6...",
  "code": "auth_code_from_callback",
  "state": "state_from_callback",
  "name": "my-oauth-account",
  "proxy_url": "http://proxy.example.com:8080"
}

参数说明:

参数 类型 必填 说明
session_id string 是 generate-auth-url 返回的 session_id
code string 是 授权回调 URL 中的 code 参数
state string 是 授权回调 URL 中的 state 参数
name string 否 账号名称，默认使用邮箱或 oauth-account
proxy_url string 否 代理 URL，覆盖生成 URL 时的设置

响应:

{
  "message": "OAuth 账号 user@example.com 添加成功",
  "id": 42,
  "email": "user@example.com",
  "plan_type": "pro"
}

支持模型

模型 说明
gpt-5.4 旗舰模型
gpt-5.4-mini 轻量版
gpt-5 标准版
gpt-5-codex Codex 专用
gpt-5-codex-mini Codex 轻量
gpt-5.1 旧版本
gpt-5.1-codex 旧版本 Codex
gpt-5.1-codex-mini 旧版本 Codex 轻量
gpt-5.1-codex-max 旧版本 Codex 最大版
gpt-5.2 中间版本
gpt-5.2-codex 中间版本 Codex
gpt-5.3-codex 较新版本

提示：实际支持的模型以 /v1/models 接口返回为准，文档可能未及时更新。

错误码

HTTP 状态码

状态码 说明
200 请求成功
400 请求参数错误
401 认证失败
403 权限不足
404 资源不存在
429 请求过于频繁（限流）
499 客户端断开连接
500 服务器内部错误
502 网关错误（上游服务异常）
503 服务不可用（账号池耗尽）
598 上游流中断

错误响应格式

{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误代码"
  }
}

常见错误代码

代码 说明 处理建议
missing_api_key 缺少 API Key 添加 Authorization 请求头
invalid_api_key API Key 无效 检查密钥是否正确
authentication_error 认证错误 检查 Admin Secret 或 API Key
invalid_request_error 请求参数错误 检查请求体格式
server_error 服务器错误 查看日志排查问题
upstream_error 上游服务错误 检查 Codex 服务状态
account_pool_usage_limit_reached 账号池额度耗尽 等待冷却或添加新账号
rate_limit_exceeded 限流触发 降低请求频率

限流说明

全局 RPM 限流

通过 global_rpm 设置限制全局每分钟请求数。

  • global_rpm = 0: 无限流
  • global_rpm > 0: 启用 RPM 限流

账号级别限流

系统会自动根据账号状态进行限流：

  • Healthy: 正常并发
  • Warm: 并发减半
  • Risky: 固定 1 并发
  • Banned: 0 并发，不参与调度

429 限流响应

当账号触发限流时，响应包含 Retry-After 头：

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

{
  "error": {
    "message": "账号池额度已耗尽，请稍后重试",
    "type": "server_error",
    "code": "account_pool_usage_limit_reached",
    "plan_type": "free",
    "resets_at": 1712345678,
    "resets_in_seconds": 3600
  }
}

建议

  1. 监控 X-RateLimit-* 响应头（如有）
  2. 实现指数退避重试策略
  3. 处理 429/503 状态码，根据 Retry-After 等待后重试
  4. 避免在短时内发送大量请求