AI Gateway：OpenAI 相容 API 串接

用 OpenAI SDK 不改程式邏輯串接 MaiAgent AI Gateway：端點與 base URL、Bearer 認證、模型識別（別名、自建模型、備援群組）、思考等級、串流、錯誤格式、Credits 計費與限制。

本頁寫給要用 MaiAgent AI Gateway 呼叫語言模型的工程師，尤其是已經用 OpenAI SDK 寫好程式的軟體廠商（ISV）。Gateway 提供與 OpenAI 相容的介面，把 SDK 的 base_url 換成 MaiAgent、api_key 換成 MaiAgent API Key，就能透過同一個入口呼叫組織可用的各家模型，呼叫邏輯不必改。

Gateway 在來源、模型、資料、責任與紀錄五個面向提供哪些保障，請看 AI Gateway 安全性；本頁只講怎麼串接。

AI Gateway 需要由 MaiAgent 平台為組織開通。組織未開通時，任何金鑰呼叫推論端點都會得到與無效金鑰相同的 401。

端點總覽

方法	路徑	認證	用途
POST	/api/v1/chat/completions	必填	對話補全，支援串流與非串流
POST	/api/v1/embeddings	必填	文字向量化
GET	/api/v1/models	選填	列出可呼叫的模型識別碼與定價

Base URL（給 OpenAI SDK 的 base_url）：

https://api.maiagent.ai/api/v1

SDK 會自己在後面接上 /chat/completions、/embeddings、/models。路徑結尾不加斜線。

認證

推論端點使用 Bearer 認證，與 OpenAI SDK 預設送出的標頭相同：

Authorization: Bearer <GATEWAY_API_KEY>
Content-Type: application/json

• 金鑰就是 MaiAgent 的 API Key，但 Gateway 端點只認 Bearer 前綴；MaiAgent 其他 API 使用的 Api-Key <金鑰> 格式在這裡會回 401。

• 以下情況一律回同樣的 401 invalid_api_key，不透露是哪一關擋下：金鑰不存在、已撤銷、已停用、已過期、綁定的成員或使用者已停用、組織未開通 AI Gateway。

• 請求本文只接受 JSON。

取得 Gateway 金鑰

在 MaiAgent 管理後台 組織設定 → API Key 管理 → 建立 API Key。建立精靈分三步：選擇成員、開通與限制、產生金鑰。

• 金鑰綁定一位成員，呼叫會記在該成員名下，並受該成員的 Credits 額度限制。

• 「開通與限制」可以設定：這把金鑰可呼叫的模型（只能在組織可用範圍內縮小，預設全開）、每分鐘請求數（RPM）、每分鐘 Token 數（TPM）。

• 完整金鑰只在建立當下顯示一次，請立即保存到您的密鑰管理系統。

• 同一位成員可以同時持有多把有效金鑰，輪替時先簽新金鑰、部署完成再撤銷舊的，服務不中斷。

• 使用 API Key 管理頁需要「API Key 管理權限」。沒有這個權限的成員，可以在右上角頭像 → 帳號 → API 金鑰 自行建立金鑰（同樣適用於 Gateway）；模型開通與 RPM／TPM 則由管理者在 API Key 管理頁設定。

後台左側選單的 AI Gateway → 串接範例 會依您選的模型產生可複製的 cURL／Python／Node.js 範例；呼叫失敗時可到 AI Gateway → 總覽 執行 存取診斷，逐關檢查金鑰、成員、組織與模型開通狀態。看得到 AI Gateway 選單需要角色具備 AI Gateway 權限，設定方式見使用者手冊的 讓指定角色使用 AI Gateway。

最小範例

先把金鑰放進環境變數，不要寫死在程式碼：

export GATEWAY_API_KEY="<GATEWAY_API_KEY>"

OpenAI Python SDK

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GATEWAY_API_KEY"],
    base_url="https://api.maiagent.ai/api/v1",
)

