⌕ 搜索

OpenAI兼容接口三项参数怎么填：base_url、model和API Key

更新于 2026-10-22 · 01up.cn

简答：OpenAI 兼容接口中，base_url 填服务商提供的接口根地址，model 填该平台模型列表返回的 ID，API Key 填同一账号创建的密钥；再检查路径、权限和限流。

定义：OpenAI 兼容接口通常指使用相近请求格式、认证方式和资源路径，使现有客户端或代码能够连接不同服务端的接口。

先按这张表填写 OpenAI 兼容接口

更新于 2026 年 10 月 22 日。本文帮你完成配置 OpenAI 兼容接口前的三项核对：确认接口根地址、复制真实模型 ID、使用匹配的 API Key。服务商没有明确说明的字段，不要凭经验补写。

OpenAI 兼容接口三项参数速查
字段应填写什么不要填写什么核对方法
base_url服务商提供的接口根地址，是否包含 /v1 以客户端和服务商文档为准通常不要直接填完整的 /chat/completions 路径确认客户端最终请求是否会重复拼接版本路径
model平台实际开放的模型 ID中文名称、网页标题、厂商名称或自行猜测的名称优先从服务商控制台或 /v1/models 返回结果复制
API Key同一服务商控制台创建的密钥原文不要把已经带上的 Bearer 再粘贴进密钥字段确认密钥属于当前 base_url 对应的账号和权限体系

一眼照填的占位示例是：base_url=https://api.example.com/v1、model=从模型列表复制的真实ID、API Key=控制台复制的密钥原文。这里的域名和模型值只是格式占位，不代表可直接调用的服务。

OpenAI 官方接口文档把模型列表请求写成 GET /v1/models，聊天请求写成 POST /v1/chat/completions；兼容接口是否完全支持这些路径，仍应以对应服务商文档为准，可参考模型列表接口说明和聊天请求接口说明。

按最终请求地址判断 /v1 是否重复

base_url 最容易出错的地方，是把接口根地址、版本路径和具体资源路径混在一起。可以先画出最终请求地址：

如果客户端会自动添加 /v1，你填入的地址就可能不应再包含 /v1；如果客户端只是在 base_url 后拼接资源路径，则通常需要由你确认版本前缀。没有客户端官方说明时，不能把“必须带”或“绝对不能带”作为通用规则。

排查时查看客户端日志或开发者工具中的最终 URL。若出现 /v1/v1/，优先检查版本路径是否被填写两次；若出现 /chat/completions/chat/completions，说明根地址中已经包含资源路径，或客户端又自动拼接了一次。除非客户端文档明确要求完整端点，否则优先填接口根地址。

本站的AI 搜索可见性审计和AI 引用观察记录协议都强调先固定可复查的输入和输出；配置接口时也应记录“填写值、最终 URL、返回状态码”三项，而不是只看客户端界面是否保存成功。

用 curl 先验证模型列表，再验证最小请求

用 curl 先验证模型列表，再验证最小请求

下面示例运行环境为 Linux、macOS 或已安装 curl 的终端。先把密钥放进当前会话环境变量，不要把真实密钥写进脚本、网页、公开仓库或截图。

export BASE_URL='https://api.example.com/v1'
export API_KEY='把控制台复制的密钥放在这里'
export MODEL_ID='把模型列表返回的 id 放在这里'

curl "$BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

如果服务商提供模型列表接口，先观察返回 JSON 中的 id 字段，再把完整值赋给 MODEL_ID。不要把展示名称、中文别名或截断后的字符串当作模型 ID。官方模型列表示例使用 Authorization: Bearer 认证，并返回模型对象列表，可对照模型列表参考。

确认模型列表请求成功后，再发送一条非流式短请求。这里使用双引号包裹 JSON 字符串，是为了让 shell 展开 $MODEL_ID；如果用单引号包住整个 JSON，变量会按字面量发送，容易得到模型不存在的错误。

curl "$BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"请只回复：配置成功\"}]}"

