Gate.AI 文档

统一的 AI 模型路由平台。一个 API 密钥，… 模型，智能自动路由。

快速开始

1. 创建 API 密钥

前往 gate.ai，选择登录模式，授权登录
进入控制台 → 进入设置 → 进入 API 密钥 → 创建密钥

2. 自动路由（可选）

自动路由默认开启，控制方式：

进入控制台 → 进入设置 → 进入路由 → 自动路由开关

开启后，Gate.AI 会自动为每个请求选择最佳模型。如果你更倾向于自行选择模型，可跳过此步，直接指定模型（如 anthropic/claude-sonnet-4.6）。

标准接入

与 OpenAI API 完全兼容，支持 Python、Node.js、curl 等生态工具。

替换 Base URL ( https://api.gate.ai/openai/v1 )与 API 密钥即可使用。

from openai import OpenAI

client = OpenAI(
    api_key="GATEAI_API_KEY",  # get GATEAI_API_KEY from gate.ai (API Key)
    base_url="https://api.gate.ai/openai/v1",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "system", "content": "system prompt"},
        {"role": "user", "content": "how are you?"}
    ],
)

# get the response from LLM (role=assistant)
print(completion.choices[0].message.content)

响应示例：

{
    "id": "243c850e-214c-431e-977f-ebaf4aa95f56",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! Nice to meet you. How can I help you?"
            },
            "finish_reason": "stop"
        }
    ],
    "created": 1773408946,
    "model": "deepseek.v3-v1:0",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 15,
        "total_tokens": 20
    }
}

Claude Code CLI 接入

创建 Gate.AI API 密钥

打开 gate.ai → 控制台 → API 密钥，创建并复制 sk-or-v1-… 开头的 Key
确认账户有余额

网络连通性验证

将 GATEAI_API_KEY 替换为您的密钥：

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

Anthropic 兼容端点（Claude Code）：

curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $GATEAI_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"anthropic/claude-sonnet-4.6","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  https://api.gate.ai/anthropic/v1/messages

返回 200：网关连通，可继续安装与配置
返回 401：密钥无效或已过期，请检查控制台
连接超时：检查本地网络或 DNS；确认未误用 https://api.gate.ai/v1

安装 Claude Code CLI

macOS / Linux / WSL（推荐）：

curl -fsSL https://claude.ai/install.sh | bash

或使用 npm：

npm install -g @anthropic-ai/claude-code

若 npm 安装失败

通常是因为访问 registry.npmjs.org 超时或不稳定，与 Gate.AI 网关无关。可按需选用以下方式：

方式 A：单次安装临时指定镜像（推荐先试）

npm install -g @openai/codex --registry=https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

方式 B：全局永久切换镜像

# 设为 npmmirror（原淘宝 npm 镜像，国内常用）
npm config set registry https://registry.npmmirror.com

# 验证当前镜像
npm config get registry

# 然后重新安装
npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

方式 C：仅当前终端会话临时生效

export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
npm install -g @openai/codex

现象	处理
`ETIMEDOUT` / `ECONNRESET`	使用方式 A 或 B 切换镜像后重试
`EACCES` 权限错误	配置 npm 全局目录：`mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`，并将 `export PATH=~/.npm-global/bin:$PATH` 写入 `~/.zshrc`
`command not found: claude` / `codex`	安装成功但 PATH 未生效：重启终端，或检查 `npm config get prefix` 下的 `bin` 是否在 PATH 中

配置模型

将下文所有 sk-or-v1-你的密钥 替换为您的真实 Key。配置完成后无需重复执行，除非更换 Key 或模型。

mkdir -p ~/.claude

cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    "ANTHROPIC_API_KEY": "sk-or-v1-你的密钥",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
  },
  "includeCoAuthoredBy": false
}
EOF

# 若曾登录 Anthropic / 本地代理，清除旧 session，避免认证冲突
claude /logout 2>/dev/null || true
unset ANTHROPIC_AUTH_TOKEN

认证信息建议只写在 settings.json 一处；若 ~/.zshrc 中仍有 ANTHROPIC_AUTH_TOKEN 或重复的 ANTHROPIC_API_KEY，请注释或删除。

验证接入是否成功

进入项目目录，启动 CLI，即可在终端内进行 AI 辅助编程。

使用 claude

claude

首次验证：输入 /status，确认 Base URL 为 https://api.gate.ai/anthropic，Auth token 为 ANTHROPIC_API_KEY。

进阶配置

认证冲突处理

若出现 Auth conflict: Both a token (ANTHROPIC_AUTH_TOKEN) and an API key (ANTHROPIC_API_KEY) are set：

场景	处理
曾用 Anthropic OAuth / 本地代理登录	`claude /logout`，退出后重新 `claude`
Shell 与 settings 同时配置了 Token 和 Key	只保留 `ANTHROPIC_API_KEY`；注释 `~/.zshrc` 中的 `ANTHROPIC_AUTH_TOKEN`

备选配置方式

Shell 环境变量（勿与 settings.json 重复配置）：

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"

项目级 settings（团队共享结构，勿提交真实 Key）：

路径	用途
`.claude/settings.json`	项目级，可提交（不含密钥）
`.claude/settings.local.json`	项目本地 Key，加入 `.gitignore`

模型环境变量

可在 settings.json 的 env 块中追加：

变量	用途	示例
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Sonnet 级任务	`anthropic/claude-sonnet-4.6`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Opus 级任务	`anthropic/claude-opus-4.6`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Haiku 级任务	`anthropic/claude-haiku-4.5`
`CLAUDE_CODE_SUBAGENT_MODEL`	子 Agent 任务	`anthropic/claude-sonnet-4.6`

完整列表见模型广场。若 auto 报错，请改回显式模型 ID。

恢复直连 Anthropic 官方（可选）

env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY claude

故障排除

Base URL 常见错误

# ❌ 错误（缺 /anthropic 前缀，404）
https://api.gate.ai/v1
https://api.gate.ai/v1/chat/completions

# ❌ 错误（Claude 配置项不要写完整 API 路径）
https://api.gate.ai/anthropic/v1/messages
https://api.gate.ai/anthropic/messages

# ✅ 正确
https://api.gate.ai/anthropic/v1
https://api.gate.ai/anthropic          # Claude Code CLI
https://api.gate.ai/anthropic/v1/messages  # curl 验 Key（Anthropic）
https://api.gate.ai/openai/v1/responses    # curl 验 Key（Codex）

/openai/v1/chat/completions 可用，但 Codex 必须走 Responses API；若报 404 on /responses，检查 wire_api = "responses"，不是改 URL。
/openai/v1/models 不校验 Key（无效 Key 也可能 200）；验 Key 请用上面两个 curl 地址。

现象速查表

现象	错误类型	处理建议
Auth conflict 警告	认证冲突	执行 `claude /logout`；只保留 `ANTHROPIC_API_KEY`，删除或注释 `ANTHROPIC_AUTH_TOKEN`
401 / 鉴权失败	鉴权错误	检查 Key 是否正确、是否过期
404 on URL	路径错误	Claude → `https://api.gate.ai/anthropic`；Codex → `https://api.gate.ai/openai/v1`。勿用 `https://api.gate.ai/v1/...`
模型不存在	模型 ID 错误	使用 `provider/model-name` 格式（如 `anthropic/claude-sonnet-4.6`、`openai/gpt-5.2`），对照模型广场
仍连官方域名	配置未生效	确认写在用户级配置：Claude → `~/.claude/settings.json`；Codex → `~/.codex/config.toml`（项目级 `.codex/config.toml` 无法覆盖网关配置）
显示 offline	CLI 自身行为	不影响主对话，属 Claude Code 自身行为，可忽略
402 / 429	配额 / 限流	充值或检查 Key 预算与调用频率
npm 安装失败	网络 / 权限	见「若 npm 安装失败」

Codex CLI 接入

创建 Gate.AI API 密钥

打开 gate.ai → 控制台 → API 密钥，创建并复制 sk-or-v1-… 开头的 Key
确认账户有余额

网络连通性验证

将 GATEAI_API_KEY 替换为您的密钥：

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

OpenAI 兼容端点（Codex / 标准 API）：

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $GATEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.2","input":"hi","max_output_tokens":16}' \
  https://api.gate.ai/openai/v1/responses

返回 200：网关连通，可继续安装与配置
返回 401：密钥无效或已过期，请检查控制台
连接超时：检查本地网络或 DNS；确认未误用 https://api.gate.ai/v1

安装 Codex CLI

npm install -g @openai/codex

或使用

curl -fsSL https://chatgpt.com/codex/install.sh | sh

若已装 Homebrew

brew install --cask codex

验证：codex --version

若 npm 安装失败

通常是因为访问 registry.npmjs.org 超时或不稳定，与 Gate.AI 网关无关。可按需选用以下方式：

方式 A：单次安装临时指定镜像（推荐先试）

npm install -g @openai/codex --registry=https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

方式 B：全局永久切换镜像

