OpenAI 相容 API 指南:只改 Base URL
了解 OpenAI 相容涵蓋哪些範圍、如何將既有用戶端遷移到 Modelflare,以及正式流量上線前應驗證哪些邊界。

OpenAI 相容 API 能讓既有用戶端沿用熟悉的驗證標頭、JSON 請求結構與串流模式,同時把流量改送到另一個閘道。實際改動可能只是更換 Base URL 與 API 金鑰,但相容性仍是一份協定契約——並不保證每個模型都支援所有端點或供應商專屬欄位。
本指南說明已使用 OpenAI 風格 API 的應用程式、指令碼與 AI 工具,該如何安全地完成遷移。
OpenAI 相容實際涵蓋哪些範圍
協定中最能直接沿用的部分包括:
- 透過 Authorization 標頭進行 Bearer Token 驗證。
- 在具版本號的 /v1 端點上收發 JSON 請求與回應。
- 常見端點,例如 /v1/models、/v1/chat/completions 與 /v1/responses。
- 支援串流的請求以 Server-Sent Events(SSE)傳送。
- 熟悉的請求欄位,例如 model、messages、input、stream,以及所選協定支援時的工具定義。
相容不代表同一個模型可以在 Chat Completions 與 Responses 之間自由切換。某個模型可能只透過一種經過驗證的協定提供。供應商專屬的推理、搜尋或多模態欄位,也可能需要原樣轉送,而不是由閘道轉換。
請以即時的模型與定價目錄為準,確認要使用的模型、群組與 API 格式。
準備遷移
修改應用程式程式碼之前:
- 在 API 金鑰中建立專用金鑰,不要重複使用個人金鑰或其他整合的金鑰。
- 選擇一個可以存取目標模型的主要模型群組。
- 只有在備援群組同樣支援該模型,且符合相同的成本與可靠性政策時,才依序加入備援群組。
- 記下目前的端點、模型 ID、串流設定與工具使用情況,以便比較遷移前後的行為。
Modelflare 的標準 OpenAI 相容 Base URL 為:
https://modelflare.dev/v1
多數 SDK 預期 Base URL 只到 /v1,並會自行附加 /chat/completions 或 /responses。加上第二段端點路徑之前,請先查閱用戶端的文件。
先驗證身分與模型存取權
請把金鑰存放在環境變數中,而不是寫進原始碼:
export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'
接著確認這把金鑰可以列出可用的模型:
curl -sS https://modelflare.dev/v1/models \
-H "Authorization: Bearer $MODELFLARE_API_KEY"
成功的回應證明主機名稱、TLS 連線路徑與金鑰都有效,但還不能證明某種請求格式適用於每個傳回的模型,因此下一項檢查必須使用預定的端點。
以預定協定送出一次請求
若模型已列為相容 Chat Completions 格式:
curl -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [
{"role": "user", "content": "請回覆目前使用中的模型名稱。"}
],
"stream": false
}'
若是相容 Responses 的程式開發模型:
curl -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"input": "請回覆目前使用中的模型名稱。",
"stream": false
}'
請使用即時目錄中顯示的完整模型 ID。出現 model_not_found 通常表示所選的金鑰或群組無法存取該模型,而不是改一下英文大小寫就能解決。
另外驗證串流
對依賴串流的應用程式來說,非串流請求成功還不夠。請以 "stream": true 重送同一個請求,確認事件是逐步送達,並確保用戶端不會先緩衝完整回應才開始顯示。
診斷緩慢的串流時,請分開觀察:
- 驗證身分與選擇路由所花的時間;
- 收到服務商回應標頭之前的時間;
- 收到第一段有效內容或工具增量(delta)之前的時間;
- 可見輸出開始後的生成輸送量。
Modelflare 使用日誌為此保留了請求層級的時間中繼資料,但不會儲存提示詞、回應文字、原始請求本文、API 金鑰、電子郵件或明文 IP 位址。
正式環境遷移檢查清單
- 將 API 金鑰存放在機密管理服務或環境變數中。
- 將 Base URL 固定為 https://modelflare.dev/v1。
- 使用明確支援所選端點的模型。
- 分別測試非串流與串流模式。
- 若應用程式有用到工具、結構化輸出、推理控制或多模態輸入,請逐一測試。
- 當用戶端請求中明確的 0 或 false 值具有意義時,請保留這些值。
- 依實際工作負載設定用戶端逾時,而不是只用簡短的健康檢查提示詞來決定。
- 切換後,在使用日誌中檢查狀態、延遲、Token 用量、所選群組與費用。
確認協定邊界之後,用戶端通常可以維持既有的請求生命週期,而由 Modelflare 在相容端點背後提供模型存取、路由政策與每筆請求的可視性。
想了解端點背後的營運層,請閱讀什麼是 AI API 閘道?。如果用戶端可以使用不只一種 OpenAI 格式,請在變更路徑前先參閱Responses API 與 Chat Completions 比較。