resp = client.chat.completions.create(
    model="<vendor>/<model>",  # 從 GET /models 取得的 id，或備援群組 slug
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

curl

curl https://api.maiagent.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<vendor>/<model>",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

模型識別

model 欄位填的是 Gateway 模型識別碼，不是各家供應商的原生 ID。識別碼一律是含 / 的形式，沒有 / 的值會直接回 400。

您要呼叫的	model 填什麼	從哪裡取得
MaiAgent 託管模型	{vendor}/{model}（或平台設定的別名）	GET /models 回傳的 id
組織自建模型（BYOK／自架）	系統產生的 Gateway 模型 ID，形如 {供應商 slug}/{模型名}-{隨機碼}	後台 AI Gateway → 模型頁的「Gateway 模型 ID」
備援群組	系統產生的群組 slug，形如 maiagent/fallbacks-{隨機碼}	後台 AI Gateway → 備援模型群組

解析順序：先比對平台別名，再比對 {vendor}/{model}，接著是組織自建模型，最後是備援群組。平台模型（別名與 {vendor}/{model}）只在「組織可用 ∩ Gateway 開放 ∩ 這把金鑰開通」的範圍內找；自建模型與備援群組限本組織所有，並受這把金鑰的開通清單限制。範圍外的模型與不存在的模型回同樣的 404 model_not_found。

用 /models 列出可呼叫的模型

for m in client.models.list():
    print(m.id)

帶 Gateway 金鑰呼叫時，清單只列這把金鑰實際可呼叫的模型（含組織的封鎖設定與金鑰的開通清單）；不帶認證時回傳平台公開目錄，不含組織過濾。每筆除了 OpenAI 標準的 id、object、created、owned_by，還有：

欄位	說明
name	顯示名稱
type	目前一律 language
tags	能力標籤：tool-use、multimodal、reasoning、prompt-caching、streaming；reasoning 表示這個模型接受 reasoning_effort，見「思考等級」
pricing	託管模型：input／output，單位 credits_per_1k_tokens（帶 Gateway 金鑰呼叫時已含組織的 Gateway 服務費；不帶認證的公開目錄為未加服務費的基準單價）；自建模型：traffic_fee_percent，單位 percent_of_total_tokens
providers	可承載這個模型的後端供應商清單，每筆有 slug，可搭配下方的 provider.order 指定
context_window、max_tokens	有設定時才出現

組織隱藏中國模型時的串接行為

組織開啟「隱藏中國模型」後，依平台登錄的模型產地排除中國平台模型，包含日後新上架的模型。這項限制會套用到 Gateway 的模型目錄與實際呼叫：

• 帶金鑰查詢目錄：GET /models 不列出被隱藏的平台模型；不帶認證的公開目錄沒有組織資訊，不套用這項限制。

• 直接呼叫平台模型：被隱藏的模型無法透過別名或 {vendor}/{model} 呼叫，回 404 model_not_found。以自帶金鑰呼叫同一個平台模型，也不會繞過組織的隱藏設定。

• 呼叫備援群組：先排除被隱藏的平台模型步驟，再使用剩餘步驟；沒有剩餘步驟時回 404 model_not_found，該群組也不列入帶金鑰取得的目錄。

• 組織自建模型：組織自己建立的 Gateway 模型不受這項產地隱藏設定限制，仍須符合原有的金鑰開通規則。

例如，企業的整合工程師原本將某個中國平台模型設為預設值；組織開啟隱藏後，原本的識別碼會回 404。工程師應用服務實際使用的金鑰重新取得 /models 清單，將預設值改成清單中的可用模型，再恢復呼叫；不要以未帶認證的公開目錄判斷該組織是否有權使用模型。

隱藏設定不會清除既有的逐模型封鎖清單；關閉隱藏後，仍依原本的組織啟用狀態與金鑰開通範圍判斷。

指定後端供應商

同一個模型識別碼可能由多家供應商承載（例如同一個模型同時在原廠與雲端平台上架）。要固定走某一家，在請求本文加上 provider.order，填 /models 回傳的 providers[].slug：

resp = client.chat.completions.create(
    model="<vendor>/<model>",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"provider": {"order": ["<provider-slug>"]}},
)

目前只採用清單的第一個值；該供應商沒有這個模型時回 404 model_not_found。指定 provider.order 時不會解析到備援群組。

自帶金鑰（BYOK）

組織擁有者可以在後台 AI Gateway → 模型供應商 登錄組織自己的供應商憑證。登錄後：

• 呼叫託管模型時，若組織有同一家供應商的有效憑證，Gateway 會改用組織的憑證呼叫上游（同家有多筆時用最近更新的一筆），呼叫端的 model 不用改。