# 设为 npmmirror（原淘宝 npm 镜像，国内常用）
npm config set registry https://registry.npmmirror.com

# 验证当前镜像
npm config get registry

# 然后重新安装
npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

方式 C：仅当前终端会话临时生效

export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
npm install -g @openai/codex

现象	处理
`ETIMEDOUT` / `ECONNRESET`	使用方式 A 或 B 切换镜像后重试
`EACCES` 权限错误	配置 npm 全局目录：`mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`，并将 `export PATH=~/.npm-global/bin:$PATH` 写入 `~/.zshrc`
`command not found: claude` / `codex`	安装成功但 PATH 未生效：重启终端，或检查 `npm config get prefix` 下的 `bin` 是否在 PATH 中

配置模型

将下文所有 sk-or-v1-你的密钥 替换为您的真实 Key。配置完成后无需重复执行，除非更换 Key 或模型。

mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "gateai"
model = "openai/gpt-5.2"

[model_providers.gateai]
name = "Gate.AI"
base_url = "https://api.gate.ai/openai/v1"
env_key = "GATEAI_API_KEY"
wire_api = "responses"
requires_openai_auth = false
EOF

grep -q 'GATEAI_API_KEY=' ~/.zshrc 2>/dev/null || cat >> ~/.zshrc <<'EOF'

# Gate.AI for Codex CLI
export GATEAI_API_KEY="sk-or-v1-你的密钥"
EOF

source ~/.zshrc

Codex 网关相关配置必须写在用户级 ~/.codex/config.toml；项目目录下的 .codex/config.toml 无法覆盖这些项。

验证接入是否成功

进入项目目录，启动 CLI，即可在终端内进行 AI 辅助编程。

使用 codex

codex

若返回正常回复且无 401 / 404，即表示已通过 Gate.AI 路由成功。

进阶配置

配置参考

字段	说明	示例
`model_provider`	Provider 名称	`"gateai"`
`model`	Gate.AI 模型 ID	`"openai/gpt-5.2"`
`base_url`	Gate OpenAI 兼容端点	`https://api.gate.ai/openai/v1`
`env_key`	API Key 环境变量名	`"GATEAI_API_KEY"`
`wire_api`	Codex 协议类型	`"responses"`
`requires_openai_auth`	Gate Key 非 OpenAI 官方格式时	`false`
`model_reasoning_effort`	推理强度（可选）	`"low"` / `"medium"` / `"high"`

备选配置方式

内置 OpenAI Provider（方式 A 鉴权失败时尝试）

model = "openai/gpt-5.2"
openai_base_url = "https://api.gate.ai/openai/v1"

环境变量：export OPENAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

命令行临时覆盖

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
codex --config openai_base_url='"https://api.gate.ai/openai/v1"' --config model='"openai/gpt-5.2"'

切换模型

修改 ~/.codex/config.toml 中的 model，或：codex --model openai/gpt-5.2

恢复直连 OpenAI 官方（可选）

删除 ~/.codex/config.toml 中的 Gate 相关配置，并取消 GATEAI_API_KEY 环境变量。

故障排除

Base URL 常见错误

# ❌ 错误（缺 /openai 前缀，404）
https://api.gate.ai/v1
https://api.gate.ai/v1/chat/completions

# ❌ 错误（Codex 配置项不要写完整 API 路径）
https://api.gate.ai/openai/v1/messages
https://api.gate.ai/openai/messages

# ✅ 正确
https://api.gate.ai/openai/v1          # Codex CLI
https://api.gate.ai/anthropic/v1/messages  # curl 验 Key（Anthropic）
https://api.gate.ai/openai/v1/responses    # curl 验 Key（Codex）

/openai/v1/chat/completions 可用，但 Codex 必须走 Responses API；若报 404 on /responses，检查 wire_api = "responses"，不是改 URL。
/openai/v1/models 不校验 Key（无效 Key 也可能 200）；验 Key 请用上面两个 curl 地址。

现象速查表

现象	错误类型	处理建议
401 / 鉴权失败	鉴权错误	检查 Key 是否正确、是否过期；Codex 确认 `requires_openai_auth = false`
404 on URL	路径错误	Claude → `https://api.gate.ai/anthropic`；Codex → `https://api.gate.ai/openai/v1`。勿用 `https://api.gate.ai/v1/...`
404 on `/responses`	协议错误	Base URL 可能对，但未走 Responses API。检查 `~/.codex/config.toml`：`wire_api = "responses"`，`base_url = "https://api.gate.ai/openai/v1"`
curl `/models` 返回 200 但 CLI 仍 401	验 Key 方法错误	`/openai/v1/models` 不校验 Key。改用 `/openai/v1/responses` 或 `/anthropic/v1/messages` 验 Key
模型不存在	模型 ID 错误	使用 `provider/model-name` 格式（如 `anthropic/claude-sonnet-4.6`、`openai/gpt-5.2`），对照模型广场
仍连官方域名	配置未生效	确认写在用户级配置：Claude → `~/.claude/settings.json`；Codex → `~/.codex/config.toml`（项目级 `.codex/config.toml` 无法覆盖网关配置）
402 / 429	配额 / 限流	充值或检查 Key 预算与调用频率
npm 安装失败	网络 / 权限	见「若 npm 安装失败」

Cursor 接入

前置条件

已安装 Cursor
拥有 Gate.AI API Key

Step 1：打开 Cursor 设置

右上角菜单 → Settings。

Cursor Settings 入口截图 — 参考：打开 Cursor Settings。

Step 2：进入 Models 配置

在左侧菜单中：

找到并打开 Models
点击 View All Models
滑到最底部，点击 Add Custom Model

Cursor Add Custom Model 截图 — 参考：点击 Add Custom Model。

Step 3：添加配置

填写接入信息：

配置项	说明
模型 ID	在模型广场复制某个模型 ID，例如 `deepseek/deepseek-v3.2`。不能填写 `auto`。
OpenAI API Key	打开开关，填写你的 Gate.AI API Key
OpenAI Base URL	打开开关，填写 `https://api.gate.ai/openai/v1`

Cursor API Key 与 Base URL 配置截图 — 参考：填写 API Key 与 Base URL。

Step 4：保存并关闭 Settings 页面

配置完成后保存，关闭 Settings。

Step 5：在 Cursor 中使用 Gate.AI

在 Chat、Composer、Agent 等对话界面中，于模型选择处搜索或下拉选择刚添加的模型即可使用。

常见问题

现象	处理
401 / 连接失败	确认 Base URL 为 `https://api.gate.ai/openai/v1`，API Key 有效且账户有余额。
模型不可用	确认模型 ID 来自模型广场，格式为 `provider/model`，勿填 `auto`。
列表中找不到模型	确认已在 Settings 中保存；重启 Cursor 后再试。

Claude Code 接入

如果您已安装好 Claude Code（Anthropic 终端 / IDE 中的 AI 编程助手），请按照以下步骤接入 Gate.AI。

1. 创建 Gate.AI API 密钥

进入 控制台 → 设置 → API 密钥，创建密钥。
复制以 sk-or-v1- 开头的密钥，后续替换下文占位符。
若需 自动路由：控制台 → 设置 → 路由 → 打开「自动路由」。关闭时需在请求中显式指定模型 ID。

2. 配置 Anthropic Base URL 与 API Key

Claude Code 会读取环境变量；推荐与官方 LLM gateway 说明一致，设置：

变量	值
`ANTHROPIC_BASE_URL`	`https://api.gate.ai/anthropic`
`ANTHROPIC_API_KEY`	您的 Gate.AI API 密钥（`sk-or-v1-…`）

方式 A：当前终端会话（临时）

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"
claude

方式 B：写入 Shell 配置文件

将以下内容追加到 ~/.zshrc 或 ~/.bashrc：

export ANTHROPIC_BASE_URL="https://api.gate.ai/anthropic"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

执行 source ~/.zshrc（或重新打开终端）后，再运行 claude。

方式 C：Claude Code `settings.json`（推荐）

在用户级或项目级配置中写入 env（路径见 Claude Code settings），例如 项目目录下 .claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gate.ai/anthropic",
    "ANTHROPIC_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxx"
  }
}

安全提示：不要将真实密钥提交到公共仓库；可使用各操作系统的密钥管理或 CI 密钥注入，本地仅用环境变量。

恢复直连 Anthropic 官方

若需临时绕过网关：

env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY claude

（需已配置 Anthropic 官方账号或其它默认凭据。）

3. 配置模型（Gate.AI 模型 ID）

Gate.AI 文档中的模型 ID 形如 provider/model-name（如 anthropic/claude-sonnet-4.6），与 Claude Code 内置别名（如 sonnet）不完全相同。任选其一：

3.1 使用环境变量指定默认模型

export ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"

或在 settings.json 的 env 中增加同名键。

3.2 使用别名映射

将别名映射到 Gate.AI 的模型 ID（示例为 Sonnet）：

export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5"

具体 ID 以 Gate.AI 文档 - 模型 列表为准。

3.3 在 `/model` 中选自定义项

