OpenAI 相容 API 指南:只改 Base URL

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

OpenAI 相容 API 指南:只改 Base URL

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 格式。

準備遷移

修改應用程式程式碼之前:

  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 重送同一個請求,確認事件是逐步送達,並確保用戶端不會先緩衝完整回應才開始顯示。

診斷緩慢的串流時,請分開觀察:

  • 驗證身分與選擇路由所花的時間;
  • 收到服務商回應標頭之前的時間;
  • 收到第一段有效內容或工具增量(delta)之前的時間;
  • 可見輸出開始後的生成輸送量。

Modelflare 使用日誌為此保留了請求層級的時間中繼資料,但不會儲存提示詞、回應文字、原始請求本文、API 金鑰、電子郵件或明文 IP 位址。

正式環境遷移檢查清單

  • 將 API 金鑰存放在機密管理服務或環境變數中。
  • 將 Base URL 固定為 https://modelflare.dev/v1。
  • 使用明確支援所選端點的模型。
  • 分別測試非串流與串流模式。
  • 若應用程式有用到工具、結構化輸出、推理控制或多模態輸入,請逐一測試。
  • 當用戶端請求中明確的 0 或 false 值具有意義時,請保留這些值。
  • 依實際工作負載設定用戶端逾時,而不是只用簡短的健康檢查提示詞來決定。
  • 切換後,在使用日誌中檢查狀態、延遲、Token 用量、所選群組與費用。

確認協定邊界之後,用戶端通常可以維持既有的請求生命週期,而由 Modelflare 在相容端點背後提供模型存取、路由政策與每筆請求的可視性。

想了解端點背後的營運層,請閱讀什麼是 AI API 閘道?。如果用戶端可以使用不只一種 OpenAI 格式,請在變更路徑前先參閱Responses API 與 Chat Completions 比較。