ACCESS
接入信息
接入前请确认：密钥在服务端、模型已授权、业务日志已记录请求 ID。
| Base URL | https://api.gatecraftai.com/v1 |
|---|---|
| 认证方式 | Authorization: Bearer <GATECRAFT_API_KEY> |
| 模型列表 | GET /v1/models |
| 对话接口 | POST /v1/chat/completions |
| 请求体格式 | application/json |
| 排障追踪 | 响应头 x-request-id |
PRICING & USAGE
计费与用量
按 token 计费，按量扣费。账单透明，调用记录可追踪。
计费单位
按输入 token 和输出 token 分别计费，合并后扣减账户余额。
扣费时点
请求完成后按实际 token 用量计算费用并扣减余额。
对账口径
以请求日志、模型、token 用量、请求 ID 作为对账依据。
计费公式（人民币）api
按量计费（生产口径）
费用 = ((输入 token / 1,000,000 × 输入单价USD)
+ (输出 token / 1,000,000 × 输出单价USD))
× 0.3 × 7
说明：
- 0.3：Gatecraft 结算系数（官方参考价的 30%）
- 7：汇率换算基准（$1 = ¥7）
- 实际可用模型与单价以你的账号权限和控制台展示为准| 字段 | 说明 |
|---|---|
| 时间 | 请求创建时间（本地时区显示） |
| 模型 | 本次调用使用的模型 ID |
| 输入 token | 请求输入 token 数 |
| 输出 token | 响应输出 token 数 |
| 费用 | 按模型费率和 token 用量计算后的实际扣费 |
| 耗时 | 请求端到端耗时（毫秒） |
| 请求 ID | 用于排障与对账的唯一追踪标识 |
QUICKSTART
请求示例
示例使用 Chat Completions。实际模型 ID 以 /v1/models 返回结果为准。
请求示例
POST /v1/chat/completions
curl https://api.gatecraftai.com/v1/chat/completions \
-H "Authorization: Bearer $GATECRAFT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-nano",
"messages": [
{ "role": "user", "content": "用一句话解释 Gatecraft AI。" }
]
}'MODEL PERMISSION
模型权限
模型按账号权限开放。未开通模型会返回权限错误。
查询可用模型api
curl https://api.gatecraftai.com/v1/models \
-H "Authorization: Bearer $GATECRAFT_API_KEY"OpenAI 系列
| 模型 ID | 权限 |
|---|---|
| gpt-5.5 | 按账号授权 |
| gpt-5.4 | 按账号授权 |
| gpt-5.4-pro | 按账号授权 |
| gpt-5.2 | 按账号授权 |
| gpt-5.4-mini | 按账号授权 |
| gpt-5-mini | 按账号授权 |
| gpt-5.4-nano | 按账号授权 |
| gpt-5-nano | 按账号授权 |
Anthropic / Claude 系列
| 模型 ID | 权限 |
|---|---|
| claude-opus-4.7 | 按账号授权 |
| claude-opus-4.6 | 按账号授权 |
| claude-opus-4.5 | 按账号授权 |
| claude-sonnet-4.6 | 按账号授权 |
| claude-sonnet-4.5 | 按账号授权 |
| claude-haiku-4.5 | 按账号授权 |
Gemini 系列
| 模型 ID | 权限 |
|---|---|
| gemini-3.1-pro | 按账号授权 |
| gemini-3-flash | 按账号授权 |
STREAM
流式输出
设置 stream: true 后，接口通过 SSE 返回增量内容。
流式请求示例api
curl https://api.gatecraftai.com/v1/chat/completions \
-H "Authorization: Bearer $GATECRAFT_API_KEY" \
-H "Content-Type: application/json" \
-N \
-d '{
"model": "claude-opus-4.7",
"stream": true,
"messages": [
{ "role": "user", "content": "把这段客户反馈改写成专业客服回复。" }
]
}'连接保持
客户端持续读取 SSE；不要在首个 chunk 后提前关闭连接。
重试策略
流式已开始返回内容后，不建议对同一请求自动重试。
并发占用
流式请求结束前持续占用并发额度，请按峰值评估。
ERRORS
错误码
错误体包含 error.message、error.type、error.code。
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求体格式错误，或缺少 model / messages 等必要字段。 |
| 401 | authentication_error | API 密钥缺失、错误、已过期或已停用。 |
| 403 | permission_error | 客户状态不可用，或请求模型未开放。 |
| 429 | rate_limit_error | 超过 RPM、并发上限、月度预算，或账户余额不足。 |
| 500 | api_error | 服务端异常，请携带请求 ID 反馈。 |
| 503 | service_unavailable | 模型或上游暂不可用，请稍后重试。 |
错误响应示例api
{
"error": {
"message": "Model is not enabled for this customer.",
"type": "permission_error",
"code": "model_not_allowed"
}
}LIMITS
配额与限制
生产环境建议为每个项目配置独立配额，避免互相影响。
RPM（每分钟请求数）
限制瞬时请求速率，防止脚本异常冲量。
并发上限
限制同时运行请求数，流式请求在结束前持续占用并发。
月度预算
达到预算后暂停新请求，调整预算后恢复。
模型权限
仅可调用已开通模型，高成本模型建议单独授权。
PRODUCTION OPS
生产排障清单
接入上线前请完成以下最小项。
服务端保管密钥
密钥只放后端环境变量，不写入前端页面、客户端包或公开仓库。
记录请求 ID
每次请求记录 x-request-id、模型、状态码、耗时。
设置业务超时
客户端应设置可控超时与重试策略，避免无限等待。
区分环境密钥
测试、预发、生产使用不同密钥，避免串账与误扣费。