常见问题

从哪里开始排查

按下面的顺序检查，通常可以快速定位问题：

1. 能否登录控制台，账号是否仍在等待审批或验证。

2. API Key 是否从控制台完整复制，是否刚刚重新生成过。

3. Base URL 是否正确，是否重复添加了 /v1。

4. 携带自己的 API Key 查询模型列表，确认请求的模型对账号可用。

5. 先运行快速开始的最小示例，再排查开发工具的额外配置。

401：认证失败

确认使用的是 API Key，而非网页登录密码。密钥重新生成后旧值立即失效，需要更新每个使用它的工具。

检查环境变量是否存在时，只检查是否为空，不要输出密钥本身：

test -n "$TENCENT_INFERENCE_API_KEY" && echo "API Key 已设置" || echo "API Key 未设置"

GET /v1/models 不强制认证，拿到 200 不能单独证明密钥有效。

403：账号尚未完成验证

返回控制台，按页面提示完成账号验证。如果仍在等待审批，需等待账号获批后再调用。

404：路径或模型不正确

现象	检查
请求路径出现 /v1/v1	工具自动追加了 /v1，移除 Base URL 中重复的部分
返回 Model '…' not found	使用携带自己 API Key 查询到的模型 ID，区分大小写
Claude Code 请求 claude-…	按 Claude Code 配置平台模型和别名

模型列表为空

未登录的公开目录可能为空。请登录控制台，或携带自己的 API Key 请求：

curl --fail-with-body 'https://freeinference.qq.com/v1/models' \
  -H "Authorization: Bearer $TENCENT_INFERENCE_API_KEY"

如果账号列表仍为空，表示当前没有可见模型，或密钥无效而退回了未登录目录。先在控制台核对密钥和账号状态，再联系平台运营方确认模型权限。文档中的示例 ID 不会自动为账号开通模型。

429：请求过多或额度不足

• Too many concurrent requests：减少同时运行的会话，等待已有请求结束后再试。

• Daily cost quota exceeded：在控制台查看额度和重置时间。

• Too many authentication failures：先更新仍在使用旧密钥的工具，停止反复重试，等待限流解除。

自动重试应遵守 Retry-After，逐步延长间隔；不要对 401、403、模型不存在等配置错误无限重试。

回复很慢或中途断开

先使用短提示验证服务，再尝试流式输出。降低请求的最大输出长度，并检查客户端超时和网络状态。流式响应中途可能出现错误事件，收到部分文字不等于整个请求已经成功结束。

如何反馈问题

请提供：发生时间和时区、工具及版本、接口路径、模型 ID、HTTP 状态码、错误信息、响应头中的 X-Request-ID。如果能复现，附上去掉密钥和个人数据的最小示例。

不要发送密码、短信验证码、完整 API Key 或包含个人数据的原始对话。联系平台运营方。