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（上下文長度），直接按 Enter 留空即可（由 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`