若需在界面中选择网关侧模型，可使用 Claude Code 的自定义模型项（见官方 Model configuration - ANTHROPIC_CUSTOM_MODEL_OPTION）：

export ANTHROPIC_CUSTOM_MODEL_OPTION="anthropic/claude-sonnet-4.6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet（Gate.AI）"

3.4 自动路由模型 `auto`

若在控制台已开启自动路由，可尝试将 ANTHROPIC_MODEL 设为 auto（与 OpenAI 接入页的 auto 语义一致）。若遇报错，请改回显式模型 ID（如 anthropic/claude-sonnet-4.6）。

4. 验证接入是否成功

在已配置环境的终端执行：

claude

进入会话后输入简单指令，例如：请用一句话介绍你自己。
若返回正常回复且无鉴权/路由错误，即表示请求已到达 Gate.AI 并由所选模型响应。

5. 常见问题

现象	可能原因	处理建议
401 / 鉴权失败	API Key 错误或未导出	检查 `ANTHROPIC_API_KEY`，与控制台密钥一致
404 on URL	Base URL 误用 OpenAI 路径	使用 `https://api.gate.ai/anthropic`
模型不存在 / 路由错误	模型 ID 格式错误或控制台未允许该模型	对照文档「模型」表；检查控制台路由与允许列表
仍走官方 Anthropic	环境变量未生效	确认 `settings.json` 位置层级；或在新 shell 中 `echo $ANTHROPIC_BASE_URL` 验证

Claude Desktop 接入

前置条件

Claude Desktop 已安装
Gate.AI API Key

Step 1：开启开发者模式

启动 Claude Desktop，无需登录 Anthropic 账号。
菜单栏点击 Help → Troubleshooting → Enable Developer Mode。

Claude Desktop 中 Enable Developer Mode 菜单项截图 — 参考：在 Help → Troubleshooting 中开启 Developer Mode。

开启后菜单栏出现 Developer 菜单。

Claude Desktop 中 Developer 菜单截图 — 参考：开启开发者模式后出现 Developer 菜单。

Step 2：打开第三方推理配置

菜单栏点击 Developer → Configure Third-Party Inference…

Claude Desktop 中 Configure Third-Party Inference 菜单项截图 — 参考：从 Developer 菜单打开 Configure Third-Party Inference。

Step 3：填写 Gate.AI 凭据和模型

选择 Gateway 和 Static API key，填写 Gate.AI 凭据。
完成后可点击 Test connection 测试连接。

Claude Desktop 中 Gateway 和 Static API key 配置截图 — 参考：填写 Gateway 与 Static API key 配置。

打开 Model discovery 开关。
完成后可再次点击 Test connection 测试。

Claude Desktop 中 Model discovery 开关截图 — 参考：开启 Model discovery 开关。

点击 Apply Changes 保存。

Step 4：重启并启动

完全退出 Claude Desktop（退出进程，不是关窗口），重新打开。
启动页选择 Continue with Gateway，无需 Anthropic 账号。

Step 5：验证

模型选择器显示可用模型即连接成功。

常见问题

现象	处理
连接失败 / 401	确认 Base URL 为 `https://api.gate.ai/anthropic/`，Auth scheme 选择 x-api-key，API key 有效。
没有出现「Continue with Gateway」	确认已点 Apply Changes 且完全退出重启。
没有模型显示	确认 Gate.AI 账户有余额；检查 Model discovery 开关已开启。

Hermes 接入

前置条件

已在 Gate.AI 控制台创建 API 密钥。
若使用自动路由，请在控制台设置 → 路由中开启自动路由。

方式一：终端配置

1. 选择模型与自定义端点

在终端执行：

hermes model

在菜单中选择 Custom endpoint，按提示填写：

项	值
API base URL	https://api.gate.ai/openai/v1
API key	你的 Gate.AI API 密钥
Model	auto（推荐自动路由），或控制台列出的完整模型 ID（如 deepseek/deepseek-v3.2）

若询问 context length（上下文长度），直接回车留空即可（由 Hermes 自动探测）。

2.（可选）本地 Web 管理界面

若希望通过浏览器编辑配置，可运行：

hermes dashboard

3. 验证

hermes chat "Hello"

成功则说明请求已到达 Gate.AI，并由智能路由或你指定的模型返回结果。

也可运行 hermes doctor 验证是否连接成功。

方式二：直接编辑配置文件

1. 文件位置

macOS / Linux

~/.hermes/config.yaml，主配置（模型、provider、base_url、api_key 等）
~/.hermes/.env，密钥与敏感环境变量（推荐）

Windows

C:\Users\<用户名>\.hermes\config.yaml
C:\Users\<用户名>\.hermes\.env

2. 在 `.env` 中保存密钥（任选其一）

写法 A（与 Gate.AI 命名一致）

# Gate.AI API 密钥
GATEAI_API_KEY=sk-or-v1_xxxxxxxxxxxxxxxxxxxxx

写法 B（与 Hermes 自定义端点常见约定一致）

Hermes 对自定义端点在未单独配置 model.api_key 时，会回退使用 OPENAI_API_KEY。可将 Gate.AI 密钥写入：

OPENAI_API_KEY=sk-or-v1_xxxxxxxxxxxxxxxxxxxxx

3. 在 `config.yaml` 中配置 `model`

自动路由（auto）

model:
  default: auto
  provider: custom
  base_url: https://api.gate.ai/openai/v1
  api_key: ${GATEAI_API_KEY}

若使用写法 B，可将 api_key 留空或删除该字段，让 Hermes 使用 OPENAI_API_KEY。

Hermes 会在加载配置时展开 ${VAR}（变量须已在环境中存在，通常由 ~/.hermes/.env 注入）。

固定模型示例

模型 ID 须与 Gate.AI 模型列表一致）：

model:
  default: deepseek/deepseek-v3.2
  provider: custom
  base_url: https://api.gate.ai/openai/v1
  api_key: ${GATEAI_API_KEY}

4. 保存后验证

保存后用 hermes chat "Hello" 测试 Gate.AI 连接来验证。

多线路 / 多模型

若同一 Gate.AI 密钥下需要多条逻辑线路（例如一条用 auto、一条固定 deepseek/deepseek-v3.2），可在 config.yaml 中配置 custom_providers（名称仅允许字母、数字、连字符等；建议用连字符，例如 gateai-auto）：

model:
  default: auto
  provider: custom
  base_url: https://api.gate.ai/openai/v1
  api_key: ${GATEAI_API_KEY}

custom_providers:
  - name: gateai-auto
    base_url: https://api.gate.ai/openai/v1
    api_key: ${GATEAI_API_KEY}
    model: auto

  - name: gateai-deepseek
    base_url: https://api.gate.ai/openai/v1
    api_key: ${GATEAI_API_KEY}
    model: deepseek/deepseek-v3.2

切换方式

终端：再次运行 hermes model，在菜单中选择对应命名线路或 Custom endpoint。
对话中（TUI）：使用 Hermes 官方文档中的 /model 语法，例如：

/model custom:gateai-auto:auto
/model custom:gateai-deepseek:deepseek/deepseek-v3.2

（具体名称以在 custom_providers[].name 中填写为准；三段为 custom:<配置名>:<模型 id>。）

常见问题

仅部分模型成功

请确认 model.provider 为 custom，且 Base URL 为 https://api.gate.ai/openai/v1。若 OpenAI 系可用、其它不可用，请检查模型 ID 与路由开关。

401 / invalid api key

检查密钥是否粘贴正确、是否过期；.env 修改后需重新启动正在运行的 hermes / hermes gateway 进程后再试。

找不到模型或空回复

模型 ID 是否与控制台一致（如 deepseek/deepseek-v3.2）。
自动路由是否在 Gate.AI 控制台开启。
运行 hermes doctor 查看配置与连通性。

QClaw 接入

如果您已安装好 QClaw，请按照以下步骤接入 Gate.AI。

对话式完成配置

1. 在对话中输入以下内容，请将 apiKey 替换为您的 Gate.AI API 密钥：

帮我新增一个provider
名称：Gate.AI
apiKey: sk-or-v1-xxxxxxxxxxxxxxxx
baseUrl: https://api.gate.ai/openai/v1
模型：auto

QClaw 会自动添加成功并重启生效。

2. 验证是否成功

直接输入：「帮我验证一下 Gate.AI 配置有没有生效」。对话会返回「Gate.AI provider 已成功添加！」（以实际界面为准。）

3. 切换到 Gate.AI 使用

直接输入：「切换到 Gate.AI 下面的 auto」。对话会返回「已切换成功！」（以实际界面为准。）

AutoClaw 接入

1. 配置入口

点击左下角偏好设置，选择模型与 API，点击添加自定义模型。

2. 添加模型

服务商选择自定义。
添加 Gate.AI 支持的模型 ID，例如 deepseek/deepseek-v3.2。
填写显示名称，例如：Gate.AI(deepseek-v3.2)。
填写 API Key，例如：sk-or-v1-xxxxxxxxxxxxxxxx。
填写 Base URL：https://api.gate.ai/openai/v1