官方聊天接口示例同样使用 JSON 请求体、model 和 messages 字段；curl 的 --data 会按命令行提供的内容发送数据，因此引号和变量展开必须先在本地 shell 中确认。可分别参考聊天接口参考与curl 手册。

如果服务商没有提供模型列表接口，原文未说明时不要假设一定存在；改为从控制台的模型详情或服务商接口文档复制模型 ID，并保留一条能复现的最小请求。

按返回结果排查 401、403、404、429 和 model not found

错误现象与排查顺序
现象优先检查下一步
401 UnauthorizedAPI Key 是否为空、过期、复制不完整，Authorization 是否重复添加 Bearer重新生成或复制密钥，并确认它属于当前 base_url 的账号
403 Forbidden密钥身份是否有效，但没有访问该模型或接口的权限检查账号权限、项目范围和模型访问资格
404 Not Foundbase_url、版本路径或资源路径是否拼接错误记录最终 URL，重点检查 /v1 重复、缺失和完整端点重复
429 Too Many Requests请求频率、并发量或账号限流降低请求频率；若响应提供 Retry-After，按其要求等待
model not foundmodel 是否为真实 ID，或该 Key 是否有模型权限重新查询模型列表并复制 id，确认三项参数属于同一服务体系

状态码只能帮助定位方向，不能单独证明具体配置项。MDN 对 401 的定义是缺少有效认证凭据，对 403 的定义是服务器理解身份但拒绝访问；404 表示请求资源不存在，429 表示请求过多。可查看401 说明、403 说明、404 说明和429 说明。

建议固定以下排查顺序：第一步看最终请求 URL；第二步单独验证 API Key；第三步查询或确认模型 ID；第四步确认账号权限；第五步检查频率和服务端状态。这样可以避免在模型名、路径和密钥之间反复猜测。

接入前的五项安全与兼容性自查

  1. 同一服务体系：base_url、model 和 API Key 应来自同一服务商、同一账号或同一模型权限体系。把一个平台的地址、另一个平台的密钥和第三个平台的模型名混用，不能视为有效配置。
  2. 密钥不进前端：浏览器代码、公开仓库、日志、截图和聊天记录都不应暴露真实 API Key。前端调用应经过你控制的后端接口，并由后端保存密钥。
  3. 先非流式后流式：首次验收先使用短文本和非流式请求，确认认证、路径、模型和 JSON 格式都正常，再测试流式输出。
  4. 记录版本与原文：模型 ID、路径规则和字段支持可能变化，保存查阅日期、服务商文档地址和实际响应，后续更换客户端时更容易复现。
  5. 不要扩大结论：一个兼容接口能处理聊天请求，不代表它支持图片、工具调用、嵌入、流式或所有参数；能力必须逐项以接口文档和实际响应确认。

如果你还在做 AI 内容或搜索实验，可继续查看GEO 内容审计清单，把“请求是否成功”和“结果是否符合内容目标”分成两类指标记录。

常见问题

OpenAI 兼容接口的 base_url 到底要不要加 /v1？

不能一概而论。先确认客户端是否自动拼接 /v1，再查看最终请求 URL；出现 /v1/v1/ 时通常是重复填写。

model 应该填模型名称还是模型 ID？

应填平台实际接受的模型 ID，优先从模型列表返回的 id 或服务商控制台复制，不要填中文展示名或网页标题。

API Key 前面要不要手动加 Bearer？

通常字段只填密钥原文，客户端会自动生成 Authorization: Bearer 请求头；只有客户端明确要求完整认证字符串时才按其说明填写。

为什么三个参数都填了还是 model not found？

优先检查模型 ID 是否拼写完整、是否属于当前接口，以及 API Key 是否拥有该模型权限；地址、密钥和模型不匹配也会导致此错误。

出现 401 和 403 时应该先查什么？

401 先查密钥是否有效和认证头格式，403 再查账号是否有接口或模型权限；不要先修改模型名称。

相关阅读

参考资料

  1. 模型列表接口参考
  2. 聊天请求接口参考
  3. curl 官方手册
  4. HTTP 401 状态码说明
  5. HTTP 403 状态码说明
  6. HTTP 404 状态码说明
  7. HTTP 429 状态码说明