协议选择指南

很多用户第一次接入失败，不是 Key 错，也不是模型不能用，而是客户端协议选错了。协议决定请求路径、请求体结构、鉴权头和流式返回格式，不能只看模型名。

一句话选择

你使用的工具先选这个协议Base URL
ChatBox、Cherry Studio、LobeChat、Dify、沉浸式翻译OpenAI Chathttps://www.wanmoapi.com/v1
Codex、部分 Agent 框架OpenAI Responseshttps://www.wanmoapi.com/v1
Claude Code、Cline 的 Anthropic 模式Claude Messageshttps://www.wanmoapi.com
Gemini 官方 SDK / 原生客户端Gemini 原生https://www.wanmoapi.com
Warning

不要把 /v1/chat/completions、/v1/responses、/v1/messages 手动拼进客户端的 Base URL，除非该客户端明确要求填写完整 endpoint。大多数客户端只需要 Base URL。

四种协议对比

协议典型路径请求体关键词适合场景不适合场景
OpenAI Chat/v1/chat/completionsmessages桌面聊天、翻译、Dify、普通 OpenAI SDKCodex 这类需要 Responses 的编码代理
OpenAI Responses/v1/responsesinput、工具调用事件Codex、Agent、工具调用、多步任务只支持 Chat Completions 的旧客户端
Claude Messages/v1/messagesmessages、anthropic-versionClaude Code、Anthropic 模式客户端OpenAI Compatible 模式
Gemini 原生/v1beta/models/...:generateContentcontentsGemini SDK、Gemini 原生生态OpenAI SDK
Chat：最通用，绝大多数桌面客户端用它。Base URL 填 https://www.wanmoapi.com/v1，请求路径由客户端拼成 /chat/completions。

Base URL 怎么判断

客户端字段名称通常应该填什么备注
Base URL / API Host / Endpointhttps://www.wanmoapi.com/v1OpenAI 兼容客户端最常见
OpenAI Base URLhttps://www.wanmoapi.com/v1不要再加 /chat/completions
API Address / Proxy URLhttps://www.wanmoapi.com 或 https://www.wanmoapi.com/v1看客户端是否自动补 /v1
Anthropic Base URLhttps://www.wanmoapi.comClaude Messages 常见写法
Gemini Base URLhttps://www.wanmoapi.com由 SDK 拼 /v1beta/...

如果不确定客户端是否自动补 /v1，先填 https://www.wanmoapi.com/v1。如果报 404 且日志里显示路径重复，例如 /v1/v1/chat/completions，改成 https://www.wanmoapi.com。

复制验证请求

OpenAI Chat

curl https://www.wanmoapi.com/v1/chat/completions \
  -H "Authorization: Bearer $WANMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

OpenAI Responses

curl https://www.wanmoapi.com/v1/responses \
  -H "Authorization: Bearer $WANMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "你好，用一句话介绍你自己"
  }'

Claude Messages

curl https://www.wanmoapi.com/v1/messages \
  -H "x-api-key: $WANMO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-7-sonnet",
    "max_tokens": 200,
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

Windows PowerShell 用户请把 $WANMO_API_KEY 改成 $env:WANMO_API_KEY。

排查顺序

  1. 确认客户端支持的协议。
  2. 确认 Base URL 是否只填到客户端要求的位置，不要重复拼路径。
  3. 确认模型名属于该协议支持的模型。
  4. 用在线调试先验证 Key 与模型是否可用。
  5. 到控制台调用日志里看实际请求路径和上游错误。

典型错误

报错可能原因处理
404 not foundBase URL 多拼或少拼 /v1看日志里的实际路径
model not found模型名不属于当前分组或协议换控制台可用模型
invalid request bodyChat / Responses 请求体混用按协议示例重填
unsupported stream event客户端期望的流式格式不匹配换正确协议或关闭流式测试
401鉴权头或 Key 错回到认证与令牌

下一步：选择你的客户端接入教程。