88API88API
使用指南AI 應用API 文件幫助支援
聊天（Chat）

OpenAI 對話格式（Chat Completions）

官方文件

OpenAI Chat

📝 簡介

給定一組包含對話的訊息列表，模型將返回一個響應。相關指南可參閱OpenAI官網：Chat Completions

💡 請求示例

基礎文字對話 ✅

curl https://88api.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "developer",
        "content": "你是一個有幫助的助手。"
      },
      {
        "role": "user",
        "content": "你好！"
      }
    ]
  }'

響應示例:

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4.1-2025-04-14",
  "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
    }
  },
  "service_tier": "default"
}

影象分析對話 ✅

curl https://88api.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "這張圖片裡有什麼？"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 300
  }'

響應示例:

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4.1-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "圖片展示了一條穿過茂密綠色草地或草甸的木製棧道。天空湛藍，點綴著幾朵散落的雲彩，給整個場景營造出寧靜祥和的氛圍。背景中可以看到樹木和灌木叢。",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "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
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

流式響應 ✅

curl https://88api.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "developer",
        "content": "你是一個有幫助的助手。"
      },
      {
        "role": "user",
        "content": "你好！"
      }
    ],
    "stream": true
  }'

流式響應示例:

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"你好"},"logprobs":null,"finish_reason":null}]}

// ... 更多資料塊 ...

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

函式呼叫 ✅

curl https://88api.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "波士頓今天的天氣怎麼樣？"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "獲取指定位置的當前天氣",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市和州，例如 San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

響應示例:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n\"location\": \"Boston, MA\"\n}"
            }
          }
        ]
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

Logprobs 請求 ✅

curl https://88api.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "你好！"
      }
    ],
    "logprobs": true,
    "top_logprobs": 2
  }'

