如何整合 Gate.AI：開發者快速上手指南

Gate.AI API 集成讓開發者能夠透過相容 OpenAI 的 API 存取多種 AI 模型，實現統一的模型接入、路由與測試，無需為每個模型服務商單獨維護 SDK 設定。不論是開發聊天機器人、內部工具、智慧代理、流程自動化，或模型評測腳本，都能大幅簡化接入流程。本指南將介紹 API 金鑰建立、自動路由、手動模型選擇、OpenAI 相容基礎 URL、首次請求測試及常見設定錯誤排查，但不涵蓋企業級治理、計費策略設計或自訂安全架構等進階主題。

前置條件：

• 擁有 Gate.AI 帳戶並可存取 Console 設定。
• 本地環境已安裝 Python、Node.js 或 curl。

完成本指南後你將獲得哪些能力？

完成本指南後，你將能夠建立 Gate.AI API 金鑰、設定 OpenAI 相容基礎 URL、使用 model: "auto" 發送首個 API 請求，並測試指定模型 ID。

開發者透過 Gate.AI API 集成可以打造哪些應用？

開發者可利用 Gate.AI API 集成，透過統一的 OpenAI 相容請求格式存取多模型系統，典型應用場景包括：

構建類型	Gate.AI 的作用	範例輸出
聊天應用	將用戶訊息路由至支援的聊天模型	客服助理
內部工具	團隊間統一 API 設定	AI 寫作/研究助手
智慧代理與流程	連接模型調用與任務自動化	工具調用助理
模型測試	比較 auto 路由與固定模型 ID	評測腳本
移轉專案	替換現有 OpenAI 相容基礎 URL	多模型原型

當你希望 Gate.AI 自動選擇模型時，請使用 model: "auto"；若需對某一指定模型進行可重現操作，則填入具體模型 ID。

開始前你需要準備什麼？

啟動前僅需符合兩個關鍵條件：

必要條件	重要原因
Gate.AI 帳戶存取	需進入 Console 建立 API 金鑰並檢查路由設定
本地請求方式	需透過 Python、Node.js 或 curl 發送測試請求

無需一開始就選擇所有模型。請先確認 API 金鑰與基礎 URL 可用，再測試手動模型選擇。

步驟 1：建立 Gate.AI API 金鑰

本步驟將建立你應用用於 API 認證的憑證。

操作方法：

1. 造訪 gate.ai。
2. 選擇登入方式並完成授權。
3. 開啟 Console → 設定 → API keys。
4. 點擊 建立金鑰。
5. 立即複製 API 金鑰並妥善保存。

你會在 API 金鑰區域看到新金鑰。若 secret 僅顯示一次，請務必在關閉建立視窗前複製金鑰。

步驟 2：選擇自動路由或手動模型選擇

本步驟決定由 Gate.AI 自動分配模型，或在請求中指定模型。

操作方法：

1. 開啟 Console → 設定 → 路由。
2. 檢查 自動路由 開關。
3. 若需 Gate.AI 為每次請求自動選擇模型，保持自動路由開啟。
4. 若需手動指定模型 ID，則關閉自動路由，在請求體中填入模型 ID。

選擇模式	請求參數值	適用場景
自動路由	"model": "auto"	需 Gate.AI 自動路由請求時
手動模型選擇	"model": "anthropic/claude-sonnet-4.6"	需測試或使用指定模型 ID 時

自動路由適合快速接入與通用路由測試；手動選擇則適用需對單一模型進行可重現評測的場景。

步驟 3：設定 OpenAI 相容基礎 URL

本步驟將現有 OpenAI 風格客戶端指向 Gate.AI，而非預設 OpenAI 端點。

請使用以下基礎 URL：

https://api.gate.ai/openai/v1

認證格式如下：

Authorization: Bearer YOUR_API_KEY

Gate.AI 文件規定 API 路徑為 /openai/v1，而非僅 /v1（截至 2026年6月）。請務必依照範例完整填寫基礎 URL。

設定項	值
基礎 URL	https://api.gate.ai/openai/v1
認證方式	Authorization: Bearer YOUR_API_KEY
格式	相容 OpenAI
聊天端點	POST /chat/completions
模型列表端點	GET /models

大多數集成錯誤源於基礎 URL 縮寫或 API 金鑰複製錯誤。請先確認這兩項無誤，再調整模型設定。

步驟 4：發送首個 API 請求

本步驟用於測試 API 金鑰、基礎 URL 及 OpenAI 相容聊天格式是否協同運作。

