客户接入文档 | Gatecraft AI

SETUP

接入流程

以下流程适用于试点客户。生产环境请使用服务端环境变量保存 API key，不要把 key 放到前端页面、移动端包或公开仓库。

获取 API key

试点开通后，客户会获得一个以 ag_ 开头的 API key。请只放在服务端环境变量中。

配置 Base URL

把 SDK 或 HTTP 客户端的 base_url 设置为 https://api.gatecraftai.com/v1。

查询模型权限

调用 GET /v1/models，确认当前 key 已开放哪些模型。

发起测试请求

用 chat completions 完成一次非流式请求，再测试 stream。

保存 request id

生产环境建议记录响应头 x-request-id，用于排查和账单核对。

QUICKSTART

3 分钟完成第一次调用

示例使用 chat completions 接口。实际模型名称以 /v1/models 返回结果和客户授权为准。

00:00

设置环境变量

GATECRAFT_BASE_URL=https://api.gatecraftai.com/v1，GATECRAFT_API_KEY=ag_...

01:00

查询模型权限

调用 /v1/models，确认 key 已开放的模型。

02:00

发送第一条消息

用 curl、TypeScript 或 Python 调用 /v1/chat/completions。

First request

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。" }
    ]
  }'

MODELS

支持模型类别

模型权限按客户开通。高成本模型建议用于明确业务场景，并设置单独预算。

List modelsapi

curl https://api.gatecraftai.com/v1/models \
  -H "Authorization: Bearer $GATECRAFT_API_KEY"

OpenAI 系列

8 models

模型 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 系列

6 models

模型 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 系列

2 models

模型 ID	开通方式
gemini-3.1-pro	按客户授权
gemini-3-flash	按客户授权

CHAT COMPLETIONS

接口参数

Gatecraft 使用标准 JSON 请求体。不同模型的能力、上下文长度和参数支持可能不同，建议先用已授权模型做小样本测试。

Endpoint	POST /v1/chat/completions
Auth	Authorization: Bearer <API_KEY>
Required	model, messages
Streaming	设置 "stream": true
JSON output	可按模型能力使用 response_format
Request ID	响应头 x-request-id

JSON outputapi

curl https://api.gatecraftai.com/v1/chat/completions \
  -H "Authorization: Bearer $GATECRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "response_format": { "type": "json_object" },
    "messages": [
      { "role": "user", "content": "输出 JSON：包含 title、summary、priority。" }
    ]
  }'

STREAM

流式输出

设置 stream: true 后，接口会以 SSE 形式返回增量内容。适合聊天、客服、代码生成和长文本生成场景。

Stream curlapi

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。排查时请提供 x-request-id。

HTTP	type	说明
400	invalid_request_error	请求体格式错误，或缺少 model / messages 等必要字段。
401	authentication_error	API key 缺失、错误、已过期或已被停用。
403	permission_error	客户状态不可用，或请求模型未开放。
429	rate_limit_error	超过 RPM、并发上限、预算限制或模型临时限流。
500	api_error	服务端异常。请携带 request id 联系支持。
503	service_unavailable	模型或上游服务暂不可用，可稍后重试或联系支持。

Error responseapi

{
  "error": {
    "message": "Model is not enabled for this customer.",
    "type": "permission_error",
    "code": "model_not_allowed"
  }
}

REQUEST ID

用 request id 排查问题

每次响应都会尽量返回 x-request-id。客户侧应把它写入业务日志，便于定位模型、延迟、错误和账单记录。

建议记录字段

x-request-idcustomer request idmodelHTTP statuslatencycreated_at

联系支持时提供

请提供 request id、发生时间、模型、是否 stream、错误信息和简要业务场景。不要通过聊天工具发送完整 API key。

LIMITS

限流、预算和计费

每个客户都可以配置 RPM、并发上限、模型权限和月度预算。达到限制后，新请求会被拒绝。

RPM

每分钟最多请求数。适合控制突发流量，避免脚本循环造成异常账单。

并发

同一时间最多运行请求数。流式请求在结束前会持续占用并发。

月度预算

达到预算后暂停新请求。预算恢复或调整后可继续调用。

模型权限

高成本模型需要单独开通，客户只能调用已授权模型。

模型消耗、服务费和套餐额度以双方确认的试点报价为准。正式报价单会单独列明是否包含模型消耗、额度上限和超额计费方式。

SERVICE BOUNDARIES

服务边界

以下边界用于保护客户预算、服务稳定性和合规使用。试点开通即默认接受这些边界。

不提供无限量承诺

每个客户都会设置调用频率、并发和预算边界。超出限制的请求会被拒绝，避免不可控成本。

高成本模型按需开通

GPT-5.5、Claude Opus 4.7、Gemini 3.1 Pro 等高成本模型适合明确场景使用，默认按客户需求和预算单独开放。

不支持违规业务

不得用于违法违规、欺诈、滥发、绕过风控、侵权或其他违反适用规则的场景。异常使用可能导致暂停服务。

账单以日志和 usage 为准

试点阶段按请求日志、模型、tokens、预算和商务约定对账。客户可通过 request id 辅助核对。

故障排查需要 request id

遇到错误、延迟异常或响应不符合预期时，请提供 x-request-id、时间、模型和简要请求描述。