API 接入

通过 OpenAI、Anthropic 和 Gemini 协议接入 Better Gate，并使用智能路由调用模型。

Better Gate 提供统一的模型网关，同时兼容 OpenAI、Anthropic 和 Gemini 常用协议。你可以继续使用熟悉的 SDK，只需替换 API Key、Base URL 和模型 ID。

接入前准备

登录 Better Gate 控制台。
在“API Keys”创建 Key，并保持默认“智能路由”。
在“模型列表”复制准备调用的模型 ID。
确认当前个人或组织工作区拥有可用额度。

智能路由 Key 可以自动选择支持当前模型的可用渠道，并在异常时切换备用渠道。如果 Key 设置了“指定渠道分组”或模型范围限制，请确认目标模型在允许范围内。

API 地址与鉴权

协议	Base URL	推荐鉴权方式
OpenAI 兼容	`https://gateway.better-gate.com/v1`	`Authorization: Bearer bg_live_...`
Anthropic Messages	`https://gateway.better-gate.com`	`x-api-key: bg_live_...`
Gemini 原生	`https://gateway.better-gate.com/v1beta`	`x-goog-api-key: bg_live_...`

在服务端环境变量中保存配置：

export BETTER_GATE_API_KEY="bg_live_..."
export BETTER_GATE_BASE_URL="https://gateway.better-gate.com"

不要把完整 API Key 写入浏览器前端、公开仓库、日志或截图。

获取可用模型

模型会随渠道配置变化，不建议在应用中长期写死模型清单。使用当前 Key 请求模型列表，可以得到该 Key 实际可访问的模型。

OpenAI 格式

curl https://gateway.better-gate.com/v1/models \
  -H "Authorization: Bearer $BETTER_GATE_API_KEY"

返回结果中的 data[].id 就是请求时使用的模型 ID。supported_endpoint_types 表示模型支持的接口类型，例如：

openai：Chat Completions。
openai-response：Responses API。
openai-response-compact：Responses Compact。
anthropic：Anthropic Messages。
gemini：Gemini 原生生成接口。
image-generation：图像生成或编辑。

Anthropic 格式

curl https://gateway.better-gate.com/v1/models \
  -H "x-api-key: $BETTER_GATE_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Gemini 格式

curl https://gateway.better-gate.com/v1beta/models \
  -H "x-goog-api-key: $BETTER_GATE_API_KEY"

也可以直接在控制台“模型列表”查看模型 ID、支持能力和当前价格。

OpenAI Chat Completions

接口地址：

POST https://gateway.better-gate.com/v1/chat/completions

cURL

curl https://gateway.better-gate.com/v1/chat/completions \
  -H "Authorization: Bearer $BETTER_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      { "role": "user", "content": "请用一句话介绍 Better Gate。" }
    ]
  }'

将 MODEL_ID 替换为控制台中的真实模型 ID。

Python

安装 SDK：

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTER_GATE_API_KEY"],
    base_url="https://gateway.better-gate.com/v1",
)

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {"role": "user", "content": "请用一句话介绍 Better Gate。"}
    ],
)

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

Node.js

安装 SDK：

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
	apiKey: process.env.BETTER_GATE_API_KEY,
	baseURL: "https://gateway.better-gate.com/v1",
});

const completion = await client.chat.completions.create({
	model: "MODEL_ID",
	messages: [{ role: "user", content: "请用一句话介绍 Better Gate。" }],
});

console.log(completion.choices[0].message.content);

流式输出

在请求中加入 stream: true：

stream = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "写一首四行短诗。"}],
    stream=True,
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

OpenAI Responses API

支持 Responses 的模型可以使用：

POST https://gateway.better-gate.com/v1/responses

不要仅根据模型名称判断是否支持 Responses。请以模型列表返回的 supported_endpoint_types 为准。

cURL

curl https://gateway.better-gate.com/v1/responses \
  -H "Authorization: Bearer $BETTER_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "input": "用三点说明智能路由的作用。"
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTER_GATE_API_KEY"],
    base_url="https://gateway.better-gate.com/v1",
)

response = client.responses.create(
    model="MODEL_ID",
    input="用三点说明智能路由的作用。",
)

print(response.output_text)

流式调用：

with client.responses.stream(
    model="MODEL_ID",
    input="逐步解释什么是 API 网关。",
) as stream:
    for text in stream.text_deltas:
        print(text, end="", flush=True)

部分模型还支持 POST /v1/responses/compact。只有模型列表明确包含 openai-response-compact 时才应使用该接口。

Anthropic Messages API

接口地址：

POST https://gateway.better-gate.com/v1/messages

cURL

curl https://gateway.better-gate.com/v1/messages \
  -H "x-api-key: $BETTER_GATE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "请用一句话介绍 Better Gate。" }
    ]
  }'

Better Gate 也接受 Authorization: Bearer ...，但使用 Anthropic SDK 时建议保留原生的 x-api-key 方式。

Python

安装 SDK：

pip install anthropic

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["BETTER_GATE_API_KEY"],
    base_url="https://gateway.better-gate.com",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请用一句话介绍 Better Gate。"}
    ],
)

