使用 API 與遊樂場

遊樂場

遊樂場用於線上簡單測試和體驗 AI 模型，使用者可以輸入問題或指令，與模型進行對話並檢視生成結果。入口為左側導覽「遊樂場」或 /playground。

選擇群組與模型：在輸入框右下方選擇可用的模型群組和具體模型，確認本次對話使用的模型。
設定請求參數：點擊參數設定按鈕，依需要啟用並調整溫度、Top P、頻率懲罰、存在懲罰和最大 Tokens 等生成參數。
填寫對話內容：在底部輸入框中輸入問題、指令或提示詞。
送出請求：確認模型、參數和輸入內容後，點擊「送出」按鈕提交請求。
檢視回覆結果：模型生成完成後，可在對話區域檢視回傳內容，並繼續輸入新的問題進行多輪對話。

API 位址與認證

閘道的 OpenAI 相容位址通常為：

https://your-host/v1

使用 API 金鑰作為 Bearer Token：

Authorization: Bearer sk-your-api-key

以聊天補全為例：

curl https://your-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}'

SDK 範例

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://your-host/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Claude 原生格式

curl https://your-host/v1/messages \
  -H "x-api-key: sk-xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'

Gemini 原生格式

curl "https://your-host/v1beta/models/gemini-1.5-pro:generateContent?key=sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "Hello"}]}]}'

支援的介面端點

對話與文字

介面	路徑	說明
聊天補全	`POST /v1/chat/completions`	OpenAI Chat Completions 相容介面，要求提供 `model` 和 `messages`，支援串流或一般回應。
遊樂場聊天	`POST /pg/chat/completions`	網頁遊樂場專用介面，使用登入工作階段認證，不需要 API 金鑰；計費方式與一般呼叫一致。
文字補全	`POST /v1/completions`	傳統文字補全介面，要求提供 `prompt` 和 `model`。
Responses API	`POST /v1/responses`	OpenAI Responses 格式介面，支援輸入、工具和回應事件等能力。
Responses 壓縮	`POST /v1/responses/compact`	對 Responses 請求上下文執行壓縮處理。
Claude Messages	`POST /v1/messages`	Anthropic Claude Messages 相容介面，要求提供 `model` 和訊息內容，必要時轉換為上游協定。
Codex 網頁搜尋	`POST /v1/alpha/search`	Codex 獨立網頁搜尋格式介面，僅部分模型支援。
即時對話	`GET /v1/realtime`（WebSocket）	OpenAI Realtime 風格的雙向即時通訊介面，模型通常透過查詢參數傳入，API 金鑰可透過 Bearer Token 或 WebSocket 子協定傳遞。

向量與排序

介面	路徑	說明
向量嵌入	`POST /v1/embeddings`	將文字或文字陣列轉換為向量，要求提供 `input`。
Gemini 嵌入相容介面	`POST /v1/engines/{model}/embeddings`	相容舊版 Gemini 風格的嵌入路徑，依 URL 中的模型名稱處理嵌入請求。
重新排序	`POST /v1/rerank`	依 `query` 對候選 `documents` 進行相關性排序，要求查詢內容和文件清單不為空。
內容審核	`POST /v1/moderations`	對文字或其他輸入執行內容審核；未提供模型時會使用預設審核模型候選。

圖像與音訊

介面	路徑	說明
圖像生成	`POST /v1/images/generations`	依提示詞生成圖像；可用的尺寸、品質和數量取決於所選模型。
圖像編輯	`POST /v1/images/edits`	依輸入圖像和提示詞進行圖像編輯，支援 JSON 和 `multipart/form-data` 請求。
舊版編輯介面	`POST /v1/edits`	保留的相容路徑，進入圖像 Relay 處理；新用戶端建議優先使用 `/v1/images/edits`。
語音轉文字	`POST /v1/audio/transcriptions`	將音訊轉換為文字，依照 OpenAI 音訊介面格式轉發到對應語音辨識通道。
音訊翻譯	`POST /v1/audio/translations`	辨識音訊內容並輸出翻譯後的文字。
文字轉語音	`POST /v1/audio/speech`	將輸入文字轉換為音訊。

影片、音樂等非同步生成介面見日誌與非同步任務中的「非同步生成與任務介面」。

模型清單

介面	路徑	說明
模型清單	`GET /v1/models`	預設回傳 OpenAI 格式模型清單；使用 Anthropic 請求標頭時回傳 Claude 格式，使用 `x-goog-api-key` 或 `key` 查詢參數時回傳 Gemini 格式。
模型詳情	`GET /v1/models/{model}`	查詢單一模型資訊；模型不存在時回傳 `model_not_found` 錯誤物件。
Gemini 模型清單	`GET /v1beta/models`	以 Gemini 格式回傳可用模型清單，回應欄位包括 `models` 和 `nextPageToken`。
OpenAI 格式模型清單	`GET /v1beta/openai/models`	在 Gemini 相容命名空間下，以 OpenAI 格式回傳模型清單。

Gemini 原生路徑

介面	路徑	說明
Gemini 原生模型呼叫	`POST /v1beta/models/{model}:{action}`	Gemini 原生格式介面，支援 `generateContent`、`streamGenerateContent` 和嵌入相關操作。
Gemini 相容模型呼叫	`POST /v1/models/{model}:{action}`	以 `/v1` 前綴承接 Gemini 風格的模型操作請求，由 Gemini Relay 負責解析和轉換。