文档 · 排查问题

curl 能跑通，工具里却报错

2026-09-18

工具和能跑通的 curl 通常差在七处，逐一对照就能找到。

仪表板（Dashboard）页 开始使用（Get started）面板里那条 第一个 API 请求（First API request）curl 能跑通，是因为路径、请求头和模型 id 一字不差。换到工具里同一把 key 就报错，差别通常出在下面七处。

一、base URL

API 密钥（API keys）页的 API 接入点（API endpoint）面板给的是 https://ai.topxea.com，路径留给客户端自己拼。OpenAI 风格的工具会在后面拼 /chat/completions，所以 base URL 必须以 /v1 结尾：

https://ai.topxea.com/v1

少了 /v1，工具实际请求的是 https://ai.topxea.com/chat/completions，那是控制台的网页：返回 200 和一段 HTML，工具报的错就是 JSON 解析失败。/v1 写了两遍，会收到 404 和 Invalid URL (POST /v1/v1/chat/completions)。Anthropic 风格的工具和 TypeSafe 的 SDK 会自己拼 /v1/messages 和 /v1/systemone，这两类的 base URL 填 https://ai.topxea.com，不带 /v1。

二、鉴权头

OpenAI 风格的端点读 Authorization: Bearer sk-...。x-api-key 头只在 /v1/messages 和 /v1/models 上认，Anthropic 工具如果指向 /v1/chat/completions，拿到的就是 401 Invalid token。

三、模型 id

id 区分大小写：GLM-5.3-Abliterated、claude-sonnet-5-5。工具把名字转成小写，就会收到 403 Model is not offered by this service。想知道这把 key 能调哪些模型，拿这把 key 查一遍：

curl https://ai.topxea.com/v1/models -H "Authorization: Bearer sk-..."

四、key 绑定的线路和模型限制

建 key 时选定一个分组（Group）。绑在 claude-shared 上的 key 调不了 gpt-6-astra，返回 403 Model is not available on this API key route。要在几家厂商的模型之间切换的工具，建一把 自动路由（Auto route）的 key，按模型所属的分组自动落到价格最低的线路。模型不在 key 的 模型限制（Model limits）里，返回 403 This token has no access to model ...。

五、key 的 IP 白名单

key 设了 IP 白名单（支持 CIDR）（英文界面 IP Whitelist (supports CIDR)）的话，笔记本上的 curl 能通，换到不在名单里的服务器上就是 403。

六、只有 chat 接口的模型，以及 Jev

GLM-5.3-Abliterated 和 kimi-k3 只在 /v1/chat/completions 上提供；GPT 和 Grok 模型另外支持 /v1/responses，Claude 模型另外支持 /v1/messages。GLM 只收文字：编辑器添加模型时拿图片试探，网关会把图换成 [Attachment omitted: this model accepts text only.]，测试能通过，但模型永远看不到图片。jev-1.13.0 是 TypeSafe 的 System One 模型，走 POST /v1/systemone，返回的是带类型的判断（noul / choice / score），不是对话，所以要配在 TypeSafe 的 SDK 里，设 TYPESAFE_BASE_URL=https://ai.topxea.com，而不是加进 chat 客户端。

七、超时、流式和视频

网关等上游最多 30 分钟：首字节等 30 分钟，流里两段数据之间也等 30 分钟。比这短的超时是工具自己设的。生成时间长的请求打开 stream: true；流中途出错，会收到一条 data: {"error":...} 事件（/v1/messages 上前面多一行 event: error），然后流直接结束，没有 [DONE]。视频是异步的：POST /v1/videos/generations 立刻返回一份带 request_id 的任务单。之后轮询 GET /v1/videos/{request_id}，文件从 GET /v1/videos/{request_id}/content 取。工具要是指望 POST 直接返回视频文件，拿到的只是那份任务单，文件要另外去取。