跳到主要内容

常见问题

最小自检​

先分别检查模型目录与最小对话，再结合完整错误响应定位。

一、Key 和网络是否正常

curl https://api.smartwan.com/v1/models \
  -H "Authorization: Bearer sk-你的Token"

返回模型列表说明本次目录请求通过，不代表所有模型都有权限或可完成推理。

二、对话是否正常

curl https://api.smartwan.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Token" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 1024
  }'

第一条成功、第二条失败时，还需检查模型权限、余额、渠道、接口与参数；不能只判断为请求体或模型名错误。

错误码​

错误常见原因怎么办
401鉴权未通过核对 Key、状态和请求头；Messages 接受 x-api-key 或 Bearer，详见认证
400参数、角色、工具或协议不匹配等保留 error.code/type/message，退回该协议的最小请求，再逐项恢复参数
403权限或账户限制等结合响应检查模型授权和账户状态，不直接推断模型下线
404路径或资源不匹配等OpenAI / Messages 使用 /v1，Gemini 原生使用 /v1beta；检查 SDK 是否重复拼接版本路径
429请求频率或额度限制等按响应提示降低并发、等待重试或检查限额
500网关转换或上游错误等保存错误与请求 ID；Responses 的支持情况需按模型验证
503 / 504渠道不可用或超时等记录模型和时间，检查渠道状态；必要时重试或使用已验证的备用模型

Base URL 到底怎么填​

最高频的问题。按场景对号入座：

场景填什么
OpenAI SDK 的 base_url / baseURLhttps://api.smartwan.com/v1
Anthropic Python SDKhttps://api.smartwan.com，SDK 自动追加 /v1/messages
Google GenAI Python SDKhttps://api.smartwan.com，设置 api_version="v1beta"
curl 调 OpenAI 兼容接口https://api.smartwan.com/v1/chat/completions
curl 调 Anthropic 接口https://api.smartwan.com/v1/messages
curl 调 Gemini 接口https://api.smartwan.com/v1beta/models/{model}:generateContent
客户端工具https://api.smartwan.com 或带 /v1，以工具页说明为准

看到 /v1/v1/chat/completions 这种路径，就是 /v1 填重复了。

各接口的实测状态​

2026-09-22 的测试覆盖了当前目录的 36 个文本模型的 Chat Completions、代表模型的 Messages / Responses / Gemini 原生调用，以及三款图像模型的生成与解码。客户端版本、型号和差异见认证与 Base URL及厂商调用差异。

已验证可用的参数​

验证针对具体请求组合，不能将单次成功扩展为所有参数均已通过。已验证的差异包括 Messages 双鉴权、Claude 工具多轮上下文与 thinking 回传、Kimi K3 两个温度值，以及 DeepSeek Flash / Pro 的思考输出。

本轮没有覆盖全协议流式输出、全部图像生成参数、图片编辑、mask 或流式编辑；这些能力不能依据本轮结果标为已验证。

已知的模型参数限制​

kimi-k3 在 temperature: 1 与 0.3 下均成功，不能统一限制为 1。HTTP 200 也不一定包含完整回答：最终文本为空时检查 finish_reason、推理消耗和输出预算。详见厂商调用差异。

具体问题​

模型列表拉不到 / 是空的

Key 无权限、账户无额度，或工具刷新异常。先用上面的最小自检命令确认 /v1/models 能不能返回。

工具里配置能保存，但一对话就报错

先核对 Base URL、模型名和 API 类型，再结合错误响应检查权限、额度和渠道。模型名务必从模型列表复制，不要手打。

模型名报不存在

大小写敏感。MiniMax-M2.7 不能写成 minimax-m2.7。另外模型会更新换代，文档里的示例名可能已下线，以模型列表实时返回为准。

参数报错，不知道是哪个参数

先退回对应协议的最小请求体；例如 Messages 还需要 max_tokens。参考第一次调用，成功后逐个加回参数。

图片生成失败

确认模型是 gpt-image-2，先只用 prompt、n、size 这几个基础参数测试。

图片接口的 response_format=url 没返回外部链接

按实际字段解析：本次 GPT / Grok 图片生成返回 data[].b64_json，Gemini 返回 inlineData，均可解码。不要只查找外部 URL；具体格式和尺寸检查见第一次调用。

图片编辑报错

先确认模型支持编辑、文件有效且符合接口要求，并保留错误响应。图片编辑、mask 与流式编辑没有在本轮验证，不能直接归因为某个参数。

Codex CLI 的 Responses 请求失败

先使用已验证的 GPT 模型和配置复现。其他模型可能返回不同的协议或参数错误，不能仅由 Chat Completions 成功判断支持 Responses。详见 Codex CLI 页。

Claude 在 Agent 工具里报 400

检查实际错误、工具 schema、请求体大小与上下文。本次 32 个工具定义的请求也成功，不能只按工具数量判断原因。见 Hermes 的 Claude Profile 方案。

账户与额度​

API Key 丢了 — 先在“额度与 API Key”检查再次复制入口；是否可用取决于权限和 Key 状态。怀疑泄露时进行轮换。

创建不了 Key — 查看创建界面的错误提示，检查当前角色权限、所属部门和额度条件；需要时联系管理员。

怎么看用量 — 控制台「用量中心」支持按部门、员工、密钥、模型查看，可导出 CSV。

价格在哪看 — 控制台的模型定价页面，文档站不展示价格。

联系支持时提供什么​

先保存失败时间（含时区）、模型、接口路径、客户端名称和版本，以及 HTTP 状态码与 error.code/type/message。响应中有 request ID 时一并提供；网关可能在 x-oneapi-request-id 或错误消息中给出它。

以下是已观察到的鉴权失败格式，request ID 已替换。code 可以为空，不能只检查这个字段：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: REDACTED)",
    "type": "new_api_error"
  }
}

可复制下面的模板，并删除 API Key、Authorization / Cookie、真实邮箱及业务敏感内容：

失败时间和时区：
客户端及版本：
请求方法与接口路径：
模型名称：
HTTP 状态码：
error.code / type / message：
request ID（若有）：
脱敏后的最小请求体：
目录查询是否成功：
是否在最小请求中复现：

不要发送完整 Key 或未脱敏的 curl -v 输出。401 / 403 先检查认证和权限，参数类 400 先修正请求；重试前先判断错误是否可重试，避免原样循环发送失败请求。