響應示例:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1702685778,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我能為你提供什麼幫助？"
      },
      "logprobs": {
        "content": [
          {
            "token": "Hello",
            "logprob": -0.31725305,
            "bytes": [72, 101, 108, 108, 111],
            "top_logprobs": [
              {
                "token": "Hello",
                "logprob": -0.31725305,
                "bytes": [72, 101, 108, 108, 111]
              },
              {
                "token": "Hi",
                "logprob": -1.3190403,
                "bytes": [72, 105]
              }
            ]
          },
          {
            "token": "!",
            "logprob": -0.02380986,
            "bytes": [33],
            "top_logprobs": [
              {
                "token": "!",
                "logprob": -0.02380986,
                "bytes": [33]
              },
              {
                "token": " there",
                "logprob": -3.787621,
                "bytes": [32, 116, 104, 101, 114, 101]
              }
            ]
          },
          {
            "token": " How",
            "logprob": -0.000054669687,
            "bytes": [32, 72, 111, 119],
            "top_logprobs": [
              {
                "token": " How",
                "logprob": -0.000054669687,
                "bytes": [32, 72, 111, 119]
              },
              {
                "token": "`<|end|>`",
                "logprob": -10.953937,
                "bytes": null
              }
            ]
          },
          {
            "token": " can",
            "logprob": -0.015801601,
            "bytes": [32, 99, 97, 110],
            "top_logprobs": [
              {
                "token": " can",
                "logprob": -0.015801601,
                "bytes": [32, 99, 97, 110]
              },
              {
                "token": " may",
                "logprob": -4.161023,
                "bytes": [32, 109, 97, 121]
              }
            ]
          },
          {
            "token": " I",
            "logprob": -3.7697225e-6,
            "bytes": [32, 73],
            "top_logprobs": [
              {
                "token": " I",
                "logprob": -3.7697225e-6,
                "bytes": [32, 73]
              },
              {
                "token": " assist",
                "logprob": -13.596657,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              }
            ]
          },
          {
            "token": " assist",
            "logprob": -0.04571125,
            "bytes": [32, 97, 115, 115, 105, 115, 116],
            "top_logprobs": [
              {
                "token": " assist",
                "logprob": -0.04571125,
                "bytes": [32, 97, 115, 115, 105, 115, 116]
              },
              {
                "token": " help",
                "logprob": -3.1089056,
                "bytes": [32, 104, 101, 108, 112]
              }
            ]
          },
          {
            "token": " you",
            "logprob": -5.4385737e-6,
            "bytes": [32, 121, 111, 117],
            "top_logprobs": [
              {
                "token": " you",
                "logprob": -5.4385737e-6,
                "bytes": [32, 121, 111, 117]
              },
              {
                "token": " today",
                "logprob": -12.807695,
                "bytes": [32, 116, 111, 100, 97, 121]
              }
            ]
          },
          {
            "token": " today",
            "logprob": -0.0040071653,
            "bytes": [32, 116, 111, 100, 97, 121],
            "top_logprobs": [
              {
                "token": " today",
                "logprob": -0.0040071653,
                "bytes": [32, 116, 111, 100, 97, 121]
              },
              {
                "token": "?",
                "logprob": -5.5247097,
                "bytes": [63]
              }
            ]
          },
          {
            "token": "?",
            "logprob": -0.0008108172,
            "bytes": [63],
            "top_logprobs": [
              {
                "token": "?",
                "logprob": -0.0008108172,
                "bytes": [63]
              },
              {
                "token": "?\n",
                "logprob": -7.184561,
                "bytes": [63, 10]
              }
            ]
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 9,
    "total_tokens": 18,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": null
}

📮 請求

端點

POST /v1/chat/completions

建立給定聊天對話的模型響應。更多詳情請參閱文字生成、視覺和音訊指南。

鑑權方法

在請求頭中包含以下內容進行 API 金鑰認證：

Authorization: Bearer $API_KEY

其中 $API_KEY 是您的 API 金鑰。您可以在 OpenAI 平臺的 API 金鑰頁面中找到或生成 API 金鑰。

請求體引數

messages

  • 型別：陣列
  • 必需：是

到目前為止包含對話的訊息列表。根據使用的模型，支援不同的訊息型別（形式），如文字、影象和音訊。

訊息型別描述
Developer message開發者提供的指令，模型應遵循這些指令，無論使用者傳送什麼訊息。在 o1 模型及更新版本中，開發者訊息取代了之前的系統訊息。
System message開發者提供的指令，模型應遵循這些指令，無論使用者傳送什麼訊息。在 o1 模型及更新版本中，請使用開發者訊息代替。
User message由終端使用者傳送的訊息，包含提示或額外的上下文資訊。
Assistant message模型響應使用者訊息傳送的訊息。
Tool message工具訊息的內容。
Function message已棄用。

Developer message 屬性：

屬性型別必需描述
role字串是訊息作者的角色，此處為 developer。
content字串或陣列是開發者訊息的內容。可以是文字內容（字串）或內容部分陣列。
name字串否參與者的可選名稱。為模型提供資訊以區分相同角色的參與者。

System message 屬性：

屬性型別必需描述
role字串是訊息作者的角色，此處為 system。
content字串或陣列是系統訊息的內容。可以是文字內容（字串）或內容部分陣列。
name字串否參與者的可選名稱。為模型提供資訊以區分相同角色的參與者。

User message 屬性：

屬性型別必需描述
role字串是訊息作者的角色，此處為 user。
content字串或陣列是使用者訊息的內容。可以是文字內容（字串）或內容部分陣列。
name字串否參與者的可選名稱。為模型提供資訊以區分相同角色的參與者。

內容部分型別：

內容部分型別描述可用於
文字內容部分文字輸入。所有訊息型別
影象內容部分影象輸入。使用者訊息
音訊內容部分音訊輸入。使用者訊息
檔案內容部分檔案輸入，用於文字生成。使用者訊息
拒絕內容部分模型生成的拒絕訊息。助手訊息

文字內容部分屬性：

屬性型別必需描述
text字串是文字內容。
type字串是內容部分的型別。

影象內容部分屬性：

屬性型別必需描述
image_url物件是包含影象URL或base64編碼的影象資料。
type字串是內容部分的型別。

影象URL物件屬性：

屬性型別必需描述
url字串是影象的URL或base64編碼的影象資料。
detail字串否指定影象的詳細級別。預設為 auto。

音訊內容部分屬性：

屬性型別必需描述
input_audio物件是包含音訊資料的物件。
type字串是內容部分的型別。始終為 input_audio。

音訊輸入物件屬性：

屬性型別必需描述
data字串是base64編碼的音訊資料。
format字串是編碼音訊資料的格式。當前支援 "wav" 和 "mp3"。

檔案內容部分屬性：

屬性型別必需描述
file物件是包含檔案資料的物件。
type字串是內容部分的型別。始終為 file。

檔案物件屬性：

屬性型別必需描述
file_data字串否base64編碼的檔案資料，用於將檔案作為字串傳遞給模型。
file_id字串否已上傳檔案的ID，用作輸入。
filename字串否檔名，用於將檔案作為字串傳遞給模型。

Assistant message 屬性：

屬性型別必需描述
role字串是訊息作者的角色，此處為 assistant。
content字串或陣列否助手訊息的內容。除非指定了 tool_calls 或 function_call，否則為必需。
name字串否參與者的可選名稱。為模型提供資訊以區分相同角色的參與者。
audio物件或null否關於模型先前音訊響應的資料。
function_call物件或null否已棄用，由 tool_calls 替代。應呼叫的函式的名稱和引數，由模型生成。
tool_calls陣列否模型生成的工具呼叫，如函式呼叫。
refusal字串或null否助手的拒絕訊息。

Tool message 屬性：

屬性型別必需描述
role字串是訊息作者的角色，此處為 tool。
content字串或陣列是工具訊息的內容。
tool_call_id字串是此訊息響應的工具呼叫。

Function message 屬性：（已棄用）

屬性型別必需描述
role字串是訊息作者的角色，此處為 function。
content字串或null是函式訊息的內容。
name字串是要呼叫的函式的名稱。

model

  • 型別：字串
  • 必需：是

要使用的模型 ID。有關哪些模型適用於 Chat API 的詳細資訊，請參閱模型端點相容性表。

store

  • 型別：布林值或 null
  • 必需：否
  • 預設值：false

是否儲存此聊天補全請求的輸出以用於我們的模型蒸餾或評估產品。

reasoning_effort

  • 型別：字串或 null
  • 必需：否
  • 預設值：medium
  • 僅適用於 o系列 的模型

約束推理模型的推理工作。當前支援的值為 low、medium 和 high。減少推理工作可以加快響應速度並減少響應中用於推理的標記數。

metadata

  • 型別：map
  • 必需：否

可以附加到物件的16個鍵值對集合。這對於以結構化格式儲存物件的其他資訊很有用,並可以透過 API 或儀表板查詢物件。

鍵是最大長度為64個字元的字串。值是最大長度為512個字元的字串。

modalities

  • 型別：陣列或 null
  • 必需：否

您希望模型為此請求生成的輸出型別。大多數模型都能生成文字,這是預設設定: ["text"]

該模型還可以用於生成音訊。要請求此模型同時生成文字和音訊響應,您可以使用: ["text", "audio"]

prediction

  • 型別：物件
  • 必需：否

預測輸出的配置,當提前知道模型響應的大部分內容時,可以大大提高響應時間。這在您只對檔案進行微小更改時最常見。

可能的型別：

型別描述
靜態內容靜態預測輸出內容，例如正在重新生成的具有微小更改的文字檔案內容。

靜態內容屬性：

屬性型別必需描述
content字串或陣列是生成模型響應時應匹配的內容。如果生成的標記與此內容匹配，則整個模型響應可以更快地返回。
type字串是要提供的預測內容型別。當前型別始終為 content。

內容可能的型別：

  1. 文字內容（字串） - 用於預測輸出的內容。這通常是您正在重新生成的檔案的文字，只有微小更改。

  2. 內容部分陣列（陣列） - 具有定義型別的內容部分陣列。支援的選項因用於生成響應的模型而異。可以包含文字輸入。

內容部分陣列屬性：

屬性型別必需描述
text字串是文字內容。
type字串是內容部分的型別。

audio

  • 型別：物件或 null
  • 必需：否

音訊輸出的引數。當使用 modalities: ["audio"] 請求音訊輸出時需要。

屬性型別必需描述
format字串是指定輸出音訊格式。必須是以下之一：wav、mp3、flac、opus 或 pcm16。
voice字串是模型用於響應的聲音。支援的聲音包括：alloy、ash、ballad、coral、echo、fable、nova、onyx、sage 和 shimmer。

temperature

  • 型別：數字或 null
  • 必需：否
  • 預設值：1

要使用的取樣溫度，介於 0 和 2 之間。較高的值（如0.8）會使輸出更加隨機，而較低的值（如0.2）會使其更加集中和確定性。我們通常建議更改此值或 top_p，但不要同時更改。

top_p

  • 型別：數字或 null
  • 必需：否
  • 預設值：1

一種替代取樣溫度的方法，稱為核取樣，其中模型考慮具有 top_p 機率質量的標記結果。因此，0.1 意味著只考慮包含前 10% 機率質量的標記。

我們通常建議更改此值或 temperature，但不要同時更改。

n

  • 型別：整數或 null
  • 必需：否
  • 預設值：1

為每個輸入訊息生成多少個聊天補全選擇。請注意，您將根據所有選擇生成的標記數量收費。保持 n 為 1 可最大限度地降低成本。

stop

  • 型別：字串/陣列/null
  • 必需：否
  • 預設值：null
  • 不支援最新的推理模型和 .o3、o4-mini

API 將停止生成更多標記的最多 4 個序列。返回的文字不會包含停止序列。

max_tokens

  • 型別：整數或 null
  • 必需：否

聊天補全中可以生成的最大標記數。此值可用於控制透過 API 生成的文字成本。

該值現已棄用，取而代之的是 max_completion_tokens，並且與 o1 系列模型不相容。

max_completion_tokens

  • 型別：整數或 null
  • 必需：否

補全中可以生成的標記數的上限，包括可見輸出標記和推理標記。

presence_penalty

  • 型別：數字或 null
  • 必需：否
  • 預設值：0

介於 -2.0 和 2.0 之間的數字。正值根據新標記到目前為止在文字中出現的情況來懲罰它們，從而增加模型討論新主題的可能性。

frequency_penalty

  • 型別：數字或 null
  • 必需：否
  • 預設值：0

介於 -2.0 和 2.0 之間的數字。正值根據新標記到目前為止在文字中的現有頻率來懲罰它們，從而降低模型逐字重複同一行的可能性。

logit_bias

  • 型別：map
  • 必需：否
  • 預設值：null

修改指定標記出現在補全中的可能性。

接受一個 JSON 物件，該物件將標記（由分詞器中的標記 ID 指定）對映到從 -100 到 100 的關聯偏差值。在數學上，偏差被新增到模型在取樣之前生成的對數中。確切的效果會因模型而異，但介於 -1 和 1 之間的值應該會減少或增加選擇的可能性；像 -100 或 100 這樣的值應該導致相關標記被禁止或獨佔選擇。

logprobs

  • 型別：布林值或 null
  • 必需：否
  • 預設值：false

是否返回輸出標記的對數機率。如果為 true，則返回 message.content 中每個輸出標記的對數機率。

user

  • 型別：字串
  • 必需：否

表示終端使用者的唯一識別符號，可以幫助 OpenAI 監控和檢測濫用行為。瞭解更多。

service_tier

  • 型別：字串或 null
  • 必需：否
  • 預設值：auto

指定用於處理請求的延遲層級。此引數與訂閱了 scale tier 服務的客戶相關：

  • 如果設定為 'auto'，且專案啟用了 Scale tier，系統將使用 scale tier 信用直到用完
  • 如果設定為 'auto'，且專案未啟用 Scale tier，請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證
  • 如果設定為 'default'，請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證
  • 如果設定為 'flex'，請求將使用 Flex Processing 服務層級處理。詳情請參閱文件。
  • 未設定時，預設行為為 'auto'
  • 當設定此引數時，響應體將包含使用的 service_tier

stream_options

  • 型別：物件或 null
  • 必需：否
  • 預設值：null

流式響應的選項。僅在設定 stream: true 時使用。

可能的屬性：

屬性型別必需描述
include_usage布林值否如果設定，將在 data: [DONE] 訊息之前流式傳輸一個附加塊。該塊上的 usage 欄位顯示整個請求的令牌使用統計資訊，choices 欄位始終為空陣列。所有其他塊也將包含 usage 欄位，但值為 null。注意：如果流被中斷，您可能不會收到包含請求總令牌使用量的最終使用塊。

response_format

  • 型別：物件
  • 必需：否

指定模型必須輸出的格式。

  • 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型將匹配您提供的 JSON schema。
  • 設定為 { "type": "json_object" } 啟用 JSON 模式，確保模型生成的訊息是有效的 JSON。

重要提示：使用 JSON 模式時，您還必須透過系統或使用者訊息自行指示模型生成 JSON。否則，模型可能會生成無盡的空白直到生成達到令牌限制。

可能的型別：

型別描述
text預設響應格式。用於生成文字響應。
json_schemaJSON Schema 響應格式。用於生成結構化 JSON 響應。瞭解更多關於結構化輸出的資訊。
json_objectJSON 物件響應格式。一種較老的生成 JSON 響應的方法。對於支援的模型，推薦使用 json_schema。

text 屬性：

屬性型別必需描述
type字串是正在定義的響應格式型別。始終為 text。

json_schema 屬性：

屬性型別必需描述
json_schema物件是結構化輸出配置選項，包括 JSON Schema。
type字串是正在定義的響應格式型別。始終為 json_schema。

json_schema.json_schema 屬性：

屬性型別必需描述
name字串是響應格式的名稱。必須是 a-z、A-Z、0-9 或包含下劃線和破折號，最大長度為 64。
description字串否響應格式的用途描述，模型用它來確定如何以該格式響應。
schema物件否響應格式的架構，描述為 JSON Schema 物件。
strict布林值或 null否是否在生成輸出時啟用嚴格架構遵守。如果設定為 true，模型將始終遵循 schema 欄位中定義的確切架構。strict 為 true 時，僅支援 JSON Schema 的子集。

json_object 屬性：

屬性型別必需描述
type字串是正在定義的響應格式型別。始終為 json_object。

seed

  • 型別：整數或 null
  • 必需：否 Beta 功能。如果指定，我們的系統將盡最大努力進行確定性取樣，使得具有相同 seed 和引數的重複請求應返回相同的結果。不保證確定性，您應參考響應引數的 system_fingerprint 以監控後端的變化。

tools

  • 型別：陣列
  • 必需：否

模型可能呼叫的工具列表。目前僅支援函式作為工具。使用此引數提供模型可能生成 JSON 輸入的函式列表。最多支援 128 個函式。

屬性：

屬性型別必需描述
function物件是要呼叫的函式資訊
type字串是工具的型別。目前，僅支援 function。

function 屬性：

屬性型別必需描述
name字串是要呼叫的函式名稱。必須是a-z、A-Z、0-9，或包含下劃線和破折號，最大長度為64。
description字串否函式功能的描述，模型用它來選擇何時以及如何呼叫函式。
parameters物件否函式接受的引數，描述為JSON Schema物件。請參閱指南獲取示例，以及JSON Schema參考瞭解格式文件。省略parameters定義一個空引數列表的函式。
strict布林值或 null否預設值：false。是否在生成函式呼叫時啟用嚴格架構遵守。如果設定為 true，模型將遵循 parameters 欄位中定義的確切架構。strict 為 true 時，僅支援 JSON Schema 的子集。詳情請參閱函式呼叫指南中的結構化輸出部分。

functions

  • 型別：陣列
  • 必需：否
  • 注意：已棄用，推薦使用 tools

模型可能生成 JSON 輸入的函式列表。

屬性型別必需描述
name字串是要呼叫的函式名稱。必須是a-z、A-Z、0-9，或包含下劃線和破折號，最大長度為64。
description字串否函式功能的描述，模型用它來選擇何時以及如何呼叫函式。
parameters物件否函式接受的引數，描述為JSON Schema物件。省略parameters定義一個空引數列表的函式。

tool_choice

  • 型別：字串或物件
  • 必需：否

控制模型呼叫哪個工具（如果有）：

  • none：模型不會呼叫任何工具，而是生成訊息
  • auto：模型可以在生成訊息或呼叫一個或多個工具之間選擇
  • required：模型必須呼叫一個或多個工具
  • {"type": "function", "function": {"name": "my_function"}}：強制模型呼叫特定工具

當沒有工具時預設為 none，有工具時預設為 auto。

可能的型別：

型別描述
字串none 表示模型不會呼叫任何工具，而是生成訊息。auto 表示模型可以在生成訊息或呼叫一個或多個工具之間選擇。required 表示模型必須呼叫一個或多個工具。
物件指定模型應使用的工具。用於強制模型呼叫特定函式。

物件屬性：

屬性型別必需描述
function物件是包含函式資訊的物件
type字串是工具的型別。目前，僅支援 function。

function 屬性：

屬性型別必需描述
name字串是要呼叫的函式名稱。

function_call

  • 型別：字串或物件
  • 必需：否
  • 預設值：沒有函式時為 none，有函式時為 auto
  • 注意：已棄用，推薦使用 tool_choice

控制模型呼叫哪個函式（如果有）：

  • none：模型不會呼叫函式，而是生成訊息
  • auto：模型可以在生成訊息或呼叫函式之間選擇
  • {"name": "my_function"}：強制模型呼叫特定函式

物件型別屬性：

屬性型別必需描述
name字串是要呼叫的函式名稱。

parallel_tool_calls

  • 型別：布林值
  • 必需：否
  • 預設值：true

是否在工具使用期間啟用並行函式呼叫。

stream

  • 型別：布林值或 null
  • 必需：否
  • 預設值：false

如果設定為 true，模型響應資料將在生成時透過伺服器傳送事件流式傳輸到客戶端。請參閱下方的流式響應部分獲取更多資訊，以及流式響應指南瞭解如何處理流式事件。

top_logprobs

  • 型別：整數或 null
  • 必需：否

0 到 20 之間的整數，指定在每個標記位置返回的最可能標記的數量，每個標記都有關聯的對數機率。如果使用此引數，必須將 logprobs 設定為 true。

web_search_options

  • 型別：物件
  • 必需：否

此工具搜尋網路以獲取相關結果用於回覆。瞭解更多關於網路搜尋工具的資訊。

可能的屬性：

屬性型別必需描述
search_context_size字串否預設值：medium。用於搜尋的上下文視窗空間量的高階指導。可選值為 low、medium 或 high。medium 是預設值。
user_location物件或 null否搜尋的近似位置引數。

user_location 屬性：

屬性型別必需描述
approximate物件是搜尋的近似位置引數。

approximate 屬性：

屬性型別必需描述
city字串否使用者城市的自由文字輸入，例如 San Francisco。
country字串否使用者的兩字母 ISO 國家程式碼，例如 US。
region字串否使用者地區的自由文字輸入，例如 California。
timezone字串否使用者的 IANA 時區，例如 America/Los_Angeles。
type字串是位置近似型別。始終為 approximate。

📥 響應

聊天補全物件

返回一個聊天補全物件,如果請求被流式傳輸,則返回聊天補全塊物件的流式序列。

id

  • 型別：字串
  • 說明：響應的唯一識別符號

object

  • 型別：字串
  • 說明：物件型別,值為 "chat.completion"

created

  • 型別：整數
  • 說明：響應建立時間戳

model

  • 型別：字串
  • 說明：使用的模型名稱

system_fingerprint

  • 型別：字串
  • 說明：系統指紋識別符號，表示模型執行的後端配置。可以與seed請求引數一起使用，以瞭解何時進行了可能影響確定性的後端更改。

choices

  • 型別：陣列
  • 說明：包含生成的回覆選項列表。如果 n 大於 1，則可以有多個選項。
  • 屬性:
    • index: 選項在選項列表中的索引。
    • message: 模型生成的聊天補全訊息。
      • role: 訊息作者的角色。
      • content: 訊息的內容，可能為 null。
      • refusal: 模型生成的拒絕訊息，可能為 null。
      • annotations: 訊息的註釋，在適用時提供，例如使用網路搜尋工具時。
        • type: 註釋型別，URL引用時始終為 "url_citation"。
        • url_citation: 使用網路搜尋時的URL引用。
          • start_index: URL引用在訊息中的第一個字元的索引。
          • end_index: URL引用在訊息中的最後一個字元的索引。
          • url: 網路資源的URL。
          • title: 網路資源的標題。
      • audio: 如果請求了音訊輸出模態，此物件包含來自模型的音訊響應的資料。
        • data: 模型生成的Base64編碼音訊位元組，格式在請求中指定。
        • id: 此音訊響應的唯一識別符號。
        • transcript: 模型生成的音訊的轉錄。
        • expires_at: 此音訊響應在伺服器上可用於多輪對話的Unix時間戳（秒）。
      • function_call: （已棄用）應呼叫的函式的名稱和引數，由模型生成。已被 tool_calls 替代。
        • name: 要呼叫的函式的名稱。
        • arguments: 用於呼叫函式的引數，由模型以JSON格式生成。
      • tool_calls: 模型生成的工具呼叫，如函式呼叫。
        • id: 工具呼叫的ID。
        • type: 工具的型別。目前，僅支援 function。
        • function: 模型呼叫的函式。
          • name: 要呼叫的函式的名稱。
          • arguments: 用於呼叫函式的引數，由模型以JSON格式生成。注意，模型並不總是生成有效的JSON，並且可能會產生您函式架構中未定義的引數。在呼叫函式之前，請在程式碼中驗證引數。
    • logprobs: 對數機率資訊。
      • content: 帶有對數機率資訊的訊息內容標記列表。
        • token: 標記。
        • logprob: 此標記的對數機率，如果它在前20個最可能的標記內。否則，使用-9999.0的值表示此標記非常不可能。
        • bytes: 表示標記的UTF-8位元組表示的整數列表。在字元由多個標記表示且必須組合它們的位元組表示以生成正確的文字表示的情況下很有用。如果標記沒有位元組表示，則可能為null。
        • top_logprobs: 在此標記位置上最可能的標記及其對數機率的列表。在罕見情況下，返回的top_logprobs數量可能少於請求的數量。
      • refusal: 帶有對數機率資訊的訊息拒絕標記列表。
    • finish_reason: 模型停止生成標記的原因。如果模型到達自然停止點或提供的停止序列，則為 "stop"；如果達到請求中指定的最大標記數，則為 "length"；如果由於內容過濾器標記而省略內容，則為 "content_filter"；如果模型呼叫了工具，則為 "tool_calls"；如果模型呼叫了函式，則為 "function_call"（已棄用）。

usage

  • 型別：物件
  • 說明：補全請求的使用統計資訊。
  • 屬性:
    • prompt_tokens: 提示中的標記數。
    • completion_tokens: 生成的補全中的標記數。
    • total_tokens: 請求中使用的標記總數（提示 + 補全）。
    • prompt_tokens_details: 提示中使用的標記的細分。
      • cached_tokens: 提示中存在的快取標記。
      • audio_tokens: 提示中存在的音訊輸入標記。
    • completion_tokens_details: 補全中使用的標記的細分。
      • reasoning_tokens: 模型生成的推理標記。
      • audio_tokens: 模型生成的音訊標記。
      • accepted_prediction_tokens: 使用預測輸出時，預測中出現在補全中的標記數。
      • rejected_prediction_tokens: 使用預測輸出時，預測中未出現在補全中的標記數。但是，與推理標記一樣，這些標記仍計入計費、輸出和上下文視窗限制的總補全標記中。

service_tier

  • 型別：字串或 null
  • 說明：指定用於處理請求的延遲層級。此引數與訂閱了 scale tier 服務的客戶相關：
    • 如果設定為 'auto'，且專案啟用了 Scale tier，系統將使用 scale tier 信用直到用完
    • 如果設定為 'auto'，且專案未啟用 Scale tier，請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證
    • 如果設定為 'default'，請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證
    • 如果設定為 'flex'，請求將使用 Flex Processing 服務層級處理
    • 未設定時，預設行為為 'auto'
    • 當設定此引數時，響應體將包含使用的 service_tier

聊天補全物件響應示例

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "圖片展示了一條穿過茂密綠色草地或草甸的木製棧道。天空湛藍，點綴著幾朵散落的雲彩，給整個場景營造出寧靜祥和的氛圍。背景中可以看到樹木和灌木叢。",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "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
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

聊天補全列表物件

當返回多個聊天補全時，API 可能會返回聊天補全列表物件。

object

  • 型別：字串
  • 說明：物件型別，始終為 "list"

data

  • 型別：陣列
  • 說明：聊天補全物件的陣列

first_id

  • 型別：字串
  • 說明：資料陣列中第一個聊天補全的識別符號

last_id

  • 型別：字串
  • 說明：資料陣列中最後一個聊天補全的識別符號

has_more

  • 型別：布林值
  • 說明：表示是否有更多聊天補全可用

聊天補全列表響應示例

{
  "object": "list",
  "data": [
    {
      "object": "chat.completion",
      "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
      "model": "gpt-4o-2024-08-06",
      "created": 1738960610,
      "request_id": "req_ded8ab984ec4bf840f37566c1011c417",
      "tool_choice": null,
      "usage": {
        "total_tokens": 31,
        "completion_tokens": 18,
        "prompt_tokens": 13
      },
      "seed": 4944116822809979520,
      "top_p": 1.0,
      "temperature": 1.0,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0,
      "system_fingerprint": "fp_50cad350e4",
      "input_user": null,
      "service_tier": "default",
      "tools": null,
      "metadata": {},
      "choices": [
        {
          "index": 0,
          "message": {
            "content": "電路之心低吟，\n在寂靜中學習模式—\n未來的寧靜火花。",
            "role": "assistant",
            "tool_calls": null,
            "function_call": null
          },
          "finish_reason": "stop",
          "logprobs": null
        }
      ],
      "response_format": null
    }
  ],
  "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
  "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
  "has_more": false
}

聊天補全訊息列表物件

聊天補全訊息列表物件表示聊天訊息的列表。

object

  • 型別：字串
  • 說明：物件型別，始終為 "list"

data

  • 型別：陣列
  • 說明：聊天補全訊息物件的陣列，每個訊息物件包含以下屬性：
    • id: 聊天訊息的識別符號
    • role: 訊息作者的角色
    • content: 訊息的內容，可能為 null
    • name: 訊息傳送者的名稱，可能為 null
    • refusal: 模型生成的拒絕訊息，可能為 null
    • annotations: 訊息的註釋，在適用時提供，例如使用網路搜尋工具時
      • type: 註釋型別，URL引用時始終為 "url_citation"
      • url_citation: 使用網路搜尋時的URL引用
        • start_index: URL引用在訊息中的第一個字元的索引
        • end_index: URL引用在訊息中的最後一個字元的索引
        • url: 網路資源的URL
        • title: 網路資源的標題
    • audio: 如果請求了音訊輸出模態，此物件包含來自模型的音訊響應的資料
      • data: 模型生成的Base64編碼音訊位元組，格式在請求中指定
      • id: 此音訊響應的唯一識別符號
      • transcript: 模型生成的音訊的轉錄
      • expires_at: 此音訊響應在伺服器上可用於多輪對話的Unix時間戳（秒）
    • function_call: （已棄用）應呼叫的函式的名稱和引數，由模型生成。已被 tool_calls 替代
      • name: 要呼叫的函式的名稱
      • arguments: 用於呼叫函式的引數，由模型以JSON格式生成
    • tool_calls: 模型生成的工具呼叫，如函式呼叫
      • id: 工具呼叫的ID
      • type: 工具的型別。目前，僅支援 function
      • function: 模型呼叫的函式
        • name: 要呼叫的函式的名稱
        • arguments: 用於呼叫函式的引數，由模型以JSON格式生成

first_id

  • 型別：字串
  • 說明：資料陣列中第一個聊天訊息的識別符號

last_id

  • 型別：字串
  • 說明：資料陣列中最後一個聊天訊息的識別符號

has_more

  • 型別：布林值
  • 說明：表示是否有更多聊天訊息可用

聊天補全訊息列表響應示例

{
  "object": "list",
  "data": [
    {
      "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
      "role": "user",
      "content": "寫一首關於人工智慧的俳句",
      "name": null,
      "content_parts": null
    }
  ],
  "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
  "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
  "has_more": false
}

OpenAI 響應格式（Responses）

下一頁

目錄

📝 簡介
💡 請求示例
基礎文字對話 ✅
影象分析對話 ✅
流式響應 ✅
函式呼叫 ✅
Logprobs 請求 ✅
📮 請求
端點
鑑權方法
請求體引數
messages
model
store
reasoning_effort
metadata
modalities
prediction
audio
temperature
top_p
n
stop
max_tokens
max_completion_tokens
presence_penalty
frequency_penalty
logit_bias
logprobs
user
service_tier
stream_options
response_format
seed
tools
functions
tool_choice
function_call
parallel_tool_calls
stream
top_logprobs
web_search_options
📥 響應
聊天補全物件
id
object
created
model
system_fingerprint
choices
usage
service_tier
聊天補全物件響應示例
聊天補全列表物件
object
data
first_id
last_id
has_more
聊天補全列表響應示例
聊天補全訊息列表物件
object
data
first_id
last_id
has_more
聊天補全訊息列表響應示例