NewAPI 中文接入手册

从 API Key 到客户端调用，一页完成配置

本文档整理了 NewAPI 常见接入流程，包括令牌创建、Base URL 填写、OpenAI 兼容请求、Claude Code、Codex CLI、OpenClaw、外接客户端、模型分组和报错排查。

单文件 index.htmlOpenAI 兼容中文配置手册适合团队内部发布

快速上手

如果你只是想尽快跑通一次请求，按下面四步来。真实域名、令牌和可用模型以你的 NewAPI 后台为准。

登录 NewAPI 后台

进入你的 NewAPI 站点，确认账户余额、可用分组和模型权限。

创建 API Key

在「令牌」或「Token」页面新建令牌。建议给不同客户端单独创建不同令牌，方便统计和撤销。

填写 Base URL

OpenAI 兼容客户端通常填写 https://你的域名/v1。如果客户端要求根地址，则填写 https://你的域名。

选择模型并发送请求

模型名必须使用后台模型广场或接口返回的模型 ID，例如 gpt-4o、claude-sonnet-4-5 或站点自定义别名。

网络问题先排查

如果安装客户端失败，或请求返回 Connection error、ConnectionRefused、Request timed out，先检查代理、TUN 模式、DNS 和防火墙。浏览器能打开后台，不代表命令行也能访问同一网络。

账号与令牌

NewAPI 一般通过 API Key 鉴权。令牌相当于你的调用凭证，泄露后别人可以消耗你的额度。

令牌命名

建议按用途命名，例如 codex-laptop、claude-code-work、cursor-office。

额度限制

如果后台支持额度限制，给测试令牌设置较小额度，避免误调用产生高额消耗。

定期轮换

长期使用的令牌建议定期更换。发现异常消耗时，先禁用令牌，再排查客户端。

Authorization Header

Authorization: Bearer sk-your-newapi-key

Base URL 填写规则

大多数问题都出在 Base URL 是否带 /v1。判断方法是看客户端是否已经内置了 /v1/chat/completions 这类路径。

使用场景	推荐填写	说明
OpenAI SDK	`https://你的域名/v1`	SDK 会继续拼接 `/chat/completions`、`/models` 等路径。
curl 直接请求	`https://你的域名/v1/chat/completions`	完整接口路径写在 URL 中。
Claude Code 转接	按转接工具要求填写	有些工具要根地址，有些工具要兼容 OpenAI 的 `/v1` 地址。
OpenClaw Provider	`https://你的域名` 或 `https://你的域名/v1`	取决于 Provider 类型。OpenAI 兼容 Provider 通常使用 `/v1`。

快速判断是否填错

如果报 404 Not Found，常见原因是多写或少写了 /v1。如果报 401 Unauthorized，通常是 Key 无效、Key 前后有空格，或客户端读取了旧环境变量。

OpenAI 兼容接口

NewAPI 通常暴露 OpenAI 兼容接口。你可以用官方 OpenAI SDK、curl 或任何兼容 OpenAI 协议的客户端接入。

Chat Completions

curl

curl https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-your-newapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是一个简洁可靠的助手。"},
      {"role": "user", "content": "用三句话介绍 NewAPI。"}
    ],
    "temperature": 0.7
  }'

Python SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-newapi-key",
    base_url="https://你的域名/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好，NewAPI。"}],
)

print(response.choices[0].message.content)

模型列表

Models

curl https://你的域名/v1/models \
  -H "Authorization: Bearer sk-your-newapi-key"

客户端配置

不同客户端的字段名称不同，但本质只有三项：API Key、Base URL、Model。遇到报错时，先把这三项逐一核对。

Codex CLI

适合复杂编程任务。安装完成后，把服务商改为 OpenAI 兼容地址，模型填写后台可用的模型 ID。

shell

npm install -g @openai/codex

# Windows 临时环境变量示例
set OPENAI_API_KEY=sk-your-newapi-key
set OPENAI_BASE_URL=https://你的域名/v1

codex

Claude Code

Claude Code 的配置依赖具体转接方案。若你的 NewAPI 提供 Claude 兼容或 OpenAI 到 Claude 的映射，按服务端文档选择对应分组和模型。

不要混填模型名

如果当前分组是 OpenAI 兼容模型，就不要继续填写 Claude 模型名。反过来，如果分组只支持 Claude，也不要填 GPT 模型名。

OpenClaw

在后台添加 Provider，协议选择 OpenAI Compatible 或你的服务端支持的类型，再填写 Base URL、API Key 和可用模型。

Provider 示例

Provider Name: NewAPI
Protocol: OpenAI Compatible
Base URL: https://你的域名/v1
API Key: sk-your-newapi-key
Model: gpt-4o-mini

Cursor、JetBrains、Trae 等外接客户端

