常见问题

Base URL 到底带不带 /v1？

这是最高频的问题。判断依据是看工具文档里写的是「base URL」还是「完整端点」：

同一个值填错位置，表现就是 404。各客户端的具体填法见接入概览。

模型名填什么？ 填 GET /v1/models 返回的 id。不同分组看到的清单不同，详见模型列表接口。

Key 是哪种格式？ sk- 开头的一串字符，放在 Authorization: Bearer 头里。

可以把 Key 放在 URL 里吗？ 不可以，网关会拒绝查询参数形式的密钥，请改用请求头。

两个域名怎么分工？

注意两个站点的 Key 与额度是分开的，ark 站需要单独获取 Key。

Does the base URL include /v1 or not?

This is the most frequent question. The answer depends on whether the tool's docs say "base URL" or "full endpoint":

Put the same value in the wrong field and you get a 404. For per-client specifics see the integrations overview.

What do I put for the model name? Use the id returned by GET /v1/models. Different groups see different lists; see the models list endpoint.

What format is a key? A string starting with sk-, sent in the Authorization: Bearer header.

Can I put the key in the URL? No. The gateway rejects keys passed as query parameters; use the request header instead.

How do the two domains divide the work?

Note that the two sites have separate keys and balances; the ark site requires its own key.

遇到问题按这三步走，大部分情况能自己定位。

第一步：先确认 Key 有效。

curl https://api.oairoute.com/v1/models \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY"

返回模型列表说明认证没问题，问题在后续参数；返回 401 就是 Key 本身的问题。

第二步：确认模型存在。

上一步返回的列表里找一下你要用的模型 ID，没有就是该账号未开通。

第三步：用最小请求试。

curl https://api.oairoute.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"hi"}]}'

最小请求能通，说明接入没问题，问题在你自己的请求体。

Work through these three steps; most issues can be traced this way.

Step 1: Confirm the key is valid.

curl https://api.oairoute.com/v1/models \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY"

A model list means authentication is fine and the problem is in your parameters; a 401 means the key itself is the problem.

Step 2: Confirm the model exists.

Look for the model ID you want in the list returned above. If it's missing, your account doesn't have it enabled.

Step 3: Try a minimal request.

curl https://api.oairoute.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"hi"}]}'

If the minimal request works, integration is fine and the problem is in your own request body.

401 Key 复制不完整、已删除或已停用。到控制台「令牌」页核对。

402 余额不足。到控制台钱包页面充值。

403 无访问权限，或 Key 所在分组不允许调用该模型。换用分组内的可用模型。

404 路径或资源不存在。先确认地址有没有多写或少写 /v1，再确认模型名是否正确。

429 触发限流。按响应头 Retry-After 的指示等待，或降低并发。

500 / 502 / 503 服务端或上游异常，网关已做过重试。稍等几秒再试一次。

完整的错误码、错误结构与含义见错误码与限流。

401 The key was copied incompletely, deleted, or disabled. Check the "Tokens" page in the console.

402 Insufficient balance. Top up on the console wallet page.

403 No access, or the key's group doesn't allow that model. Switch to a model available in your group.

404 Path or resource not found. First check whether /v1 is extra or missing, then whether the model name is correct.

429 Rate limit hit. Wait as the Retry-After response header instructs, or lower concurrency.

500 / 502 / 503 Server-side or upstream error; the gateway has already retried. Wait a few seconds and try once more.

For the full set of error codes, structures, and meanings see Error codes and rate limits.

返回内容为空？

• 流式场景：检查是否解析了 choices[0].delta.content。首条消息里的 delta 只含 role，content 是 null，直接取会得到空值
• 非流式场景：看 finish_reason。如果是 length，说明被 max_tokens 截断了，把上限调大
• 内容审核拦截：部分模型会返回空的 content，同时 finish_reason 为 content_filter

流式输出中途断了？ 先检查客户端是否处理了流内的 error 事件。网络中间设备可能提前关闭长连接，建议在客户端配置更长的读超时。

请求特别慢？ 按影响程度排序：

1. 上下文太长。每轮都重发全部历史，输入越长首 token 越慢
2. 模型太大。旗舰模型的推理本身就慢
3. 网络链路。跨境访问有额外延迟，可换直连线路试试

中文乱码？ Windows 终端默认不是 UTF-8，先执行 chcp 65001 再跑命令。写入文件时也要显式指定编码，Python 用 encoding="utf-8"。

并发上不去？ 429 是限流信号，不是服务坏了：

• 用信号量把并发压在 5 到 10
• 遇到 429 按指数退避重试
• 需要更高并发时，拆成多个 Key 分担

为什么实际扣费和官方价格不一样？ 实际扣费 = 用量 × 单价 × 分组倍率。你的分组系数在控制台能看到，算账方法见计费说明。

同一把 Key 能同时调 Claude 和 GPT 吗？ 取决于 Key 所在分组。分组决定了你这把 Key 能调哪些模型，清单见 GET /v1/models。

用量记录多久出现？ 调用结束后写入，流式请求在流结束时写入。可在控制台用量页面查看。

Why is the response empty?

• Streaming: check that you're parsing choices[0].delta.content. The first message's delta contains only role, and content is null, so reading it directly gives you nothing
• Non-streaming: check finish_reason. If it's length, the output was cut off by max_tokens; raise the limit
• Content moderation: some models return an empty content with finish_reason set to content_filter

Why did the stream stop partway? First check whether your client handles in-stream error events. Network middleboxes may close long-lived connections early; configure a longer read timeout on the client.

Why is the request so slow? In order of impact:

1. Context is too long. Resending the full history every turn makes longer input mean a slower first token
2. The model is too large. Flagship models are inherently slower at inference
3. The network path. Cross-border access adds latency; try a direct route

Why is Chinese text garbled? Windows terminals don't default to UTF-8; run chcp 65001 before the command. Specify the encoding explicitly when writing files too — in Python, encoding="utf-8".

Why can't I raise concurrency? 429 is a rate-limit signal, not the service being down:

• Use a semaphore to keep concurrency between 5 and 10
• Retry 429s with exponential backoff
• If you need more concurrency, split across multiple keys

Why does my bill differ from the official price? Actual charge = usage × unit price × group ratio. You can see your group's multiplier in the console; see Billing for the math.

Can one key call both Claude and GPT? That depends on the key's group. The group determines which models your key can call; see GET /v1/models for the list.

How soon does usage show up? It's written after the call completes; for streaming requests, when the stream ends. View it on the console usage page.

忘记密码？ 登录页点「忘记密码」，通过邮箱重置。

额度用完了会怎样？ 产生费用的接口会被拒绝，查询类接口仍可调用，充值后立即恢复。

没找到答案？ 写邮件到 [email protected]，附上请求时间、接口路径、HTTP 状态码与完整错误体，以及你的 Key 名称（不要贴完整 Key）。

Forgot your password? Click "Forgot password" on the sign-in page and reset it by email.

What happens when the balance runs out? Endpoints that incur charges are rejected, while query endpoints still work. Everything resumes as soon as you top up.

Didn't find an answer? Email [email protected] with the request time, endpoint path, HTTP status code, full error body, and your key name (never paste the full key).