接入指引（客户版）

本文可直接发给客户。你们的对接方只需按下面三步操作，通常 5 分钟内可完成首次调用。

一、你会收到什么

开通后我们提供以下三项，请妥善保管：

项目	示例	说明
接口地址	https://cn.guanqiintelligence.com/v1	固定不变，所有请求都发到这里
API Key	sk-xxxxxxxx...	你的调用凭证，等同于账号密码
可用模型	glm-5-3-260814 等	见模型列表

二、三步接入

第 1 步：把接口地址换成我们的

我们完全兼容 OpenAI 协议，所以只需修改 Base URL：

https://cn.guanqiintelligence.com/v1

已有代码无需改动

原本调用 OpenAI 的代码，只改 Base URL 和 API Key 两处即可，业务逻辑一行不用改。 Claude、Gemini 协议同样支持，见调用示例。

第 2 步：把 API Key 换成我们的

在请求头中携带：

Authorization: Bearer sk-你的密钥

⚠️ 切勿把密钥写进前端代码或客户端 App —— 前端代码会被用户看到，密钥必然泄露。 正确做法是通过你自己的后端转发请求。

第 3 步：发一个请求验证

curl https://cn.guanqiintelligence.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "glm-5-3-260814",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024
  }'

返回 200 且带有 usage 字段即表示对接成功。

三、常见接入问题

返回 200 但内容为空？

说明你用的是推理模型（如 GLM-5.3、DeepSeek V4），max_tokens 被思考过程消耗完了。 把 max_tokens 调大（建议 ≥1024） 即可。这是接入时最常见的坑。

返回 401？

密钥无效或格式不对。确认请求头是 Authorization: Bearer sk-xxx，注意 Bearer 后有空格、 密钥前后无多余空格。

返回 404 说模型不存在？

model 字段必须填完整模型 ID（如 doubao-seed-2-1-turbo-260628）， 不能填中文名或简称。见模型列表。

返回 429？

触发限流。请降低并发并做指数退避重试（如 1s、2s、4s…）。如业务确需更高速率，请联系我们评估。

流式输出中断？

检查你的客户端超时设置——长回答需要较长等待。我们已为流式接口关闭网关缓冲。

更多排查见错误码。

四、账号与自助管理

拿到账号后，你可以在控制台（https://cn.guanqiintelligence.com）自助完成：

你可以自助	位置
创建 / 吊销 API 密钥	API 密钥
为单个密钥设置额度上限、有效期、可用模型、IP 白名单	API 密钥
查看实时余额与用量	钱包
查看每一笔调用明细（时间/模型/token/金额）并可导出	使用日志
查看用量趋势统计	数据看板
修改密码、绑定邮箱、开启两步验证	安全与访问

你不需要为这些事找我们 —— 这也是我们把控制台开放给你的原因。

五、我们能帮你做什么

事项	联系方式
提额、加模型、调整档位	联系对接商务
调用异常、性能问题	联系我们（请附上 request_id，见下）
发票、对账	联系对接商务

报障时请提供 request_id

每次响应都带 X-Oneapi-Request-Id，错误信息里也会含 request id: xxx。 提供它我们能直接定位该次调用的完整链路，大幅加快排查速度。

六、计费与对账

按实际用量计费，具体单价以双方合同为准。 每次调用的 usage 字段都会返回本次 token 用量；控制台可导出逐笔明细用于对账。 详见计费说明。

---

还有问题？ 随时联系你的对接商务，或查阅左侧完整文档。