• 也可以用這些憑證建立「自建模型」，以系統產生的 Gateway 模型 ID 呼叫。

• 上游以 401／403 拒絕組織憑證時，Gateway 回 502 upstream_auth_error，訊息會指出是組織的 BYOK 憑證被拒，請到 AI Gateway 設定更新憑證。

部分更新供應商憑證

整合程式可用 PATCH /api/v1/gateway/credentials/{id}/ 更新自己組織的供應商憑證。此管理介面需要登入、組織已開通 AI Gateway、具備 AI Gateway 存取權限，且寫入者為組織擁有者；認證與 推論端點 的 Gateway Bearer 金鑰用途不同。

請求可包含 name、isActive 或 credentials；credentials 內使用 apiBase、apiKey 等 camelCase 欄位名稱。每個憑證欄位依下表處理：

送出的值	更新結果
省略欄位	保留原值
空字串 ""	保留原值，代表沒有修改
非空的新值	取代原值，再依供應商規則驗證
null	清空選填欄位；必填欄位無法清空，會回 400

例如 vLLM 與 OpenAI 相容供應商的 apiKey 可用 null 清空，但 apiBase 為必填。Anthropic 的選填 apiBase 可用 null 清除憑證中的自訂端點；API Key 仍為必填。

已存有 API Key 時，把 apiBase 改成另一個非空端點，必須同時重新輸入 apiKey，或在該供應商允許時明確以 null 清空金鑰。省略金鑰或送空字串會回 400，錯誤位於 credentials.apiKey，原設定不變。只改名稱或重送相同端點不需重新輸入金鑰。

讀取回應只提供遮罩預覽 credentialsPreview，不會回傳原始憑證。後台的操作說明請見 模型供應商設定，本節只說明整合程式的更新語意。

備援群組

備援群組是組織擁有者在後台建立的有序模型清單。model 填群組 slug 時才會啟用整條備援鏈；單一模型的呼叫不會自動切換。

• 切換條件（系統固定）：逾時、連線失敗、上游回 408／429／500／502／503／504／529。參數錯誤、金鑰無效這類請求端錯誤不切換，直接回錯誤。

• 串流：Gateway 會先向上游取得第一段內容再開始回應，所以連線錯誤與限流在送出第一個位元組前就能切換；一旦開始回傳內容就不再切換。

• 回應的 model 欄位維持您送出的群組 slug，實際由哪個模型服務、是否觸發備援會記錄在後台的用量與請求紀錄。

• 模型資料已不存在，或組織自建模型已被刪除（停用）的步驟，會在呼叫前跳過；主模型也會改用清單中第一個仍可呼叫的步驟。平台模型僅被停用時不適用這項跳過規則。

• 整條鏈沒有可呼叫的步驟時，推論回 400 invalid_request_error，錯誤碼為 fallback_group_unavailable；請編輯群組加入可用模型，不要把它當作暫時的上游錯誤重試。

• GET /api/v1/gateway/fallback-groups/{id}/ 讀取群組時，上述失效步驟會回 modelId: null、modelName: ""、managedModel: null、customModel: null。讀取管理介面需要登入、組織已開通 AI Gateway 與 AI Gateway 存取權限；只能讀取可見的平台群組與自己組織的群組。

• /models 中的組織自有備援群組，只有仍存在可呼叫步驟時才會列出。這項規則不代表每個平台虛擬模型會從模型目錄消失。

對話補全參數

POST /chat/completions 接受的欄位：

欄位	說明
model	必填，見上節
messages	必填、不可為空。role 可為 system、user、assistant、tool；content 可為字串或 text／image_url 多模態陣列；支援 tool_calls、tool_call_id、name
stream	預設 false
stream_options.include_usage	預設 false，見「串流」
temperature	數值
max_tokens	最小 1
top_p	0 到 1
stop	字串或字串陣列
n	1 到 8，預設 1
tools	只支援 type: "function"，函式名稱最長 64 字元
tool_choice	auto、none、required 或指定函式物件
parallel_tool_calls	預設 true
response_format	type 為 text、json_object 或 json_schema；json_schema 需附 json_schema 物件
reasoning_effort	none、minimal、low、medium、high、xhigh、max；只對 /models 帶 reasoning 標籤的模型生效，見「思考等級」
provider	MaiAgent 擴充欄位，見「指定後端供應商」

