如何整合 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。如實際行為與預期不符，請檢查控制台的路由設定。