常见问题
最小自检
出问题先跑这两条，能快速定位是 Key 的事还是调用的事。
一、Key 和网络是否正常
curl https://api.smartwan.com/v1/models \
-H "Authorization: Bearer sk-你的Token"
返回模型列表说明 Key 有效、网络可达。
二、对话是否正常
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": 20
}'
第一条通、第二条不通，问题在请求体或模型名上。
错误码
| 错误 | 常见原因 | 怎么办 |
|---|---|---|
| 401 | Key 错误、没带鉴权头、Header 名称写错 | 核对协议对应的 Header：OpenAI 用 Authorization: Bearer，Anthropic 用 x-api-key，Gemini 用 x-goog-api-key |
| 400 | 缺必填参数，或模型不支持某参数 | 检查 model、messages；删掉不确定的高级参数重试 |
| 404 | URL 路径写错 | 统一用 https://api.smartwan.com/v1/...；旧路径 /openai/v1、/anthropic/v1、/google/v1beta 均已废弃 |
| 429 | 请求过频或上游限流 | 降并发、稍后重试，或换个模型 |
500 not implemented | 该模型不支持这个接口 | 多半是非 GPT 模型调了 Responses API，改用 /v1/chat/completions |
| 503 / 504 | 上游渠道不可用 | 稍后重试；图片编辑先关掉 stream，别用 mask |
Base URL 到底怎么填
最高频的问题。按场景对号入座：
| 场景 | 填什么 |
|---|---|
OpenAI SDK 的 base_url / baseURL | https://api.smartwan.com/v1 |
| 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 填重复了。
各接口的实测状态
以下为当前环境的实测结论，帮助判断某个能力是否可直接使用。
| 接口 | 状态 | 说明 |
|---|---|---|
/v1/models | ✅ 可用 | 返回当前可用模型列表 |
/v1/chat/completions | ✅ 可用 | GPT、Claude、DeepSeek、MiniMax 等代表模型均验证通过 |
/v1/messages | ✅ 可用 | Claude、DeepSeek、Kimi、MiniMax 代表模型均可请求 |
/v1beta/models/{model}:generateContent | ✅ 可用 | Gemini 代表模型验证通过 |
| 流式输出 | ✅ 可用 | 三种协议的 stream 路径均验证通过 |
/v1/responses | ⚠️ 部分模型可用 | 仅 GPT 系验证可用；DeepSeek、Kimi、Claude 返回 not implemented |
/v1/images/... | ✅ 可用 | gpt-image-2 的生成与编辑均验证通过，编辑需上传有效图片 |
已验证可用的参数
| 类别 | 结论 |
|---|---|
| Chat Completions 必填 | model、messages 缺任一都会报错 |
| Chat Completions 常用 | max_tokens、temperature、top_p、stream、stream_options.include_usage、response_format、tools / tool_choice |
| Anthropic Messages | model、messages、max_tokens、system、temperature、stream，以及 DeepSeek 的 thinking |
| Gemini | contents 必填；generationConfig 下的 maxOutputTokens、temperature、topP |
| Responses | model、input、max_output_tokens、JSON 输出格式（GPT 系） |
| 图片生成 | model、prompt、n、size、quality、background、output_format、output_compression、moderation、response_format、stream |
| 图片编辑 | model、image、prompt、n、size、quality、background、output_format；mask 和 stream=true 实测不稳定 |
已知的模型参数限制
kimi-k3 实测要求 temperature=1，传其他值会报 400。遇到 temperature 相关报错先设回 1。
其他厂商的特殊限制见厂商调用差异。
具体问题
模型列表拉不到 / 是空的
Key 无权限、账户无额度，或工具刷新异常。先用上面的最小自检命令确认 /v1/models 能不能返回。
工具里配置能保存，但一对话就报错
Base URL、模型名或 API 类型三者之一不匹配。模型名务必从模型列表复制，不要手打。
模型名报不存在
大小写敏感。MiniMax-M2.7 不能写成 minimax-m2.7。另外模型会更新换代，文档里的示例名可能已下线，以模型列表实时返回为准。
参数报错，不知道是哪个参数
先退回最小请求体（只留 model + messages），确认能通之后逐个加回参数，就能定位到具体是哪个。
图片生成失败
确认模型是 gpt-image-2，先只用 prompt、n、size 这几个基础参数测试。
图片接口的 response_format=url 没返回外部链接
当前环境会返回 data URL / base64，这是预期行为，不是故障。
图片编辑报错
确认上传的是有效图片文件，并且不要用 mask 和 stream=true——这两个当前实测不稳定。
Codex 里模型报 not implemented
Codex 只走 Responses API，而该模型不支持。换成 GPT 系模型。详见 Codex 页。
Claude 在 Agent 工具里报 400
工具定义太多，触发了 Anthropic 的 schema 复杂度限制。见 Hermes 的 Claude Profile 方案。
账户与额度
API Key 丢了 — 无法找回，删除重建。
创建不了 Key — 所属部门还没分到额度，联系企业管理员分配。
怎么看用量 — 控制台「用量中心」支持按部门、员工、密钥、模型查看，可导出 CSV。
价格在哪看 — 控制台的模型定价页面，文档站不展示价格。
还没解决就带上完整的错误响应体联系管理员，那里通常写明了具体原因。