OpenAI 相容 API 指南：更換 Base URL

釐清 OpenAI 相容 API 的範圍、如何把既有用戶端切換至 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 傳送串流資料；
  • model、messages、input、stream，以及該協定所支援的工具定義。

相容不代表同一個模型可以在 Chat Completions 與 Responses 之間任意切換。模型可能只在其中一種已驗證的協定上提供。供應商專屬的推理、搜尋或多模態欄位，也可能必須原樣透傳，不能由閘道代為轉換。

請以即時的模型與價格目錄為準，確認要使用的模型、群組與 API 格式。

遷移前先整理現況

修改應用程式之前，建議先完成以下事項：

  1. 在API 金鑰中建立專用金鑰，不要沿用個人或其他整合所用的金鑰。
  2. 選擇確實能存取目標模型的主要群組。
  3. 只有在備援群組同樣支援該模型，且成本與可靠性政策一致時，才依優先順序加入。
  4. 記錄目前的端點、完整模型 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 重測，確認事件逐步抵達，也確認用戶端沒有等到整份回應完成才一次顯示。

遇到串流偏慢時，應分開觀察：

  • 驗證與選擇路由所花的時間；
  • 等待上游回應標頭的時間；
  • 第一個有效文字、推理或工具事件出現前的時間；
  • 可見輸出開始後的生成速度。

Modelflare 的用量記錄會保留這些請求層級的時間資料，但不儲存 Prompt、回應文字、原始請求本文、API 金鑰、電子郵件或明文 IP 位址。

正式環境切換檢查表

  • 將 API 金鑰放在祕密管理服務或環境變數。
  • Base URL 固定使用 https://modelflare.dev/v1。
  • 使用明確支援所選端點的模型。
  • 分別測試非串流與串流模式。
  • 若應用程式會使用工具、結構化輸出、推理控制或多模態輸入，逐項實測。
  • 0 或 false 具有語意時，必須保留明確值。
  • 逾時設定應依實際工作負載調整，不要只以短小的健康檢查 Prompt 為準。
  • 切換後從用量記錄核對狀態、延遲、Token、實際群組與費用。

協定邊界確認無誤後，用戶端通常可以保留既有請求生命週期；Modelflare 則在相同端點後方處理模型存取、路由政策與單筆請求可觀測性。