Chat Completions

使用 OpenAI 相容的 Chat Completions API 建立文字、多模態和工具呼叫回應。

Chat Completions API 會根據訊息清單生成模型回應，適用於一般文字對話、多模態輸入、串流輸出、結構化輸出和函式工具呼叫。不同模型支援的輸入類型和進階參數可能不同，請以目前 API Key 可用的模型及實際呼叫結果為準。

POST/v1/chat/completions

根據指定的訊息清單生成模型回應。API 支援一般回應和 SSE 串流回應；圖片、音訊、工具呼叫、結構化輸出等進階功能取決於所選模型。

切換模型時，建議先使用最小文字請求驗證基本功能，再逐項啟用進階參數。

授權

bearerAuth

授權Bearer <token>

在 Authorization Header 中使用 Bearer your-api-key。

傳遞位置: header

請求主體

請依模型的輸入模態選擇請求結構。三個檢視使用相同的 Chat Completions 端點，並共用相同的生成參數。

application/json

文字對話

適用於一般聊天、內容生成與文字推理。訊息內容可以直接使用字串。

model: 目前帳戶可用的文字模型 ID。
messages[].role: 訊息角色，例如 user、system 或 assistant。
messages[].content: 字串格式的文字訊息。

application/json

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "你好！請用一句話介紹你自己。"
    }
  ]
}

文字對話請求。使用者訊息可以使用字串，或只包含 text 的內容陣列。

model*string

要使用的文字模型 ID。請從模型廣場複製目前帳戶可見且支援文字輸入的模型 ID。

長度1 <= length

messages*array<|||||>

文字對話訊息清單，依傳送順序排列。

項目數1 <= items

store?boolean|null

是否儲存本次聊天補全輸出。是否生效取決於所選模型和上游供應管道。

預設值false

reasoning_effort?string|null

推理模型的推理工作量。可用取值取決於所選模型；none 表示明確關閉推理工作量。

預設值"medium"

可用值

"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
null

metadata?|null

附加到請求的鍵值資訊。鍵最長 64 個字元，值最長 512 個字元。

欄位數properties <= 16

modalities?array<>|null

希望模型生成的輸出型別。預設只生成文字。

prediction?|null

已知大部分預期輸出時使用的預測內容設定。

audio?|null

請求音訊輸出時使用的格式和聲音設定。

temperature?number|null

取樣溫度。通常只調整 temperature 或 top_p 中的一項；是否支援取決於所選模型。

範圍0 <= value <= 2

預設值1

top_p?number|null

核取樣的累積機率。通常只調整 temperature 或 top_p 中的一項；是否支援取決於所選模型。

範圍0 <= value <= 1

預設值1

n?integer|null

為每個輸入生成的候選回覆數量。生成多個候選會增加用量。

範圍1 <= value <= 128

預設值1

stop?string|array<string>|null

最多四個停止序列。是否支援以及具體行為取決於所選模型。

max_tokens?integer|null

已棄用

舊版最大輸出 Token 參數。推薦使用 max_completion_tokens。

範圍1 <= value

max_completion_tokens?integer|null

補全可以生成的 Token 上限，包括可見輸出和推理 Token。

presence_penalty?number|null

根據 Token 是否已經出現施加懲罰，以增加討論新主題的可能性。是否支援取決於所選模型。

範圍-2 <= value <= 2

預設值0

frequency_penalty?number|null

根據 Token 已出現的頻率施加懲罰，以降低重複內容的可能性。是否支援取決於所選模型。

範圍-2 <= value <= 2

預設值0

logit_bias?|null

將 Token ID 對應到 -100 到 100 的偏差值。

logprobs?boolean|null

是否傳回輸出 Token 的對數機率。是否支援取決於所選模型。

預設值false

user?string

已棄用

已棄用的終端使用者標識。安全監測請使用 safety_identifier，快取路由請使用 prompt_cache_key。

safety_identifier?string|null

用於安全和濫用監測的穩定終端使用者標識。建議傳入經過雜湊處理且不包含個人資訊的值。

長度length <= 64

prompt_cache_key?string|null

用於提高相似請求快取命中率的穩定鍵值。請勿包含個人資訊或其他敏感資料。

prompt_cache_options?|null

請求級提示快取設定。

prompt_cache_retention?string|null

已棄用

已棄用的快取保留設定。請改用 prompt_cache_options.ttl。

可用值

"in_memory"
"24h"
null

verbosity?string|null

控制文字回答的詳細程度。是否支援取決於所選模型。

預設值"medium"

可用值

"low"
"medium"
"high"
null

moderation?|null

設定輸入和輸出的內容審核策略。

service_tier?string|null

請求使用的服務層級。是否可用取決於帳戶和上游能力。

預設值"auto"

可用值

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
null

stream_options?|null

僅在 stream: true 時使用的串流回應選項。

response_format?||

指定模型輸出格式。結構化輸出能力取決於所選模型。

seed?integer|null

已棄用

盡力進行確定性取樣的 Beta 參數，不保證完全確定。

tools?array<|>

模型可以呼叫的工具清單。

項目數items <= 128

functions?array<>

已棄用

舊版函式定義。推薦改用 tools。

tool_choice?|||

控制模型是否呼叫工具、強制呼叫指定工具，或將可用範圍限制為一組工具。

function_call?|

已棄用

舊版函式選擇參數。推薦改用 tool_choice。

parallel_tool_calls?boolean

是否允許模型在一次回應中並行呼叫多個工具。

預設值true

stream?boolean|null

為 true 時透過 Server-Sent Events 增量傳回聊天補全資料區塊。

預設值false

top_logprobs?integer|null

每個 Token 位置傳回的最可能 Token 數量。使用時應同時設定 logprobs: true；是否支援取決於所選模型。

範圍0 <= value <= 20

web_search_options?

圖片與音訊輸入僅適用於支援相應模態的模型；請以目前帳戶可用模型及實際 API 功能為準。

回應主體

`application/json`

curl -X POST "https://example.com/v1/chat/completions" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "messages": [      {        "role": "user",        "content": "你好！請用一句話介紹你自己。"      }    ]  }'

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我能為你提供什麼幫助？",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

OpenAI Chat Completions 官方文件檢視上游協議定義與最新欄位變更。

授權

請求主體

回應主體

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`