从注册到生产，五分钟跑通

介绍

NewAPI 是一个聚合多家 LLM 厂商的统一网关。一把 API Key、 一个 OpenAI 兼容协议，覆盖 Claude、GPT、Gemini、DeepSeek、通义千问、 Moonshot、Doubao 等主流模型。

它能解决什么

• 不需要分别维护多家厂商账号、不需要多套 SDK；
• 不再被单家上游故障/限流卡住业务，多通道自动容灾；
• 港/新加坡线路加速，国内访问稳定低延迟；
• 按 Token 实时计费，账单清晰，团队多账号结算；
• 不留痕、不训练、全链路加密，必要时支持自部署。

谁在用

• 把 GPT/Claude 集成进自家产品的应用开发者；
• 跑批量任务、做 RAG / Agent 的初创团队；
• 需要在国内访问国外模型的研究者；
• 希望统一管理团队 Token 花销的工程团队。

快速开始

三步走通整个调用链路。预计耗时 5 分钟。跟着每个 step 复制粘贴即可。

1. 1

   注册账号

   打开 https://new2api.com，用邮箱或 GitHub 登录。 新账号会自动创建一个默认 Workspace。

2. 2

   创建 API Key

   在控制台 → API Keys 页面点击「新建」，复制 sk- 开头的密钥到本地环境变量：

   复制 已复制

   export NEW2API_KEY="sk-..."

   密钥只在创建时显示一次。如果丢失，去控制台重新生成即可，旧的会立即失效。
3. 3

   第一次调用

   用 curl 验证密钥与基础调用：

   复制 已复制

   curl https://new2api.com/v1/chat/completions \
     -H "Authorization: Bearer $NEW2API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "claude-haiku-4-5",
       "messages": [{ "role": "user", "content": "Hello" }]
     }'

   正常返回的响应体里能看到 choices[0].message.content 字段，就成功了。

   恭喜，链路打通了。接下来按需要换 SDK / 切模型 / 加流式 —— 看下一章。

CLI 快速上手

NewAPI 为 Claude Code、Codex、Gemini CLI 三款主流 AI 编码命令行工具 提供原生协议级兼容。按下方步骤复制粘贴即可上线。

3.1 Claude Code

Anthropic 官方 AI 编码 CLI。把 ANTHROPIC_BASE_URL 指向 NewAPI，鉴权用同一把 sk- 密钥。

# 1) 安装
npm install -g @anthropic-ai/claude-code

# 2) 配置环境变量（写入 ~/.zshrc 或 ~/.bashrc）
export ANTHROPIC_BASE_URL="https://new2api.com/v1"
export ANTHROPIC_AUTH_TOKEN="$NEW2API_KEY"

# 3) 启动
cd your-project && claude

3.2 Codex (OpenAI)

OpenAI 官方 AI 编码 CLI。需要写两个配置文件 + 启动命令。

# 1) 安装
npm install -g @openai/codex

# 2) 写入两个配置文件（路径见下方），然后启动
codex

model = "gpt-5.4"
model_provider = "new2api"

[model_providers.new2api]
name = "NewAPI"
base_url = "https://new2api.com/v1"
wire_api = "responses"

{ "OPENAI_API_KEY": "$NEW2API_KEY" }

3.3 Gemini CLI

Google 官方命令行助手。NewAPI 同时提供 Gemini 原生协议端点（https://new2api.com/v1beta）， 和 Google AI Studio 的请求格式完全一致。

# 1) 安装
npm install -g @google/gemini-cli

# 2) 配置环境变量（NewAPI 提供 Gemini 原生协议端点）
export GEMINI_API_KEY="$NEW2API_KEY"
export GEMINI_API_BASE_URL="https://new2api.com/v1beta"

# 3) 启动
cd your-project && gemini

鉴权

所有请求都用 HTTP Header 携带密钥：

Authorization: Bearer $NEW2API_KEY

多 Key 管理

• 建议为不同项目/环境（开发、预发、生产）分别申请独立 Key；
• 团队成员各自创建 Key，不共享，便于审计和回收；
• 每把 Key 都可在控制台单独 禁用 / 撤销 / 调整额度上限。