3. 测试配置是否成功

点击连通测试，显示「测试成功」字样，则表示配置成功。

4. 模型使用

点击添加按钮，保存成功后，返回应用。
在聊天框下方选择切换模型，选择配置的 Gate.AI(deepseek-v3.2)，即可使用。

API 参考

通用对话 API 参考

字段	值
Base URL	https://api.gate.ai/openai/v1
认证	Authorization: Bearer <API_KEY>
格式	OpenAI 兼容
计费	按量计费

注意： API 路径是 /openai/v1（不是 /v1）。

端点

方法	路径	描述
POST	/chat/completions	聊天补全（支持流式）
GET	/models	获取可用模型列表

Seedance 视频生成 API 参考

字段	值
Base URL	https://api.gate.ai
认证	Authorization: Bearer <API_KEY>

提交视频生成任务

POST/api/v1/videos

提交异步视频生成任务，成功返回 202 及 job_id 供后续轮询状态。建议传入 Idempotency-Key 以防重复创建。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式
Idempotency-Key	header	string	否	幂等键，相同 key 重复提交时返回首次创建的任务，不会重复创建

请求体

名称	类型	必选	说明
model	string	是	模型 ID，当前使用 bytedance/seedance-2.0
prompt	string	是	视频描述，建议包含主体、动作、场景、镜头和风格。不同模型上限不同：Sora 500 字，Hailuo 2000 字，Wan T2V 1500 字、I2V 800 字。Gate.AI 本身不设硬性上限，超出后由上游拒绝并透传 502 / 503。
duration	integer	否	视频时长（秒），支持 4–15
resolution	string	否	输出分辨率：480p、720p 或 1080p
aspect_ratio	string	否	宽高比：16:9、4:3、1:1、3:4、9:16、21:9 或 adaptive
generate_audio	boolean	否	是否生成音频
seed	integer	否	随机种子，-1 到 4294967295；相同 seed 不保证完全一致
size	string	否	精确输出尺寸，如 1280x720
input_references	array	否	可选参考素材数组，用于图生视频、首尾帧驱动、视频风格迁移或音频驱动生成
input_references[].type	string	是	参考素材类型：image、video 或 audio，必须与 role 匹配
input_references[].url	string	是	参考素材的 HTTPS 地址
input_references[].role	string	是	参考素材用途：first_frame、last_frame、reference_video 或 reference_audio。first_frame/last_frame 各最多 1 个；last_frame 出现时必须同时提供 first_frame
metadata	object	否	业务透传字段，用于审计或来源标记
webhook_url	string	否	任务完成或失败后的回调地址

示例

{
  "model": "bytedance/seedance-2.0",
  "prompt": "A golden retriever running on a sunny beach, cinematic camera movement",
  "duration": 6,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": false,
  "seed": -1,
  "input_references": [
    {
      "type": "image",
      "url": "https://cdn.example.com/portrait.jpg",
      "role": "first_frame"
    }
  ],
  "metadata": {
    "source": "playground"
  },
  "webhook_url": "https://example.com/webhooks/gateai-video"
}

返回字段说明

名称	类型	说明
job_id	string	任务唯一 ID
status	string	任务状态：pending / in_progress / completed / failed
model	string	使用的模型
status_url	string	查询任务状态的完整 URL
message	string	服务端提示信息
current_balance	string	当前账户余额（USD）
estimated_cost	string	预估费用
pre_deduct_amount	string	预扣展示金额
balance_after_estimate	string	按预估费用计算后的余额
currency	string	货币类型，当前为 USD
billing_notice	string	计费提示

返回示例

{
  "code": 200,
  "msg": "",
  "data": {
    "job_id": "video_abc123",
    "status": "in_progress",
    "model": "bytedance/seedance-2.0",
    "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",
    "message": "视频任务已提交，请调用 status_url 查询生成进度。",
    "current_balance": "100.0000000000",
    "estimated_cost": "1.0800000000",
    "pre_deduct_amount": "1.0800000000",
    "balance_after_estimate": "98.9200000000",
    "currency": "USDT",
    "billing_notice": "视频生成完成后按实际任务结果扣款，提交后请保持余额充足。"
  }
}

返回结果

状态码	状态码含义	说明	数据模型
202	Accepted	任务已提交并排队，响应中包含用于轮询的 job_id。	VideoSubmitResponse
400	Bad Request	参数错误	ErrorResponse
401	Unauthorized	未登录或 Token 无效	ErrorResponse
402	Payment Required	余额不足，响应中包含预估费用与当前余额。	ErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse

查询任务状态

GET/api/v1/videos/{job_id}

轮询任务状态、进度及计费信息。任务完成后响应中包含 download_url。

请求参数

名称	位置	类型	必选	说明
job_id	path	string	是	视频任务 ID
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>

返回字段说明

名称	类型	说明
job_id	string	任务唯一 ID
status	string	任务状态：pending / in_progress / completed / failed
model	string	使用的模型
status_url	string	查询任务状态的完整 URL
download_url	string	视频下载入口 URL（状态为 completed 后出现）
duration	integer	视频时长（秒）
resolution	string	输出分辨率
aspect_ratio	string	宽高比
generate_audio	boolean	是否包含音频
estimated_cost	string	预估费用
billed_cost	string	实际扣费金额
billing_status	string	计费状态：pre_deducted 或 settled
expires_at	string(ISO 8601)	视频文件过期时间
created_at	string(ISO 8601)	任务创建时间
completed_at	string(ISO 8601)	任务完成时间

返回示例