Python 範例：

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.gate.ai/openai/v1",
)
completion = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Say hello from Gate.AI."}
    ],
)
print(completion.choices[0].message.content)

Node.js 範例：

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.gate.ai/openai/v1",
});
const completion = await client.chat.completions.create({
  model: "auto",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Say hello from Gate.AI." }
  ],
});
console.log(completion.choices[0].message.content);

curl 範例：

curl https://api.gate.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Say hello from Gate.AI."}
    ]
  }'

你應會收到正常的助手回覆。如遇認證錯誤，請先檢查 API 金鑰，無需立即修改程式碼。

步驟 5：測試指定模型 ID

本步驟驗證應用需指定模型時，手動模型選擇是否生效。

將 model 參數由 auto 改為具體支援的模型 ID：

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.gate.ai/openai/v1",
)
completion = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "user", "content": "Explain model routing in one paragraph."}
    ],
)
print(completion.choices[0].message.content)

請嚴格依 Gate.AI 模型文件或模型列表中的名稱填寫模型 ID。如拼寫錯誤，即使 API 金鑰與基礎 URL 正確，請求也會失敗。

Gate.AI API 請求中的自動路由機制如何運作？

Gate.AI 自動路由透過在請求體中填寫 model: "auto"，並結合 Gate.AI 控制台中的路由設定，為請求自動選擇模型。截止 2026年6月，相關路由控制項可於 Console → 設定 → 路由 管理。

路由方式	設定位置	API 請求參數
自動路由	Console → 設定 → 路由	"model": "auto"
手動模型選擇	請求體	指定模型 ID
路由策略控制	控制台路由設定	組織自訂行為

自動路由並不等同於省略模型欄位。需於請求中明確填寫 model 欄位並賦值為 auto，Gate.AI 才會自動路由。

應選擇哪種集成方式？

請依應用運行環境選擇集成方式：

方式	適用場景	主要變更點
Python SDK	已有 Python 後端腳本或服務	設定 base_url 與 api_key
Node.js SDK	使用 JavaScript 或 TypeScript 服務	設定 baseURL 與 apiKey
curl	需最快速手動驗證	直接發送請求標頭與 JSON 載荷
現有 OpenAI 相容應用	應用已支援自訂基礎 URL	替換基礎 URL 與 API 金鑰

多數開發者推薦先用 curl 快速驗證，隨後用 Python 或 Node.js 集成至實際應用。

Gate.AI API 請求失敗的常見原因有哪些？

集成遇阻時，請依下表逐項排查：

症狀	原因說明	解決方法
401 或 API 金鑰無效	API 金鑰缺失、過期、複製錯誤，或未用 Bearer 認證	重新建立/複製金鑰，使用 Authorization: Bearer YOUR_API_KEY
找不到模型	請求使用了錯誤或帳戶不可用的模型 ID	查閱 Gate.AI 模型文件，或用 model: "auto" 路由測試
OpenAI 相容程式碼立即報錯	基礎 URL 不完整或僅填寫 /v1	使用 https://api.gate.ai/openai/v1
自動路由未如預期運作	自動路由被關閉或路由設定與預期不符	開啟 Console → 設定 → 路由 檢查自動路由開關
回應空白或異常	請求體格式錯誤或所選模型不支援目前請求	先測試最簡聊天請求，再逐步增加參數

排查建議依序從認證、基礎 URL、模型 ID 開始。大部分快速接入問題可透過這三步解決。

後續可設定哪些內容？

首次請求成功後，開發者可從以下三個方向擴展集成：

• 在 Gate.AI 控制台設定模型路由行為：https://gate.ai/docs
• 查看模型可用性並為生產測試選擇固定模型 ID：https://gate.ai/models
• 比較價格，合理選擇高並發場景下的模型：https://gate.ai/pricing

常見問題解答

為什麼建議優先使用 model: "auto"？

優先用 model: "auto" 可一次驗證 API 金鑰、基礎 URL、請求格式與路由設定。確認無誤後，再測試指定模型 ID。

可以用現有 OpenAI SDK 呼叫 Gate.AI 嗎？

可以。Gate.AI 支援 OpenAI 相容 API 格式，只需設定 Gate.AI API 金鑰並將基礎 URL 替換為 https://api.gate.ai/openai/v1。

切換到指定模型後請求失敗的原因？

模型 ID 可能不存在、拼寫錯誤，或目前帳戶不支援。請在 Gate.AI 模型文件中確認模型 ID 後重試。

使用指定模型時需要關閉自動路由嗎？

不一定。當需手動選擇模型時，可直接於請求體中傳入模型 ID。如行為與預期不符，請檢查控制台路由設定。