AIHubMix Base URL怎么填？不同协议的正确地址与配置方法

更新于 2026-10-30 · aihubmix.cyou

简答：如果你使用 OpenAI 兼容客户端，Base URL 填 <code>https://aihubmix.com/v1</code>；不要填完整的 <code>/chat/completions</code>。Anthropic SDK 或 Claude Code 通常填 <code>https://aihubmix.com/</code>，Gemini 原生 SDK 使用 <code>https://aihubmix.com/gemini</code>。再确认 API Key、模型 ID 与协议匹配，最后用一次最小请求验证。

定义：Base URL 是客户端自动拼接具体 API 路径前使用的接口根地址，不等同于完整的请求 Endpoint。

先看这张表：AIHubMix Base URL到底填哪个地址

先判断你正在使用的协议，而不是先复制搜索结果里的完整请求地址。AIHubMix官方文档目前分别列出了 OpenAI 兼容、Anthropic 兼容和 Gemini 原生调用方式；截至2026年10月30日，常见填写规则如下。

AIHubMix不同协议的 Base URL 与完整 Endpoint
使用场景Base URL填写完整请求示例认证方式
OpenAI兼容客户端https://aihubmix.com/v1https://aihubmix.com/v1/chat/completionsAuthorization: Bearer
Anthropic SDK、Claude Codehttps://aihubmix.comhttps://aihubmix.com/v1/messagesx-api-key或客户端对应配置
Gemini原生SDKhttps://aihubmix.com/gemini由SDK按Gemini协议继续拼接Gemini SDK对应的API Key配置
Gemini模型走OpenAI兼容格式https://aihubmix.com/v1按OpenAI兼容路径调用Authorization: Bearer

官方快速开始示例把 OpenAI SDK 的 base_url 设置为 https://aihubmix.com/v1，并把具体的 /chat/completions 留给SDK或请求代码拼接；Anthropic兼容文档则把客户端地址设置为不带 /v1 的 https://aihubmix.com。官方 Quick Start、Anthropic API兼容文档

最容易犯的错误：在 OpenAI 兼容客户端中填入 https://aihubmix.com/v1/chat/completions。如果客户端还会自动追加 /chat/completions，最终路径可能重复，导致404或接口不存在。

不同客户端怎么配置：只改四个字段

Cherry Studio、Cursor、Cline、Dify、Jan、OpenWebUI等工具的界面名称可能不同，但核心字段通常一致：协议类型、Base URL、API Key、模型 ID。优先选择“OpenAI Compatible”“OpenAI兼容”或类似选项，再按下表填写。

常见客户端的通用填写方式
字段建议填写注意事项
协议或提供商类型OpenAI Compatible不要在OpenAI兼容模式中选择Anthropic协议
Base URLhttps://aihubmix.com/v1通常不填完整的/chat/completions
API Key你的实际AIHubMix Key不要把占位符、前后空格或其他平台Key粘贴进去
Model从当前模型列表复制的准确ID显示名称不一定等于API模型ID
  1. 先选协议：普通聊天客户端和大多数OpenAI SDK优先选OpenAI兼容模式。
  2. 再填地址：填https://aihubmix.com/v1，末尾通常不需要额外斜杠。
  3. 粘贴Key：使用实际密钥，不要把Key写进前端代码、公开仓库或截图。
  4. 填写模型ID：从当前模型目录复制，不要凭显示名称猜测。
  5. 保存后测试：先调用模型列表或发送一句很短的消息，确认返回正文而不是只看HTTP状态码。

如果工具有“自动补全路径”“Add /chat/completions”或“Endpoint”按钮，先查看输入框当前内容：已经填入完整Endpoint时不要再次点击补全；如果只填了Base URL，才让工具补全具体路径。

如果你使用Gemini原生SDK，不能直接把 OpenAI兼容地址当作原生地址。AIHubMix的Gemini指南把原生SDK示例地址写为https://aihubmix.com/gemini；而使用OpenAI格式调用Gemini模型时，仍使用https://aihubmix.com/v1。官方 Gemini 指南

用最小请求验证：先确认地址，再排查Key和模型

不要一开始就接入复杂Agent、流式输出或长上下文。先用一个最小的OpenAI兼容请求验证三件事：域名能访问、Key被识别、模型ID可用。下面的命令中的Key和模型只是占位内容，必须替换为你自己的实际值。

curl "https://aihubmix.com/v1/chat/completions" -H "Authorization: Bearer YOUR_AI_HUB_MIX_KEY" -H "Content-Type: application/json" -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"ping"}]}'

成功判定不是只看返回200，而是确认响应正文中有模型回复，并且没有出现认证、模型不存在或额度错误。官方快速开始示例同样使用/v1/chat/completions完整路径发起请求，并要求把模型替换为模型目录中的可用ID。官方 Quick Start

Python的OpenAI SDK配置可以写成：

from openai import OpenAI
client = OpenAI(api_key="YOUR_AI_HUB_MIX_KEY", base_url="https://aihubmix.com/v1")
response = client.chat.completions.create(model="YOUR_MODEL_ID", messages=[{"role":"user","content":"ping"}])
print(response.choices[0].message.content)

密钥建议放进环境变量，并在提交代码前检查.gitignore、Shell历史、CI日志和调试输出，避免把真实Key写入仓库或错误日志。

401、404、429和超时：按返回结果分流

配置失败时，先保留HTTP状态码、响应正文和请求追踪ID，再按下面顺序处理。不要看到任何错误都重复重试，尤其是余额、权限、模型不存在等问题。