{
  "code": 200,
  "msg": "",
  "data": {
    "job_id": "video_abc123",
    "status": "completed",
    "model": "bytedance/seedance-2.0",
    "status_url": "https://api.gate.ai/api/v1/videos/video_abc123",
    "download_url": "https://api.gate.ai/api/v1/videos/video_abc123/content",
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": false,
    "estimated_cost": "1.0800000000",
    "billed_cost": "1.0800000000",
    "billing_status": "settled",
    "expires_at": "2026-06-26T05:00:00Z",
    "created_at": "2026-05-27T05:00:00Z",
    "completed_at": "2026-05-27T05:03:00Z"
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功	VideoStatusResponse
401	Unauthorized	未登录或 Token 无效	ErrorResponse
404	Not Found	任务不存在，或任务不属于当前 API Key。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse

下载视频

GET/api/v1/videos/{job_id}/content

鉴权通过后 302 跳转至临时视频下载地址。

请求参数

名称	位置	类型	必选	说明
job_id	path	string	是	视频任务 ID
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>

返回示例

HTTP/1.1 302 Found
Location: https://cdn.example.com/videos/video_abc123.mp4?expires=1780000000

返回结果

状态码	状态码含义	说明	数据模型
302	Found	跳转至临时视频下载地址。
401	Unauthorized	未登录或 Token 无效	ErrorResponse
404	Not Found	任务不存在，或任务不属于当前 API Key。	ErrorResponse
409	Conflict	任务尚未完成，视频暂不可下载。	ErrorResponse
410	Gone	视频内容已过期，无法下载。	ErrorResponse
500	Internal Server Error	服务内部错误	ErrorResponse

参考图生成图像 API 参考

通过 Gate.AI 图生图接口上传参考图生成或编辑图片。该接口使用 multipart/form-data，同步返回图片 URL 与计费信息，usage.input_tokens 会包含参考图读取计入的 image_tokens。

字段	值
Base URL	https://api.gate.ai/openai/v1
认证	Authorization: Bearer <API_KEY>
格式	OpenAI 兼容；使用 multipart/form-data 请求体

注意： 图像接口路径位于 /openai/v1 下；生成结果 data[].url 为短时 S3 预签名地址，请尽快下载或转存，落盘对象 TTL 30 天。

基于参考图生成图像

POST/images/edits

通过 multipart/form-data 上传参考图并同步生成或编辑图片，usage.input_tokens 会包含参考图读取计入的 image_tokens。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：multipart/form-data

请求体

名称	类型	必选	说明
model	string	是	图像模型 ID，如 gpt-image-1、qwen-image-2.0-pro、seedream-4.0；缺失返回 400 model is required
image	file	是	参考图文件。gpt-image-1 要求 PNG、小于 4 MB、方形；无 mask 时须带透明通道作蒙版
mask	file	否	PNG 蒙版，透明区为编辑区域，尺寸需与 image 一致
prompt	string	是	编辑描述，最长 1000 字符
n	integer	否	生成张数，1–10，默认 1；多图按张计费
size	string	否	输出尺寸。gpt-image-1 支持 256x256、512x512 或 1024x1024，并参与费用预估
response_format	string	否	url 或 b64_json。gpt-image-1 不支持该参数，传入可能被上游拒绝

示例

model=gpt-image-1
prompt=Add a yellow border and a small sun in the corner
size=1024x1024
image=@./input.png

返回字段说明

名称	类型	说明
created	integer	生成时间戳（秒）
data	array	结果数组，长度等于 n
data[].url	string	图片 S3 预签名 URL，短时有效，落盘 30 天
usage	object	用量。OpenAI 系为 token 明细；Qwen 系为 width、height、image_count
model_extend.cost	string	实际计费金额（USD），扣款以此为准
model_extend.line_items	array	计费分项。token 计费含 input/output/cache；按张计费含 billing_unit、rate_usd_per_image、resolution_tier
model_extend.provider	string	实际上游 provider，如 openai、qwen
size / quality / output_format / background	string	部分模型回显的入参
model	string	仅 Qwen 系在顶层回显

返回示例

{
  "created": 1781604390,
  "data": [
    {
      "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-edit-0.png?X-Amz-Expires=600&X-Amz-Signature=..."
    }
  ],
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png",
  "usage": {
    "input_tokens": 220,
    "input_tokens_details": {
      "image_tokens": 194,
      "text_tokens": 26
    },
    "output_tokens": 272,
    "total_tokens": 492
  },
  "model_extend": {
    "cost": "0.009804",
    "provider": "openai",
    "total_tokens": "492"
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功，同步返回图片结果与计费信息。	ImageResponse
400	Bad Request	请求体错误、JSON 无效，或 model / prompt 缺失。	OpenAIErrorResponse
401	Unauthorized	API Key 无效或缺失。	OpenAIErrorResponse
402	Payment Required	余额不足，响应中包含当前余额与预估费用。	InsufficientBalanceResponse
404	Not Found	模型不存在，或图像端点未启用。	OpenAIErrorResponse
413	Payload Too Large	请求体过大，默认上限 8 MiB。	OpenAIErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	OpenAIErrorResponse
500	Internal Server Error	服务内部错误。	OpenAIErrorResponse
502	Bad Gateway	上游图像服务失败。	OpenAIErrorResponse

文本生成图像 API 参考

通过 Gate.AI 文生图接口调用 OpenAI、Qwen、Seedream 等供应商的图像模型。该接口使用 JSON 请求体，同步返回图片 URL 与计费信息，无需 job_id 轮询或 Webhook。

字段	值
Base URL	https://api.gate.ai/openai/v1
认证	Authorization: Bearer <API_KEY>
格式	OpenAI 兼容；使用 JSON 请求体

注意： 图像接口路径位于 /openai/v1 下；生成结果 data[].url 为短时 S3 预签名地址，请尽快下载或转存，落盘对象 TTL 30 天。

文本生成图像

POST/images/generations

根据文本 prompt 同步生成图片，成功后返回 OpenAI 兼容的图像结果，data[].url 为生成图片地址。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：application/json

请求体

名称	类型	必选	说明
model	string	是	图像模型 ID，如 gpt-image-1、qwen-image-2.0-pro、seedream-4.0；缺失返回 400 model is required
prompt	string	是	图像文本描述。gpt-image-1 上限 32000 字符
n	integer	否	生成张数，1–10，默认 1；多图按张计费
size	string	否	输出尺寸。gpt-image-1 支持 1024x1024、1536x1024、1024x1536 或 auto，并参与费用预估
response_format	string	否	url 或 b64_json。gpt-image-1 不支持该参数，传入可能被上游拒绝
stream	boolean	否	透传字段；当前图像为同步链路，不据其分流

示例

{
  "model": "gpt-image-1",
  "prompt": "A golden retriever running on a sunny beach, cinematic",
  "n": 1,
  "size": "1024x1024"
}

返回字段说明

名称	类型	说明
created	integer	生成时间戳（秒）
data	array	结果数组，长度等于 n
data[].url	string	图片 S3 预签名 URL，短时有效，落盘 30 天
usage	object	用量。OpenAI 系为 token 明细；Qwen 系为 width、height、image_count
model_extend.cost	string	实际计费金额（USD），扣款以此为准
model_extend.line_items	array	计费分项。token 计费含 input/output/cache；按张计费含 billing_unit、rate_usd_per_image、resolution_tier
model_extend.provider	string	实际上游 provider，如 openai、qwen
size / quality / output_format / background	string	部分模型回显的入参
model	string	仅 Qwen 系在顶层回显

返回示例

{
  "created": 1781604363,
  "data": [
    {
      "url": "https://ai-gateway-file.s3.ap-northeast-1.amazonaws.com/multimodal/image/2026/06/16/example-0.png?X-Amz-Expires=600&X-Amz-Signature=..."
    }
  ],
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png",
  "background": "opaque",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 196,
    "total_tokens": 206,
    "output_tokens_details": {
      "image_tokens": 196,
      "text_tokens": 0
    }
  },
  "model_extend": {
    "cost": "0.006322",
    "provider": "openai",
    "total_tokens": "206",
    "line_items": [
      {
        "kind": "uncached_input",
        "tokens": 10,
        "rate_usd_per_million": "5.0000000000",
        "amount_usd": "0.0000500000"
      },
      {
        "kind": "output",
        "tokens": 196,
        "rate_usd_per_million": "32.0000000000",
        "amount_usd": "0.0062720000"
      }
    ]
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功，同步返回图片结果与计费信息。	ImageResponse
400	Bad Request	请求体错误、JSON 无效，或 model / prompt 缺失。	OpenAIErrorResponse
401	Unauthorized	API Key 无效或缺失。	OpenAIErrorResponse
402	Payment Required	余额不足，响应中包含当前余额与预估费用。	InsufficientBalanceResponse
404	Not Found	模型不存在，或图像端点未启用。	OpenAIErrorResponse
413	Payload Too Large	请求体过大，默认上限 8 MiB。	OpenAIErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	OpenAIErrorResponse
500	Internal Server Error	服务内部错误。	OpenAIErrorResponse
502	Bad Gateway	上游图像服务失败。	OpenAIErrorResponse

语音转文本 API 参考

通过 Gate.AI 语音转文本接口上传音频文件，同步返回 OpenAI 兼容的转写结果。设置 stream=true 时，网关会以 text/event-stream 透传上游 SSE，末帧携带 usage 与 model_extend。

字段	值
Base URL	https://api.gate.ai/openai/v1
认证	Authorization: Bearer <API_KEY>
格式	OpenAI 兼容；使用 multipart/form-data 上传音频文件

注意： 语音接口路径位于 /openai/v1 下；语音转文本与文本转语音为同步能力，不返回 job_id，也不需要轮询。TTS 默认二进制响应中的计费信息记录在控制台 Generations。

语音转文本

POST/audio/transcriptions

上传待转写音频文件，同步返回文本、usage 与 model_extend.cost。gpt-4o-transcribe / gpt-4o-mini-transcribe 按 token 计费；whisper-1 通常按音频时长计费。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：multipart/form-data

请求体

名称	类型	必选	说明
model	string	是	语音转文本模型 ID，如 whisper-1、gpt-4o-transcribe、gpt-4o-mini-transcribe；以平台实际上架为准
file	file	是	待转写音频文件，如 mp3、wav、m4a 等格式
language	string	否	可选语言提示，如 zh，用于提升转写准确性
stream	boolean	否	设为 true 时返回 text/event-stream 流式转写事件；末帧 transcript.text.done 携带 usage 与 model_extend

示例

model=gpt-4o-transcribe
language=zh
file=@./input.mp3

返回字段说明

名称	类型	说明
text	string	转写文本
usage	object	语音转文本用量。不同模型可能返回 token 或音频时长形态
usage.input_token_details.audio_tokens	integer	音频输入 token 数，适用于 token 计费的转写模型
model_extend.cost	string	实际计费金额（USD），扣款以 model_extend.cost 为准
model_extend.provider	string	实际上游 provider，如 openai
model_extend.line_items	array	计费分项，如 input_audio、output 或按时长计费项目

返回示例

{
  "text": "今天天气很好，我们一起去海边散步吧。",
  "usage": {
    "type": "tokens",
    "input_tokens": 14,
    "input_token_details": {
      "text_tokens": 0,
      "audio_tokens": 14
    },
    "output_tokens": 18,
    "total_tokens": 32
  },
  "model_extend": {
    "cost": "0.000180",
    "provider": "openai",
    "total_tokens": "32",
    "line_items": [
      {
        "kind": "input_audio",
        "tokens": 14,
        "rate_usd_per_million": "6.0000000000",
        "amount_usd": "0.0000840000"
      },
      {
        "kind": "output",
        "tokens": 18,
        "rate_usd_per_million": "10.0000000000",
        "amount_usd": "0.0001800000"
      }
    ]
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功，同步返回转写结果、音频数据或 SSE 事件。	AudioResponse
400	Bad Request	请求参数错误、请求体格式错误，或缺少 model / file / input 等必填字段。	OpenAIErrorResponse
401	Unauthorized	API Key 无效或缺失。	OpenAIErrorResponse
402	Payment Required	余额不足。	InsufficientBalanceResponse
404	Not Found	模型不存在，或语音端点未启用。	OpenAIErrorResponse
413	Payload Too Large	上传文件或请求体过大。	OpenAIErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	OpenAIErrorResponse
500	Internal Server Error	服务内部错误。	OpenAIErrorResponse
502	Bad Gateway	上游语音服务失败。	OpenAIErrorResponse

文本转语音 API 参考

通过 Gate.AI 文本转语音接口提交文本并同步生成音频。默认返回二进制音频；设置 stream_format=sse 时会逐帧返回 speech.audio.delta，并在 speech.audio.done 末帧携带 usage 与 model_extend。

字段	值
Base URL	https://api.gate.ai/openai/v1
认证	Authorization: Bearer <API_KEY>
格式	OpenAI 兼容；使用 JSON 请求体，默认返回二进制音频，可通过 SSE 流式返回音频分片

文本转语音

POST/audio/speech

提交待合成文本并同步返回音频。默认响应体为二进制音频流，Content-Type 随 response_format 变化；SSE 模式会返回 base64 音频分片与末帧计费信息。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：application/json

请求体

名称	类型	必选	说明
model	string	是	文本转语音模型 ID，当前仅支持 gpt-4o-mini-tts
input	string	是	待合成文本
voice	string	是	发音人，如 alloy
response_format	string	否	输出音频格式，如 wav、mp3；默认 wav
stream_format	string	否	设为 sse 时返回 text/event-stream；speech.audio.delta 帧包含 base64 音频分片，speech.audio.done 帧包含 usage 与 model_extend

示例

{
  "model": "gpt-4o-mini-tts",
  "input": "今天天气很好，我们一起去海边散步吧。",
  "voice": "alloy",
  "response_format": "mp3"
}

返回字段说明

名称	类型	说明
audio bytes	binary	默认返回的音频二进制数据
speech.audio.delta	SSE event	SSE 音频分片事件，携带 base64 编码的音频片段
speech.audio.done	SSE event	SSE 结束事件，携带 usage 与 model_extend
usage	object	文本转语音用量；二进制响应场景下由网关写入后台记录，SSE 末帧返回
model_extend.cost	string	实际计费金额（USD），扣款以 model_extend.cost 为准

返回示例

HTTP/1.1 200 OK
Content-Type: audio/mpeg

(binary audio bytes)

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功，同步返回转写结果、音频数据或 SSE 事件。	AudioResponse
400	Bad Request	请求参数错误、请求体格式错误，或缺少 model / file / input 等必填字段。	OpenAIErrorResponse
401	Unauthorized	API Key 无效或缺失。	OpenAIErrorResponse
402	Payment Required	余额不足。	InsufficientBalanceResponse
404	Not Found	模型不存在，或语音端点未启用。	OpenAIErrorResponse
413	Payload Too Large	上传文件或请求体过大。	OpenAIErrorResponse
429	Too Many Requests	请求过于频繁，请降低调用频率。	OpenAIErrorResponse
500	Internal Server Error	服务内部错误。	OpenAIErrorResponse
502	Bad Gateway	上游语音服务失败。	OpenAIErrorResponse

Gemini 原生协议 API 参考

通过 Gate.AI Gemini 原生协议调用 Gemini 模型。适合已经使用 Gemini contents[]、parts[]、tools[] 请求结构的应用。

字段	值
Base URL	https://api.gate.ai/gemini/v1beta
认证	Authorization: Bearer <API_KEY>
格式	Gemini 原生 JSON 请求体
文本生成	POST /models/{model}:generateContent
流式生成	POST /models/{model}:streamGenerateContent?alt=sse

注意： Gate.AI 使用自己的 API Key，不使用 Google Gemini 的 ?key= 参数。

Gemini 原生协议通过 URL path 中的 {model} 指定模型，例如 POST /models/gemini-2.5-pro:generateContent。请求 body 无需再次传入 model。这与 OpenAI Chat Completions 在请求 body 中传入 model 的方式不同。

Base URL 等效路径

场景	Base URL
Gate.AI 显式指定 Gemini 协议（推荐）	https://api.gate.ai/gemini/v1beta
Google AI Studio SDK 直接接入（去掉 /gemini 前缀）	https://api.gate.ai/v1beta
Vertex AI 风格路径（带前缀）	https://api.gate.ai/gemini/v1/publishers/google/models/{model}:{action}
Vertex AI 风格路径（去前缀）	https://api.gate.ai/v1/publishers/google/models/{model}:{action}

文本生成

POST/models/{model}:generateContent

根据 Gemini 原生 contents[] 请求体生成模型回复。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：application/json
model	path	string	是	Gemini 模型 ID，如 gemini-2.5-pro

请求体

名称	类型	必选	说明
contents	array	是	Gemini 对话内容，按轮次顺序排列
contents[].role	string	否	user 或 model
contents[].parts	array	是	一轮消息中的内容片段
parts[].text	string	否	文本输入
parts[].inlineData	object	否	多模态输入，包含 mimeType 和 base64 data
tools	array	否	工具声明，使用 Gemini functionDeclarations 格式
toolConfig	object	否	工具调用策略
generationConfig	object	否	生成参数，如 temperature、maxOutputTokens
systemInstruction	object	否	系统指令

示例

export GATEAI_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxx"

curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \
  -H "Authorization: Bearer $GATEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "Introduce Gate.AI in one sentence"}
        ]
      }
    ]
  }'

返回字段说明

名称	类型	说明
candidates	array	模型候选回复
candidates[].index	integer	候选索引，从 0 开始
candidates[].content.role	string	固定为 model
candidates[].content.parts[].text	string	文本回复内容
candidates[].content.parts[].thought	boolean	是否为模型的思考内容（reasoning）
candidates[].content.parts[].thoughtSignature	string	思考内容签名，用于多轮 reasoning 上下文延续
candidates[].content.parts[].functionCall	object	工具调用请求
candidates[].finishReason	string	结束原因，如 STOP
usageMetadata	object	用量与计费信息
usageMetadata.promptTokenCount	integer	输入 token 数
usageMetadata.candidatesTokenCount	integer	输出 token 数
usageMetadata.totalTokenCount	integer	总 token 数
usageMetadata.cost	string	本次请求费用，单位 USD

返回示例

{
  "candidates": [
    {
      "index": 0,
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Gate.AI is a unified AI model routing platform."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 13,
    "candidatesTokenCount": 37,
    "totalTokenCount": 50,
    "cost": "0.0000964"
  }
}

流式生成

POST/models/{model}:streamGenerateContent?alt=sse

流式返回 Gemini 响应片段。最后一段通常包含 usageMetadata。客户端按 Gemini 流式协议读取 candidates[].content.parts[].text 即可。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	Gate.AI API Key。格式：Bearer <API_KEY>
Content-Type	header	string	是	请求体格式：application/json
model	path	string	是	Gemini 模型 ID，如 gemini-2.5-pro

请求体

名称	类型	必选	说明
contents	array	是	Gemini 对话内容，按轮次顺序排列
contents[].role	string	否	user 或 model
contents[].parts	array	是	一轮消息中的内容片段
parts[].text	string	否	文本输入
parts[].inlineData	object	否	多模态输入，包含 mimeType 和 base64 data
tools	array	否	工具声明，使用 Gemini functionDeclarations 格式
toolConfig	object	否	工具调用策略
generationConfig	object	否	生成参数，如 temperature、maxOutputTokens
systemInstruction	object	否	系统指令

示例

curl -N "https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer $GATEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "List three scenarios where model routing is useful"}
        ]
      }
    ]
  }'

