API

本页概览 Codexpertise API 的公开集成约定。生产模型目录和 provider-specific 能力完成验证前，本文不会列出未经确认的模型列表。

Endpoint contract

TODO: verify against sub2api。以下请求和错误示例使用 OpenAI-compatible 形态， 方便用户准备集成；最终 endpoint 列表和响应字段必须以已部署的 sub2api 配置验证 结果为准。

Base URL

API 客户端统一使用：

https://api.codexpertise.com

用户应用不要连接内部基础设施地址。公开客户端应使用上面的 API 域名。

Authentication

API key 使用 bearer token 传递：

Header

Authorization: Bearer YOUR_API_KEY

请在 dash.codexpertise.com 创建和管理 key。 Key 应保存在环境变量或 secret manager 中，不要写进源码。

Request Format

JSON 请求应包含 Content-Type: application/json。Quickstart 使用下面的首次调用 形态：

请求示例

curl -sS "https://api.codexpertise.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one short sentence."
      }
    ]
  }'

TODO: verify against sub2api。新增 endpoints、必填字段或模型名称在写成稳定文档前 都需要先完成验证。

Streaming

Streaming 请求会在生成 token 时保持 HTTP 连接打开。只有当客户端能处理部分输出、 重试和网络中断时，才建议开启 streaming。

典型客户端行为：

• 设置足够覆盖预期响应时长的 request timeout。
• 边接收边展示部分输出。
• 将断开的 stream 视为未完成响应；只有操作可安全重复时才重试。

TODO: verify against sub2api。精确的 streaming 参数和 event 格式需要验证后再发布。

Rate Limits

Codexpertise 可能按账号、key、套餐和风控策略应用限制。各套餐规则确认后，本文才 会发布具体数值。

触发限制时，API 可能返回 429 Rate Limited。请降低并发，等待后重试，并在 dashboard 中检查当前用量。

Error Format

客户端应先按 HTTP status code 处理错误。响应体可能包含机器可读字段，但在验证前 不要依赖未确认字段。

错误形态示例

{
  "error": {
    "message": "Request failed.",
    "type": "api_error",
    "code": "upstream_error"
  }
}

TODO: verify against sub2api。最终 error schema、request ID 字段和 retry header 需要验证后再写入稳定文档。

常见状态码：

• 401 Unauthorized：API key 缺失、格式错误、过期或已撤销。
• 403 Forbidden：Key 有效，但账号、套餐、来源或 route 没有权限。
• 429 Rate Limited：超过额度或速率限制。
• 5xx Upstream Error：Relay 或上游 provider 返回服务端失败。

API Key Rotation

Key 泄露、成员离开团队，或按安全周期轮换时，请按以下顺序操作：

1. 在 dashboard 创建新 key。
2. 更新本地环境变量、CI secrets 和生产 secret store。
3. 部署或重启启动时读取 key 的客户端。
4. 使用新 key 发送一个小请求验证。
5. 流量迁移后撤销旧 key。

不要把原始 API key 或完整 Authorization header 粘贴到日志、工单或截图中。