网关

先选协议，再发送第一条请求

SDK 通常会在 Base URL 后自动拼接路径；直接发送 HTTP 请求时则使用完整地址。最常见的 404 原因是重复拼接成 /v1/v1 或把完整 endpoint 填进 Base URL。

curl https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "Reply only with: connected"
  }'

• 响应：HTTP 状态为 2xx，Responses 返回 status: "completed"，文本位于消息输出项中。
• 记录：控制台出现对应的时间、API Key、模型、分组、状态和用量记录。
• 下一步：最小非流式请求成功后，再分别验证流式、工具调用、结构化输出和附件能力。

完整请求与响应结构见文本 API 文档。

一条请求实际经过哪些环节

API Key 所属分组决定本次请求可使用的模型范围、计费方式与限额。客户端发送模型 ID 后，网关在该权限范围内完成鉴权、路由、服务资源调度和用量记录。

1. 01
   客户端组装请求

   确定协议、最终路径、模型 ID、请求体以及是否启用流式。

2. 02
   网关校验密钥

   检查密钥状态、所属分组、有效期、IP 规则、额度和适用限额。

3. 03
   解析模型与权限

   确认该分组允许当前模型和接口；未知模型或不匹配的协议会拒绝请求。

4. 04
   调度可用服务资源

   平台根据分组、模型与当前运行状态选择可用资源，并将请求发送给对应模型服务。

5. 05
   传回响应

   非流式请求返回完整响应；流式请求持续传回相应协议的 SSE 事件。

6. 06
   记录用量

   平台保存鉴权、模型、状态、Token、费用和耗时等调用与计费元数据。

更换 Base URL 后，必须重新验证这些能力

能填写 Base URL、API Key 和模型 ID，只说明客户端允许自定义接口，不代表完整兼容。迁移时应逐项验证客户端实际发送的协议和功能。

先判断错误类型，再决定是否重试

状态码只说明失败发生在哪一类环节。先读取完整错误信息和响应头，再按下面的顺序处理；修正配置类错误时，不要用高频重试掩盖问题。

把 API Key 当作权限和成本边界

API Key 不只用于登录。它关联所属分组，并可能同时受状态、总额度、有效期、IP 规则和当前账户的限额配置影响。

• 按环境隔离：生产、测试、本地开发和不同应用使用独立密钥。
• 只在服务端保存：使用环境变量或 Secret 管理服务，不把密钥放进浏览器、移动端包或公开仓库。
• 限制影响范围：按当前控制台提供的选项设置额度、有效期、访问来源或用量窗口。
• 发现泄露立即轮换：先撤销旧密钥，再更新调用端；仅修改客户端显示名称不能阻止滥用。

用一条记录回答“调用去哪了、花了多少”

控制台可按 API Key、模型、分组、请求类型和计费方式筛选调用记录。排错时先定位单条请求，再判断是客户端、权限、路由还是模型服务问题。

联系支持时请提供 UTC 时间、模型、协议、是否流式、脱敏后的实际 URL、HTTP 状态、完整错误信息和请求 ID。不要发送完整 API Key、Prompt 或正常响应正文。详细步骤见排错与安全文档。

区分请求正文、调用记录与上游处理

KHaiXAPI 不将正常 Prompt 或正常模型响应用于训练自有通用模型。原始调用与计费记录原则上不超过 90 日，小时汇总原则上不超过 180 日，日级汇总原则上不超过 730 日；争议、安全调查或法定义务可能延长相关记录的保存期限。

上线前完成这九项检查

1. 为应用和环境分别创建密钥，并确认密钥所属分组。
2. 用当前密钥核对模型 ID，不依赖旧示例或其他分组看到的名称。
3. 先通过最小非流式请求，再逐项加入流式、工具、结构化输出和附件。
4. 在控制台核对模型、Token、状态、计费方式与最终扣费。
5. 分别配置连接超时、读取超时和整体业务超时。
6. 只对适合重试的错误退避重试，并为副作用请求实现幂等。
7. 记录响应实际返回的请求 ID；客户端自建关联 ID 只作为本方日志字段。
8. 按真实并发压测；额度与并发上限不等于容量预留或 SLA。
9. 核对使用政策、支持地区及模型上游的数据规则。

常见问题