多模态输入

图片、音频、视频、PDF 等内容放入同一个 parts[]。Gate.AI Gemini 入口建议使用 camelCase 字段：inlineData.mimeType。

类型	`mimeType` 示例
图片	`image/png`、`image/jpeg`
音频	`audio/mp3`、`audio/wav`
视频	`video/mp4`
PDF	`application/pdf`

图片输入示例

IMAGE_B64="$(base64 -i ./image.png | tr -d '\n')"

curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \
  -H "Authorization: Bearer $GATEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [
      {
        \"role\": \"user\",
        \"parts\": [
          {\"text\": \"描述这张图片\"},
          {
            \"inlineData\": {
              \"mimeType\": \"image/png\",
              \"data\": \"${IMAGE_B64}\"
            }
          }
        ]
      }
    ]
  }"

工具调用

Gemini 工具使用 tools[].functionDeclarations[]。工具策略放在 toolConfig.functionCallingConfig。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "北京今天适合穿什么?"}
      ]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "查询城市天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名"
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ],
  "toolConfig": {
    "functionCallingConfig": {
      "mode": "AUTO"
    }
  }
}

模型触发工具时，会在 candidates[].content.parts[] 返回 functionCall。

常见问题

现象	原因	处理建议
404	路径缺少 /gemini/v1beta 或模型 ID 错误	使用 https://api.gate.ai/gemini/v1beta/models/{model}:generateContent
多模态内容读不到	inlineData 字段名、MIME 或 base64 不正确	使用 inlineData.mimeType/data，确认 base64 不带换行
工具没有触发	schema 超出 Gemini 支持的 JSON Schema 子集	先使用 type、properties、required、description 等基础字段

状态码