密钥泄漏后的处理

1. 立即在控制台「禁用」该 Key（或删除，效果一样）；
2. 检查最近的用量明细，确认是否有非预期调用；
3. 新建一把 Key，更新到生产环境的环境变量；
4. 排查泄漏来源，避免再次提交到 Git / 错误日志。

调用示例

4.1 基础对话（Chat Completion）

from openai import OpenAI

client = OpenAI(api_key="$NEW2API_KEY", base_url="https://new2api.com/v1")

resp = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain RAG in one sentence."},
    ],
)
print(resp.choices[0].message.content)

4.2 流式响应（Streaming）

对长文本输出，强烈建议开启流式，提升用户体感：

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Write a haiku"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

4.3 多模态（图片输入）

支持视觉输入的模型可以接收 image_url 或 base64：

resp = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://..."}},
        ],
    }],
)

4.4 函数调用（Tool Use）

所有支持工具调用的模型（GPT-5.x、Claude 4.x、Gemini 3.x）走相同的协议：

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather in a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[{"role": "user", "content": "Weather in Beijing?"}],
    tools=tools,
)

模型选择

调用时只需在 model 字段填写模型 ID，无需更换 SDK 或 endpoint。常见选择：

对话场景推荐

• 追求质量：claude-opus-4-6 / gpt-5.4
• 性价比平衡：claude-sonnet-4-6 / gpt-5.1
• 极致便宜/快：claude-haiku-4-5 / gemini-3-flash-preview
• 国内合规：deepseek-chat / qwen-max / moonshot-v1-128k
• 开源/可自部署：meta-llama/Llama-3.3-70B-Instruct-Turbo

推理与代码场景

• 复杂推理：deepseek-reasoner / qwq-plus / 任意 reasoning=true 的模型
• 代码生成：gpt-5.3-codex / claude-opus-4-6

多模态

• 图像理解：claude-sonnet-4-6 / gpt-5.4 / gemini-3.1-pro-preview
• 音频/视频：gemini-3.1-pro-preview（原生多模态）

完整列表与实时单价见首页的 模型矩阵 与 价格计算器。

高级技巧

6.1 故障切换（Fallback）

如果你不希望被单一模型卡住，可以在控制台为关键 Key 配置 Fallback Chain：

# Console → API Keys → 选择 Key → Fallback
primary:   claude-opus-4-6
fallback:  - gpt-5.4
           - claude-sonnet-4-6

当主模型超时 / 限流 / 报错时，自动按顺序回退到下一个模型。整个过程对调用方透明，resp.model 字段会标注实际命中的模型。

6.2 Prompt Caching

对于固定的系统提示词或长文档上下文，开启缓存可以大幅降低成本与延迟：

messages=[
    {
        "role": "system",
        "content": long_system_prompt,
        "cache_control": {"type": "ephemeral"},  # Anthropic-style
    },
    ...,
]

缓存命中后输入价格通常降到原价的 1/10。具体规则随模型不同，请查看模型卡的 cacheRead / cacheWrite 字段。

6.3 超时与重试

SDK 层面的最佳实践：

• 非流式：客户端超时设 120 秒 起步（推理类模型可能更长）；
• 流式：禁用客户端超时，依赖网关心跳；
• 重试：仅对 5xx 与 429 重试，幂等场景指数退避（1s / 2s / 4s）；
• 不要对 4xx（除 429）重试 —— 那些是请求本身错误。

计费与用量

7.1 计费方式

按 Token 实时计费。输入 Token 与输出 Token 分别计价（USD per 1M tokens）。 缓存命中时按缓存读取价计费。每次调用结束后扣费完成，账单立即更新。

7.2 查看用量

控制台 → Usage 提供：

• 分模型 / 分 Key / 分日的用量曲线；
• 每次调用的 Token 明细（输入/输出/缓存命中）；
• 导出 CSV，方便接入内部财务系统。

7.3 充值与套餐

支持余额充值（按调用量扣费）与包月套餐两种模式。控制台 → Billing 切换。

常见问题