选择 OpenAI Compatible、自定义模型或 Custom Provider。Base URL 常见填写 https://你的域名/v1，模型必须和后台一致。

分组与模型

NewAPI 后台可能通过「分组」控制模型路由、价格和权限。下面是常见组织方式，你可以按自己站点实际命名替换。

分组类型	适合用途	模型示例	填写建议
default	默认路由，适合普通对话和测试	`gpt-4o-mini`、`deepseek-chat`	不确定时先用低成本模型测试。
coding	编程、重构、代码审查	`gpt-4.1`、`claude-sonnet`、`qwen-coder`	Codex、Cursor、JetBrains 优先选此类。
reasoning	复杂推理、数学、规划	`o3`、`deepseek-reasoner`	注意推理模型通常更慢且成本更高。
vision	图片理解和多模态输入	`gpt-4o`、`gemini-pro-vision`	客户端必须支持图片输入。
image	图片生成与编辑	`gpt-image-1`、`imagen`	调用路径和请求格式可能不同于文本模型。

最终模型名、倍率和上下文长度，请以 NewAPI 后台「模型」或「模型广场」页面为准。

外接接入与 User-Agent

部分 NewAPI 站点会根据客户端、分组或请求头做风控。外接客户端无法调用时，可以检查是否需要指定 User-Agent。

客户端	常见问题	排查方向
Cursor	模型列表为空，或请求 401	确认 Key 是否填在自定义 Provider 中，Base URL 是否带 `/v1`。
JetBrains AI	连接成功但调用失败	检查模型名是否支持该客户端的消息格式。
Trae	提示网络错误	测试命令行 curl 是否能访问同一 Base URL。
自写脚本	返回 400 参数错误	对照 OpenAI 兼容字段，删除服务端不支持的实验参数。

带 User-Agent 的请求

curl https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-your-newapi-key" \
  -H "Content-Type: application/json" \
  -H "User-Agent: NewAPI-Docs/1.0" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

图像接口与 MCP

如果你的 NewAPI 站点开放图像模型，可以把图像生成或编辑能力接入到支持 MCP 的客户端中。这样 Claude Code、Codex 或编辑器助手可以通过工具调用完成生成、改图和批处理。

直接 API 调用

适合后端服务、脚本和自动化流程。优点是稳定可控，缺点是需要自己处理文件上传、轮询和结果保存。

MCP 封装

适合在 AI 编程工具里使用。把图像接口包装成工具后，模型可以按任务自动调用。

注意模型能力边界

图片理解、图片生成、图片编辑通常是不同能力。不要把只支持文本的模型用于图像任务，也不要把生成接口当成聊天接口调用。

报错与排查

下面是 NewAPI 接入时最常见的错误。建议从状态码、错误信息、客户端配置三层一起看。

错误	常见原因	处理方式
`401 Unauthorized`	Key 错误、Key 已禁用、环境变量覆盖	重新复制令牌，删除前后空格，检查客户端是否读取旧 Key。
`404 Not Found`	Base URL 路径错误	检查是否多写或少写 `/v1`。
`400 Invalid model`	模型名不存在或分组不支持	到后台复制精确模型 ID，不要凭印象填写。
`429 Rate limit`	额度不足、并发过高、分组限速	降低并发，更换分组，检查账户余额。
`Connection error`	网络、代理、DNS、证书或防火墙问题	先用 curl 测试，再检查代理和 TUN 模式。
`context length exceeded`	输入超出模型上下文	缩短消息，清理历史，选择更长上下文模型。

排查顺序

先用最小 curl 请求测试 Base URL 和 Key。
再调用 /v1/models 确认可用模型名。
最后回到客户端配置，检查是否有旧环境变量或缓存配置。

安全建议

不要把 Key 写进前端

浏览器页面、公开仓库、截图和日志都可能泄露令牌。前端调用应通过自己的后端转发。

为不同用途拆分令牌

工作站、服务器、测试脚本分别使用不同 Key，出现异常时可以精准禁用。

限制额度和并发

对临时测试令牌设置额度上限，避免循环脚本或工具误调用。

保留调用日志

出现账单异常时，通过模型、分组、时间和客户端信息快速定位来源。

FAQ

Base URL 到底要不要带 /v1？

OpenAI SDK 和大多数 OpenAI Compatible 客户端要带 /v1。如果客户端文档明确说填写根地址，才不带。

为什么后台有模型，客户端仍然提示模型不存在？

可能是令牌没有对应分组权限，或客户端填的模型名和后台模型 ID 不完全一致。大小写、横线和后缀都要一致。

同一个 Key 能不能给多个客户端用？

技术上可以，但不建议。多个客户端共用 Key 时，很难排查具体是哪一个产生异常消耗。

为什么浏览器能打开 NewAPI，命令行请求却失败？

浏览器和命令行可能走不同代理。命令行需要单独配置代理，或者开启系统级 TUN 模式。