状态码	状态码含义	说明
200	OK	请求成功
400	Bad Request	请求体错误、JSON 无效，或缺少必要的 contents / parts
401	Unauthorized	API Key 无效或缺失
402	Payment Required	余额不足
404	Not Found	API 路径错误、模型不存在，或模型未启用该协议
413	Payload Too Large	多模态请求体过大
429	Too Many Requests	请求过于频繁，请降低调用频率
500	Internal Server Error	服务内部错误
502	Bad Gateway	上游 Gemini 服务失败

和 OpenAI 兼容接入的区别

如果应用已经使用 OpenAI Chat Completions，可以继续通过 https://api.gate.ai/openai/v1/chat/completions 调用 Gemini 模型。如果应用已经使用 Gemini 原生 contents[] / parts[] 格式，使用本页的 /gemini/v1beta/models/... 端点，迁移成本更低。

模型列表与定价 API 参考

通过 Gate.AI 模型列表接口获取平台全部可用模型的清单、基本信息与刊例价。适合模型选型、比价工具与程序化选型的 agent 使用；单次请求返回全量模型，无需分页。

字段	值
Base URL	https://gate.ai
认证	无需认证
格式	Gate.AI REST JSON

获取模型列表

GET/api/v1/models

返回平台全部上架模型（目前 150+），包含显示名称、模型厂商、输入/输出模态、上下文长度与完整刊例价。

请求参数

名称	位置	类型	必选	说明
lang	query	string	否	响应文字语言：en（默认）、zh（简体中文）、zh-tw（繁体中文），影响 description 与 tags[].name。值区分大小写，无效值回退到英文。
context_length	query	string	否	按上下文长度过滤。支持多选，多个值以逗号分隔，例如 128000,64000。传入 0、空字符串或不传时表示不限。
input_modality	query	string	否	按输入模态过滤。可选值包含 text、image、video；支持多选，多个值以逗号分隔，例如 text,image。
keyword	query	string	否	按模型名称模糊搜索，匹配 model 或 base_info.name，不区分大小写。
max_input_price	query	number	否	输入价格上限。传入 0 或不传时表示不限。
max_output_price	query	number	否	输出价格上限。传入 0 或不传时表示不限。
min_input_price	query	number	否	输入价格下限。不传时默认为 0，并使用左开区间，即不包含价格为 0 的模型。
min_output_price	query	number	否	输出价格下限。不传时默认为 0，并使用左开区间，即不包含价格为 0 的模型。
output_modality	query	string	否	按输出模态过滤。可选值包含 text、image、video；支持多选，多个值以逗号分隔，例如 text,image。
provider_name	query	string	否	按用户可见的厂商名称过滤。匹配时忽略大小写及首尾空格。

示例

curl "https://gate.ai/api/v1/models?lang=zh-tw"

返回字段说明

名称	类型	说明
code	integer	业务状态码，成功固定为 200。
message	string	状态描述，成功为 success。
data.data	array	模型数组，每个元素为一个模型对象。
timestamp	integer	服务器时间戳（毫秒）。
data.data[].model	string	模型 ID，即各生成接口 model 参数应传入的值。
data.data[].name	string	显示名称。
data.data[].provider_name	string	模型厂商名称，如 OpenAI、Anthropic、ByteDance。
data.data[].type	string	模型可用的接口形态，多值以 \| 分隔：completions、responses、messages、videos、generations、edits、transcriptions、speech。
data.data[].input_price	number \| null	输入单价，USD / 每百万 tokens。有 pricing_tiers 时等于第一档价格；非 token 计费模型为 null。
data.data[].output_price	number \| null	输出单价，USD / 每百万 tokens，语义同 input_price。
data.data[].cache_read_price	number \| null	缓存读取单价，USD / 每百万 tokens。
data.data[].cache_write_price	number \| null	缓存写入单价，USD / 每百万 tokens。
data.data[].context_length	integer	上下文长度（tokens）；不适用的模型为 0。
data.data[].description	string	模型简介，语言跟随 lang 参数。
data.data[].tags	array	能力标签，元素包含 key（固定英文标识）、name（跟随 lang 参数）、category。
data.data[].input_modalities	array	输入模态：text、image、video、audio。为平台维护的参考信息，个别模型可能滞后于上游更新。
data.data[].output_modalities	array	输出模态，值域同 input_modalities。
data.data[].pricing_tiers	object	仅阶梯计价模型出现。input、output、cache_read、cache_write 各为阶梯数组，元素包含 upper 与对应价格。
data.data[].video_capabilities	object	仅视频模型出现：durations（秒，枚举）、resolutions、aspect_ratios。
data.data[].video_pricing	object	仅视频模型出现的计价信息。
video_pricing.currency	string	币种，目前为 USD。
video_pricing.billing_mode	string	per_second_resolution（按输出秒数 × 分辨率档位）或 per_film（按条计价）。
video_pricing.unit	string	计费单位：second 或 film。
video_pricing.tiers	array	价格档位。按秒模式包含 resolution + price；按条模式包含 resolution + duration + price。价格为 string。
data.data[].image_pricing	object	仅图像模型出现的计价信息。
image_pricing.currency	string	币种，目前为 USD。
image_pricing.billing_mode	string	per_image（按张）或 token（按 tokens）。
image_pricing.unit	string	计费单位：image 或 1M。
image_pricing.per_image	string	按张计费时的每张单价。
image_pricing.text_input / image_input	object	token 计费时出现，各包含 input、output、cache_read（USD / 每百万 tokens，string）。
data.data[].tts_stt_pricing	object	仅语音模型出现的计价信息。
tts_stt_pricing.billing_mode	string	token（按 tokens）或 audio_duration（按音频时长）。
tts_stt_pricing.input_tokens / output_tokens / cache_read_tokens / cache_write_tokens	string	token 计费时出现，USD / 每百万 tokens。
tts_stt_pricing.input_per_minute	string	按时长计费时出现，输入音频每分钟单价（USD）。
data.data[].model_publish_time	string (ISO 8601)	模型发布时间。

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 224,
        "model": "qwen3-vl-plus",
        "name": "Qwen3 VL Plus",
        "icon": "https://gimg2.staticimgs.com/image/qwen_20260402_161657_e06ffb27e1219c85184d939bce7cd1bd.webp",
        "provider_type": "qwen",
        "provider_name": "Qwen",
        "type": "completions",
        "input_price": 0.144,
        "output_price": 1.434,
        "cache_read_price": 0.029,
        "cache_write_price": 0.539,
        "price_type": 0,
        "context_length": 262144,
        "description": "Qwen3-VL 系列的 Plus 主力视觉语言模型，支持图像、视频与文本联合输入，擅长文档图表解析、视频理解、空间定位与智能体工具调用，适合多模态问答与视觉自动化场景。",
        "overview": "",
        "tags": [
          {
            "id": 3,
            "key": "vision",
            "name": "视觉",
            "category": "general"
          },
          {
            "id": 28,
            "key": "ui-understanding",
            "name": "界面理解",
            "category": "general"
          },
          {
            "id": 30,
            "key": "document-ocr",
            "name": "文档识别",
            "category": "general"
          },
          {
            "id": 31,
            "key": "multimodal-understanding",
            "name": "多模态理解",
            "category": "general"
          }
        ],
        "input_modalities": [
          "text",
          "image",
          "video"
        ],
        "output_modalities": [
          "text"
        ],
        "playground_enabled": true,
        "model_publish_time": "2025-09-23T00:00:00Z",
        "create_time": "2026-06-05T14:18:56Z",
        "update_time": "2026-07-06T01:57:19Z",
        "pricing_tiers": {
          "input": [
            {
              "upper": 32000,
              "input_price": "0.144"
            },
            {
              "upper": 128000,
              "input_price": "0.216"
            },
            {
              "upper": null,
              "input_price": "0.431"
            }
          ],
          "output": [
            {
              "upper": 32000,
              "output_price": "1.434"
            },
            {
              "upper": 128000,
              "output_price": "2.151"
            },
            {
              "upper": null,
              "output_price": "4.301"
            }
          ],
          "cache_read": [
            {
              "upper": 32000,
              "cache_read_price": "0.029"
            },
            {
              "upper": 128000,
              "cache_read_price": "0.044"
            },
            {
              "upper": null,
              "cache_read_price": "0.087"
            }
          ],
          "cache_write": [
            {
              "upper": null,
              "cache_write_price": "0.539"
            }
          ]
        }
      }
    ]
  },
  "timestamp": "1784201129"
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功，返回全量模型列表。	ModelsResponse
500	Internal Server Error	服务器内部错误。	ErrorResponse

兼容性声明： 响应中未在本页列出的字段属于平台内部字段，可能随时调整，请勿依赖。本页列出的字段仅做向后兼容的新增，不做破坏性变更。

查询余额

查询当前 API Key 所属用户的余额状态。

字段	值
Base URL	https://api.gate.ai
认证	Authorization: Bearer <API_KEY>
格式	Gate.AI REST JSON

查询 Credits 余额

GET/api/v1/credits/balance

查询当前 API Key 所属用户的余额状态。