AIHubMix Base URL常见错误排查表
现象优先检查处理方法
401 UnauthorizedKey为空、失效、复制错误或认证头不对重新复制Key；OpenAI兼容请求检查Authorization: Bearer；Anthropic请求检查对应的x-api-key
403 Forbidden余额、权限、IP限制或模型权限检查Key限制、账户状态和模型授权，不要只改Base URL
404或接口不存在/v1重复、路径缺失或把完整Endpoint当Base URLOpenAI兼容客户端恢复为https://aihubmix.com/v1，并检查是否重复追加路径
429 Too Many Requests请求频率或网关限流遵守响应中的Retry-After；没有该字段时采用有上限的退避，不要无限重试
超时或无法连接网络、DNS、代理、客户端超时设置或服务端响应慢先用curl测试域名，再检查本机网络和代理；不要直接断定是Key错误
模型不存在或无可用通道模型ID拼写、模型权限或当前可用性从当前模型列表重新复制ID；确认Key允许访问该模型

官方HTTP状态码文档将401主要归为缺少或无效访问令牌，将403细分为余额、权限、IP范围和模型授权等情况，并说明429通常与请求频率超过限制有关。官方 HTTP Status Codes Overview

一个实用分流：如果同一个Key调用模型列表也失败，先查Key、权限和网络；如果模型列表成功但聊天请求失败，重点查模型ID、协议和请求体；如果只有某一个模型失败，不要立即修改Base URL，应先核对该模型当前是否可用以及Key是否被授权。

备用地址什么时候用？如何避免把问题越查越复杂

官方快速开始页面说明，示例默认使用主域名https://aihubmix.com；如果遇到访问问题，可以将请求地址替换为页面列出的备用域名，其他参数保持不变。备用地址是否适合你的客户端，要以当前官方文档和实际网络测试为准，不要把第三方文章中的备用域名直接当成永久配置。

排查时建议按这个顺序做：

  1. 确认客户端协议是OpenAI兼容、Anthropic兼容还是Gemini原生。
  2. 确认Base URL只填根地址，避免重复拼接版本号和接口路径。
  3. 用同一个Key执行一次最小请求。
  4. 保存状态码、响应正文和追踪ID。
  5. 仅在确认主域名无法访问时，再按官方文档切换备用地址。

这样可以把“地址错误”“认证失败”“模型不可用”和“网络无法连通”分开，避免反复修改多个字段后失去定位线索。

配置前自查清单

  • OpenAI兼容：https://aihubmix.com/v1。
  • Anthropic兼容：通常使用https://aihubmix.com，由SDK请求/v1/messages。
  • Gemini原生：使用https://aihubmix.com/gemini。
  • 完整Endpoint：只在工具要求“Proxy URL”或“请求地址”时填写，例如/v1/chat/completions。
  • 模型：使用模型目录中的准确ID，不要使用猜测的显示名称。
  • 成功判定：返回有效模型回复，并检查响应正文而不是只看状态码。
  • 安全：Key不放前端、不提交到公开仓库、不写入日志。

如果你只是想快速完成客户端接入，优先走OpenAI兼容模式；只有在工具明确要求Anthropic或Gemini原生协议时，才切换到对应的地址和认证方式。

常见问题

AIHubMix Base URL可以直接填 https://aihubmix.com/v1/chat/completions 吗？

只有在客户端字段明确要求完整Proxy URL或完整Endpoint时才这样填。普通OpenAI兼容SDK的Base URL应填 <code>https://aihubmix.com/v1</code>，具体的 <code>/chat/completions</code> 通常由SDK自动追加，否则可能形成重复路径并返回404。可参考官方 Quick Start。

为什么OpenAI兼容接口要带 /v1，而Claude Code通常不带？

两者使用的协议和客户端路径拼接方式不同。OpenAI兼容示例的Base URL是 <code>https://aihubmix.com/v1</code>；Anthropic兼容示例的客户端地址是 <code>https://aihubmix.com/</code>，请求路径为 <code>/v1/messages</code>。不要把一种协议的地址复制到另一种协议。参考Anthropic API兼容文档。

Gemini模型应该填哪个Base URL？

如果使用Gemini原生SDK，官方指南示例使用 <code>https://aihubmix.com/gemini</code>；如果在OpenAI兼容客户端中调用Gemini模型，则使用 <code>https://aihubmix.com/v1</code>。先确认客户端协议，再填写地址。参考官方 Gemini 指南。

Base URL末尾要不要加斜杠？

通常直接使用文档示例中的地址，不额外添加末尾斜杠：OpenAI兼容使用 <code>https://aihubmix.com/v1</code>，Anthropic兼容使用 <code>https://aihubmix.com/</code>。如果某个客户端自动规范化URL，应以它实际生成的请求路径为准，重点检查是否出现重复斜杠或重复的 <code>/v1</code>。

填对Base URL后仍然401，应该怎么办？

401优先检查Key是否为空、过期、复制错误或带有空格，再检查认证头：OpenAI兼容请求通常使用 <code>Authorization: Bearer</code>，Anthropic兼容请求使用对应的 <code>x-api-key</code>配置。若Key正确但仍失败，保存响应正文和追踪ID，再核对Key状态与权限，不要只反复修改Base URL。参考官方 HTTP Status Codes Overview。

相关阅读

参考资料

  1. AIHubMix Quick Start：API Key、Base URL与首次调用（docs.aihubmix.com）
  2. AIHubMix Anthropic API兼容（Beta）（docs.aihubmix.com）
  3. AIHubMix Gemini指南：原生与OpenAI兼容调用（docs.aihubmix.com）
  4. AIHubMix HTTP Status Codes Overview（docs.aihubmix.com）
  5. AIHubMix中文文档首页：兼容接口与协议导航（docs.aihubmix.com）