注意事項：

• 目標模型不支援 top_p 或 stop 時，這兩個參數會被略過而不是報錯。

• tools 與 response_format: json_schema 不能同時使用，會回 400。

• json_schema 模式在串流時，完整 JSON 會以單一個 delta 一次送出，不會逐字串流。

• json_object 模式會在系統訊息中加上「只輸出合法 JSON」的指示。

• json_object 回覆若整段只有一個 Markdown json 程式碼區塊，且區塊內容是合法 JSON，Gateway 會移除區塊標記再回傳；一般回覆與串流回覆都適用。

• 若區塊外還有說明文字、區塊內容不是合法 JSON，或回覆截斷後不再構成完整的合法 JSON 區塊，Gateway 會保留模型原文。串接端仍須自行解析並處理無效 JSON，不能只靠 json_object 保證每次都取得可解析的物件。

• 串流的 json_object 回覆若以反引號開頭，Gateway 會等整段回覆結束後才送出內容；其他回覆照常逐段送出。上游中途失敗時，已收到但尚未送出的內容會照原文送出，再回報錯誤。

回應是標準 chat.completion 物件，id 形如 chatcmpl-...，model 回傳您送出的識別碼；回應標頭 x-request-id 與 id 相同，回報問題時請附上。

思考等級（reasoning_effort）

reasoning_effort 用一組跨供應商通用的等級指定模型要想多深，由弱到強：

none < minimal < low < medium < high < xhigh < max

• 可送的值：只接受上面七個值或 null。其他值（包括 off、數字形式的 token 預算）回 400 invalid_request。none 代表關閉思考。

• 不送或送 null：Gateway 不指定等級。平台若為該模型設了預設思考等級就用它，否則不送思考參數，由供應商自己的預設決定。例外是少數 OpenAI 模型（例如 GPT-5.6 系列）不帶等級就不接受工具定義，平台會替這類模型送出 none。

• 模型沒有 reasoning 標籤：這個模型沒有思考控制，reasoning_effort 會被略過，不會報錯。

• 轉換方式：等級會先對應到目標模型支援的等級，再換成該供應商的原生參數（例如 OpenAI 的 reasoning_effort、Claude 的 effort 或思考 token 預算、Gemini 的思考預算）。每個模型支援哪些等級由平台依模型家族維護，/models 目前只提供 reasoning 標籤，不列出個別模型支援的等級。

模型不支援您送的等級時，Gateway 不報錯，而是依下列規則調整：

情況	實際送出
模型支援這個等級	原樣送出
不支援，但有較弱的等級	改用最接近、且不比您要求更強的等級（例如模型只到 high，送 max 會以 high 送出），不會因為調整而變貴
要求的等級低於模型的最低等級	改用模型的最低等級
要求思考（none 以外）	不會被調整成關閉
送 none，但模型無法關閉思考	不送思考參數，由供應商預設決定；這類模型仍會思考並依實際 token 計費

同一個等級在不同模型上代表的實際思考量不同。換模型時請重新評估延遲與 token 用量，不要假設相同等級的費用一致。

串流

stream: true 時回應為 Server-Sent Events（Content-Type: text/event-stream），每個事件是一行 data: {chat.completion.chunk JSON}，正常結束以 data: [DONE] 收尾。OpenAI SDK 直接迭代即可：