请求参数

名称	位置	类型	必选	说明
Authorization	header	string	是	API Key 鉴权，格式：Bearer <API_KEY>

返回字段说明

名称	类型	说明
code	integer	业务状态码。成功固定为 200。
data	object	余额数据。
data.status	integer	余额状态：1 可交易，2 余额不足，4 已欠费。
data.message	string	状态描述。
data.asset_type	string	资产归属类型：user_asset 个人资产，organization_asset 组织资产。
data.recharge_balance	string	充值余额。
data.debt_amount	string	欠费金额；无欠费时为空字符串或 0 值字符串。

返回示例

{
  "code": 200,
  "data": {
    "status": 1,
    "message": "可以交易",
    "asset_type": "user_asset",
    "recharge_balance": "12.34000000",
    "debt_amount": ""
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	查询成功，返回 code 和 data。	CreditsBalanceResponse
401	Unauthorized	API Key 缺失、无效、过期、撤销、禁用或未激活。	ErrorResponse
403	Forbidden	当前 API Key 所属成员无权限查看余额。	ErrorResponse
429	Too Many Requests	触发限流。	ErrorResponse
500	Internal Server Error	网关内部错误，例如 API Key 查询异常或响应序列化失败。	ErrorResponse
502	Bad Gateway	余额上游服务不可用、返回非成功状态、响应解析失败或数据为空。	ErrorResponse

错误返回示例

{
  "error": {
    "type": "authentication_error",
    "code": "7022002001",
    "message": "invalid api key"
  }
}

故障排除

认证类错误

错误信息	HTTP 状态码	原因	解决方案
`invalid api key`	401	API Key 无效、已过期、已撤销或已禁用	请进入控制台 → API Keys 页面，确认 Key 状态为"活跃"，如已过期请重新生成

路由与模型错误

错误信息	HTTP 状态码	原因	解决方案
`no model config found for: {model}`	404	请求的模型 ID 不存在	进入模型列表，确认模型 ID 拼写正确
`model field is required`	400	请求体中缺少 `model` 字段	在请求 JSON 中添加 `"model": "模型名称"`
`invalid or empty requested model`	400	请求的模型名称为空或非法	进入模型列表，确认使用正确的模型 ID 格式
`unknown api path`	404	API 路径错误	请确认 Base URL 为 `https://api.gate.ai/openai/v1` 或 `https://api.gate.ai/anthropic`

请求参数错误

错误信息	HTTP 状态码	原因	解决方案
`invalid JSON body`	400	请求体 JSON 格式不合法	检查请求体是否为合法的 JSON 格式
`failed to read request body`	400	请求体读取失败	确认请求体未损坏，Content-Type 设置为 `application/json`
`failed to rewrite request body`	500	请求体重写失败（网关内部）	请重试，若持续出现，请联系技术支持
`images are not supported by this model`	400	目标模型不支持图片输入	更换支持多模态（图片）的模型，如 `gpt-4o`
`audio is not supported by this model`	400	目标模型不支持音频输入	更换支持音频输入的模型
`unsupported parameter: max_tokens`	400	部分模型不支持 `max_tokens` 参数	改用 `max_completion_tokens` 参数

配额与限流错误

错误信息	HTTP 状态码	原因	解决方案
`api key budget quota exceeded`	429	API Key 预算额度已用尽	进入控制台 → API Keys → 预算设置，提高预算上限或等待配额重置
`guardrail budget limit exceeded`	429	护栏预算限制已超出	检查护栏配置中的预算限制，调高限额或降低使用频率
`organization guardrail budget limit exceeded`	429	组织级护栏预算已超出	联系组织管理员调整组织级预算限制
`model not allowed by guardrail policy`	403	模型不在护栏策略允许范围内	进入控制台 → 护栏设置，将目标模型添加到允许列表
`The free model usage has reached its daily global limit today.`	429	免费模型全局日限额已达上限	等待次日重置，或升级到付费计划使用无限制模型
`The free model usage has reached its daily limit today.`	429	个人免费模型日限额已达上限	等待次日重置，或升级到付费计划
`Guest daily spending limit exceeded. Please try again tomorrow or upgrade to a paid plan.`	429	游客身份日累计限额已超出	注册账号并升级到付费计划，或等待次日重置

计费与余额错误

错误信息	HTTP 状态码	原因	解决方案
`Pending payment {amount} USD — Please top up...`	402	账户余额不足且存在欠费	前往 Gate Pay 完成充值
`Insufficient balance and account in debt`	402	余额不足且账户处于欠费状态	前往 Gate Pay 完成充值
`billing model info not found for model "{model}"`	400	模型的计费信息不存在	确认模型 ID 正确，若为新模型，请联系技术支持配置计费规则
`billing model info is ambiguous for model "{model}"`	400	模型计费信息存在歧义（多条匹配）	请联系技术支持排查模型计费配置
`billing configuration error`	500	计费规则配置错误（服务端）	请联系技术支持修复计费配置

上游服务错误

错误信息	HTTP 状态码	原因	解决方案
`bad gateway`	502	网关与上游服务通信失败	请重试，若持续出现，请检查服务状态页或联系技术支持
`upstream service unavailable`	502	上游 AI Provider 不可用	稍后重试，或切换到其他可用模型
`upstream service error`	502	上游 AI Provider 返回错误	检查请求参数是否符合目标模型要求；若持续出现请联系技术支持
`request timeout`	504	请求上游超时	减少输入长度或增加超时时间后重试
`no provider handler configured for protocol`	502	网关未配置对应的协议处理器	请联系技术支持检查网关配置

服务端内部错误

错误信息	HTTP 状态码	原因	解决方案
`internal server error`	500	网关内部错误	请重试，若持续出现，请携带 Request ID 联系技术支持
`failed to record request log`	500	请求日志记录失败	不影响请求结果，可忽略；若频繁出现请联系技术支持
`failed to list models`	500	模型列表查询失败	请重试，若持续出现，请联系技术支持

常见场景速查

Base URL 错误

# ❌ 错误
https://api.gate.ai/v1/chat/completions

# ✅ 正确
https://api.gate.ai/openai/v1/chat/completions  # openai 协议
https://api.gate.ai/anthropic/v1/messages  # anthropic 协议

max_tokens 参数不兼容

// ❌ 部分模型不支持
{ "model": "gpt-4o", "max_tokens": 100 }

// ✅ 使用 max_completion_tokens
{ "model": "openai/gpt-5.5", "max_completion_tokens": 100 }

API Key 格式

# ✅ 正确的请求头
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx # openai 协议
X-api-key: sk-xxxxxxxxxxxxxxxxxxxx # anthropic 协议

Gate.AI 文档

快速开始

1. 创建 API 密钥

2. 自动路由（可选）

标准接入

响应示例：

Claude Code CLI 接入

创建 Gate.AI API 密钥

网络连通性验证

安装 Claude Code CLI

配置模型

验证接入是否成功

进阶配置

认证冲突处理

备选配置方式

模型环境变量

恢复直连 Anthropic 官方（可选）

故障排除

Base URL 常见错误

现象速查表

Codex CLI 接入

创建 Gate.AI API 密钥

网络连通性验证

安装 Codex CLI

配置模型

验证接入是否成功

进阶配置

配置参考

备选配置方式

切换模型

恢复直连 OpenAI 官方（可选）

故障排除

Base URL 常见错误

现象速查表

Cursor 接入

前置条件

Step 1：打开 Cursor 设置

Step 2：进入 Models 配置

Step 3：添加配置

Step 4：保存并关闭 Settings 页面

Step 5：在 Cursor 中使用 Gate.AI

常见问题

Claude Code 接入

1. 创建 Gate.AI API 密钥

2. 配置 Anthropic Base URL 与 API Key

方式 A：当前终端会话（临时）

方式 B：写入 Shell 配置文件

方式 C：Claude Code settings.json（推荐）

恢复直连 Anthropic 官方

3. 配置模型（Gate.AI 模型 ID）

3.1 使用环境变量指定默认模型

3.2 使用别名映射

3.3 在 /model 中选自定义项

3.4 自动路由模型 auto

4. 验证接入是否成功

5. 常见问题

Claude Desktop 接入

前置条件

Step 1：开启开发者模式

Step 2：打开第三方推理配置

Step 3：填写 Gate.AI 凭据和模型

Step 4：重启并启动

Step 5：验证

常见问题

Hermes 接入

前置条件

方式一：终端配置

1. 选择模型与自定义端点

2.（可选）本地 Web 管理界面

3. 验证

方式二：直接编辑配置文件

1. 文件位置

2. 在 .env 中保存密钥（任选其一）

3. 在 config.yaml 中配置 model

4. 保存后验证

多线路 / 多模型

切换方式

常见问题

QClaw 接入

对话式完成配置

方式 C：Claude Code `settings.json`（推荐）

3.3 在 `/model` 中选自定义项

3.4 自动路由模型 `auto`

2. 在 `.env` 中保存密钥（任选其一）

3. 在 `config.yaml` 中配置 `model`