如何集成 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：

text

認證格式如下：

text Authorization: Bearer YOUR_API_KEY

Gate.AI 文檔規定 API 路徑為 /openai/v1，而非僅 /v1（截至 2026年6月）。請嚴格按照示例填寫完整基礎 URL。

| 配置項 | 值 | | ------------------ | ------------------------------------------ | | 基礎 URL | | | 認證方式 | Authorization: Bearer YOUR_API_KEY | | 格式 | 兼容 OpenAI | | 聊天端點 | POST /chat/completions | | 模型列表端點 | GET /models |

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

步驟 4：發送首個 API 請求

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

Python 範例：

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

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 範例：

javascript import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "", });

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 範例：

bash curl /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：

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

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 | 使用完整基礎 URL 例子（見上文） | | 自動路由未按預期工作 | 自動路由被關閉或路由設置與預期不符 | 打開 Console → 設置 → 路由 檢查自動路由開關 | | 響應為空或異常 | 請求體格式錯誤或所選模型不支持當前請求 | 先測試最簡聊天請求，再逐步添加參數 |

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

後續可配置哪些內容？

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

• 在 Gate.AI 控制台配置模型路由行為：
• 查看模型可用性並為生產測試選擇固定模型 ID：
• 對比價格，合理選擇高並發場景下的模型：

常見問題解答

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

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

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

可以。Gate.AI 支持 OpenAI 兼容 API 格式，只需設置 Gate.AI API 密鑰並將基礎 URL 替換為 。

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

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

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

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