stream = client.chat.completions.create(
    model="<vendor>/<model>",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

• include_usage: true 時，最後會多一個 choices 為空陣列、帶 usage 的事件。這個選項只影響是否回傳用量，不影響計費；不論是否開啟，Gateway 都會記錄並計費。

• 開始串流前發生的錯誤（認證、額度、模型不存在、上游連線失敗）以一般 HTTP 錯誤回應，不會是 SSE。

• 串流中途上游出錯時，HTTP 狀態已經是 200，Gateway 會送出一個 data: {"error": {...}} 事件後結束，不送 [DONE]。請在客戶端處理這種事件。

向量化

POST /embeddings 與 OpenAI 相同：

emb = client.embeddings.create(
    model="<embedding-model>",
    input=["第一段文字", "第二段文字"],
)
print(len(emb.data), len(emb.data[0].embedding))

• input：非空字串，或非空字串陣列。

• encoding_format：float（預設）或 base64。

• model：比對平台已對 Gateway 開放的向量模型識別值（其次比對名稱）。向量模型不在 /models 清單中，也不受 API Key 的模型開通清單限制；請向 MaiAgent 確認可用的向量模型識別碼。

• usage.prompt_tokens 由 Gateway 以 cl100k_base 分詞估算，這個數字也是計費依據。

錯誤格式

所有錯誤都是 OpenAI 格式，OpenAI SDK 會轉成對應的例外：

{
  "error": {
    "message": "Model 'vendor/model' not found or not enabled",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null
  }
}

HTTP	type	code	常見原因	建議處理
400	invalid_request_error	invalid_request	欄位驗證失敗、model 沒有 /、tools 與 json_schema 併用	修正請求，不要重試
400	invalid_request_error	upstream_invalid_request	上游以 400／413／415／422 拒絕請求（參數、工具定義或輸入大小超出該模型限制）	依目標模型限制調整請求
400	invalid_request_error	fallback_group_unavailable	備援群組沒有任何可呼叫的步驟	編輯群組，加入可用模型
401	authentication_error	invalid_api_key	金鑰無效、停用、過期、撤銷，或組織未開通 Gateway	檢查金鑰；用後台存取診斷定位
402	billing_error	insufficient_credits	組織 Credits 不足，或成員／群組額度用盡；在呼叫上游前就擋下	儲值或調整額度
404	invalid_request_error	model_not_found	模型不存在、未開放給組織、未開通給這把金鑰，或指定的供應商沒有該模型	用 /models 確認可用 id
429	rate_limit_error	rate_limit_exceeded	超過金鑰的 RPM 或 TPM 限制	退避後重試
502	server_error	upstream_auth_error	上游拒絕憑證（BYOK 或平台憑證）	BYOK：更新憑證；平台憑證：聯繫 MaiAgent
502	server_error	upstream_error	上游逾時、限流、5xx 或其他錯誤；上游原始錯誤訊息不會回傳	退避後重試，或改用備援群組

用量與 Credits 計費

每次成功呼叫都從組織的 Credits 扣點，對話補全以上游回報的 token 數為準，向量化以 Gateway 估算的 token 數為準（見「向量化」）：

• 託管模型：依模型的輸入／輸出（含提示快取）token 單價計費，再加上組織的 Gateway 服務費比例。帶 Gateway 金鑰呼叫 /models 時，pricing 已是加上服務費後的單價；不帶認證的公開目錄顯示的是未加服務費的基準單價。

• 自建模型與 BYOK 憑證：上游費用由貴公司直接付給供應商，MaiAgent 只收流量費，依該次呼叫的總 token 數（輸入＋輸出＋提示快取寫入與讀取）× 組織的流量費率計算，不收 LLM token 定價。使用者手冊的 AI Gateway 自建模型的流量費 說明如何在後台核對。

• 向量化：依輸入 token 數計費，同樣加上 Gateway 服務費。

• 串流中斷：客戶端中途斷線或上游中途出錯時，已產生的 token 仍會計費。

• 組織 Credits 不足或成員額度用盡時，請求在呼叫上游前就回 402。

用量可在後台 AI Gateway → 總覽 依模型、供應商與 API Key 查看，扣點明細在 Credits 消耗記錄。

限制

• RPM：金鑰的每分鐘請求數上限作用在這把金鑰能呼叫的所有 MaiAgent API，不只 Gateway。

• TPM：每分鐘 Token 數上限只作用在 Gateway 的對話補全與向量化。token 數要等上游回應後才知道，所以單一請求可能讓當分鐘超出一次，之後該分鐘內的請求都回 429，下一分鐘重置。

• 未設定 RPM／TPM 時不限速。

• 目前提供的 OpenAI 相容端點只有上表三個；OpenAI 的 Responses、Assistants、圖片、語音等端點不在 Gateway 範圍內。

相關文件

• AI Gateway 安全性：端點來源、模型把關、資料保護與稽核紀錄

• 快速上手：MaiAgent 平台 API（Agent、對話、知識庫）的認證方式

• 使用者手冊 Credits：Credits 餘額、計費方式與消耗記錄