常见问题和排错 #

排查问题时先用同一组 API Key、Base URL 和 Model ID 跑通 curl。curl 成功后，再检查 SDK、客户端或编程工具配置。

快速自检 #

最小验证命令 #

export COREROUTER_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl https://api.corerouter.tech/v1/models \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

如果模型列表能返回，再测试聊天：

curl https://api.corerouter.tech/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

HTTP 状态码 #

错误响应格式 #

OpenAI 兼容接口的错误通常类似：

{
  "error": {
    "message": "model is required (request id: 202609221234567890)",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

排查时重点看三项：

• message：最直接的失败原因，可能包含 Request ID。
• code：错误类别，便于判断是参数、认证、限流还是上游问题。
• HTTP 状态码：决定是改请求、换 Key、降低并发，还是稍后重试。

响应 Header 里也可能带有 X-Oneapi-Request-Id。联系支持时请优先提供这个 Request ID。

Base URL 怎么填 #

如果不确定客户端会不会自动拼接路径，先查看它最终请求的 URL。出现 /v1/v1、/v1/chat/completions/chat/completions 这类路径，通常就是 Base URL 填法不匹配。

客户端能聊天，Agent 不能工作 #

普通聊天成功只说明模型能生成文本。Agent 还需要更稳定的能力：

• Tool Calling / Tool Use
• Streaming
• 长上下文
• 多轮任务稳定性
• Responses API 或对应工具要求的协议

建议换用控制台标记支持 Coding Agent 的模型，并用工具调用示例单独测试。

客户端或插件是否支持 #

按下面规则判断：

• 能填写自定义 Base URL、API Key、Model ID：通常可以尝试接入。
• 只能登录官方账号、不能改接口地址：不支持。
• 只能使用固定官方模型列表：不建议承诺支持。
• 只支持聊天：不要承诺 Tool Calling、Agent、图片、音频或 Embeddings。
• Cursor 这类工具：不要默认写成正式支持。它的部分功能可能不走自定义 Base URL，除非你针对具体版本完整测试。
• Claude Code：属于条件支持，需要 Anthropic-compatible Messages 可用；如果某版本强依赖额外辅助端点，可能需要换版本或换工具。

Responses 或 Codex 不可用 #

/v1/chat/completions 成功不代表 /v1/responses 成功。Codex 依赖 Responses API，排查时请确认：

• base_url 是 https://api.corerouter.tech/v1，不是完整的 /v1/responses。
• model 是控制台中支持 Responses / Coding Agent 的 Model ID。
• 用同一个 API Key 和 Model ID 调用 /v1/responses 能返回成功 JSON。
• 如果返回 404 或协议不支持，通常是当前模型没有绑定 Responses 能力。

流式输出没有内容 #

检查顺序：

1. 请求体是否设置了 stream: true。
2. 客户端是否支持 Server-Sent Events。
3. 代理、网关、浏览器插件或企业网络是否缓冲了流式响应。
4. 当前模型或渠道是否支持 Streaming。
5. 先用 curl 观察是否有 data: 事件返回。

模型列表为空 #

可能原因：

• API Key 无效或权限不足。
• Key 限制了可用模型。
• 账户没有可用分组或额度。
• 用户分组没有绑定可用渠道。
• 计费配置、模型倍率或模型状态导致当前 Key 不可见。
• 客户端请求模型列表的路径不兼容。

先用 /v1/models 验证，再回到客户端里修正 Base URL 和 Key。

/v1/models 返回的是当前 API Key 可见的模型，不一定等于平台全部模型。模型列表可能受用户分组、Key 模型限制、渠道状态、模型计费配置和管理员设置影响。

Realtime 连接失败 #

Realtime 是 WebSocket，不是 HTTP POST。排查顺序：

1. URL 是否是 wss://api.corerouter.tech/v1/realtime?model=realtime-model-id。
2. model 是否是控制台中支持 Realtime 的模型。
3. 服务端程序是否传了 Authorization: Bearer sk-...。
4. 浏览器或 SDK 是否通过 Sec-WebSocket-Protocol 传了 realtime, openai-insecure-api-key.sk-...。
5. 代理、负载均衡或公司网络是否允许 WebSocket。

Rerank 或 Moderations 不可用 #

• Rerank 必须传 query 和非空 documents。
• Rerank 需要支持 Rerank 的模型，聊天模型通常不能直接复用。
• Moderations 必须传 input。
• 如果不传审核模型，系统可能使用默认审核模型；生产环境建议显式填写控制台中可用的审核模型 ID。

视频任务不返回结果 #

视频和异步任务不是一次请求立即返回视频文件。排查顺序：

1. 提交接口是否返回了 id 或 task_id。
2. 是否用同一个 API Key 查询任务。
3. 查询状态是否仍是 queued 或 in_progress。
4. 如果状态是 failed，查看 error 或 fail_reason。
5. 如果 /content 下载失败，检查查询结果里是否提供了结果 URL。

联系支持前准备 #

请准备以下信息，便于快速定位：

• 请求时间和时区。
• 使用的 Endpoint 和 Model ID。
• HTTP 状态码和错误信息。
• X-Oneapi-Request-Id 或错误消息里的 Request ID。
• 是否使用流式输出。
• 客户端、插件或 SDK 名称及版本。
• 是否可以用 curl 复现。
• 隐去中间部分的 API Key，例如 sk-abc...xyz。

不要发送完整 API Key、账户密码、验证码、私钥或完整 Cookie。