print(message.content[0].text)

Node.js

安装 SDK：

npm install @anthropic-ai/sdk

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
	apiKey: process.env.BETTER_GATE_API_KEY,
	baseURL: "https://gateway.better-gate.com",
});

const message = await client.messages.create({
	model: "MODEL_ID",
	max_tokens: 1024,
	messages: [{ role: "user", content: "请用一句话介绍 Better Gate。" }],
});

console.log(message.content[0]);

流式请求时在请求体中加入 "stream": true，或使用 Anthropic SDK 的流式方法。

Gemini 原生 API

生成内容接口：

POST https://gateway.better-gate.com/v1beta/models/{model}:generateContent

cURL

curl "https://gateway.better-gate.com/v1beta/models/MODEL_ID:generateContent" \
  -H "x-goog-api-key: $BETTER_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "请用一句话介绍 Better Gate。" }]
      }
    ]
  }'

Gemini 原生接口还接受以下鉴权方式：

Authorization: Bearer bg_live_...
查询参数 ?key=bg_live_...

服务端应用优先使用请求头，避免 Key 出现在 URL、代理记录和访问日志中。

流式输出

curl -N "https://gateway.better-gate.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $BETTER_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "写一首四行短诗。" }]
      }
    ]
  }'

Gemini CLI 等工具通常使用：

export GEMINI_API_KEY="$BETTER_GATE_API_KEY"
export GEMINI_BASE_URL="https://gateway.better-gate.com/v1beta"

具体工具的配置方式请查看 Gemini CLI 接入文档。

图像生成与编辑

只有标记为支持图像接口的模型才能调用以下端点。

生成图像

curl https://gateway.better-gate.com/v1/images/generations \
  -H "Authorization: Bearer $BETTER_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "一座雨后的未来城市，电影感灯光"
  }'

编辑图像

curl https://gateway.better-gate.com/v1/images/edits \
  -H "Authorization: Bearer $BETTER_GATE_API_KEY" \
  -F "model=MODEL_ID" \
  -F "[email protected]" \
  -F "prompt=把天空改成日落时分"

可用尺寸、输出格式和其他参数取决于具体模型，请以模型能力和上游协议为准。

常用环境变量

不同工具对变量名称的要求不同。下面是常见配置：

OpenAI 兼容工具

export OPENAI_API_KEY="$BETTER_GATE_API_KEY"
export OPENAI_BASE_URL="https://gateway.better-gate.com/v1"

Anthropic 工具

export ANTHROPIC_API_KEY="$BETTER_GATE_API_KEY"
export ANTHROPIC_BASE_URL="https://gateway.better-gate.com"

Gemini 工具

export GEMINI_API_KEY="$BETTER_GATE_API_KEY"
export GEMINI_BASE_URL="https://gateway.better-gate.com/v1beta"

如果某个工具要求填写“Host”或“Endpoint”而不是“Base URL”，请在左侧“接入工具”目录中打开对应工具的文档。

排查请求错误

现象	优先检查
`401 Unauthorized`	API Key 是否完整、已停用、已过期或轮换后仍在使用旧 Key。
`403 Forbidden`	Key 的模型范围、IP 限制、指定渠道分组或组织成员权限。
`404`	Base URL 是否重复或遗漏 `/v1`、接口路径是否正确。
`429`	工作区额度、Key 的 RPM/TPM 限制，以及当前模型渠道是否繁忙。
`model_not_found`	模型 ID 是否与“模型列表”完全一致，当前 Key 是否有权访问。
返回格式异常	所选模型是否支持当前协议，工具是否误用了其他厂商的接口格式。

每次请求都会记录到“用量日志”。你可以按 API Key、模型、渠道分组、状态和时间筛选，并查看实际路由、Tokens、费用及原始错误。联系支持时请提供请求 ID 和发生时间，不要发送完整 API Key。

上线建议

为开发、测试和生产环境分别创建 Key。
根据用途限制可用模型、过期时间、RPM 和 TPM。
在服务端读取环境变量，不在客户端代码中暴露 Key。
对 429 和临时 5xx 使用带抖动的指数退避重试。
设置请求超时；流式请求需要单独设置较长的读取超时。
定期在“用量日志”检查异常请求，并在泄露风险出现时立即停用或轮换 Key。

常见问题

一个 Key 可以调用多个模型吗？

可以。默认“智能路由”Key 可以访问其允许范围内、由多个渠道分组提供的模型。调用时只需传入准确的模型 ID。

必须为不同协议创建不同 Key 吗？

不需要。同一个 Better Gate API Key 可以用于 OpenAI、Anthropic 和 Gemini 兼容接口；是否可调用某个模型取决于 Key 权限、路由范围和模型支持的接口类型。

为什么控制台有模型，但请求返回找不到模型？

先使用同一个 Key 请求 GET /v1/models。如果返回列表中没有目标模型，请检查 Key 的模型限制和指定渠道分组；如果模型存在，再检查请求中的模型 ID 和接口类型。

如何确认智能路由最终用了哪个渠道？

打开“用量日志”找到对应请求，即可查看实际使用的渠道分组、模型、Tokens 和费用。

On this page