Microsoft Foundry 模型預覽版的 Azure OpenAI REST API 參考資料

本文詳細介紹了 Azure OpenAI 的推論 REST API 端點。

API specs

管理與互動 Azure OpenAI 模型與資源分為三大主要 API 介面：

• Control plane
• 資料平面 - 著述
• 資料平面 - 推論

每個 API 表面/規範都封裝了一組不同的 Azure OpenAI 能力。 每個 API 都有其獨特的預覽版及穩定/一般可用（GA）API 版本。 預覽版目前通常以每月更新為準。

Important

現在有一個新的預覽推論 API。 想了解更多，請參閱我們的 API 生命週期指南。

API	最新預覽發布	最新 GA 發行	Specifications	Description
Control plane	2025-07-01-preview	2025-06-01	Spec files	控制平面 API 用於 建立資源、 模型部署及其他高階資源管理任務等操作。 控制平面也規範了像 Azure Resource Manager、Bicep、Terraform 和 Azure CLI 這類功能能做什麼。
Data plane	v1 preview	v1	Spec files	資料平面 API 控制推理與撰寫操作。

Authentication

Azure OpenAI 提供兩種認證方法。 你可以使用 API 金鑰或 Microsoft Entra ID。

• API 金鑰認證：此類型驗證中，所有 API 請求必須在 api-key HTTP 標頭中包含 API 金鑰。 快速入門指南提供了如何使用此類認證打電話的指引。

• Microsoft Entra ID 認證：你可以使用 Microsoft Entra 令牌來驗證 API 呼叫。 認證憑證作為標頭包含在請求 Authorization 中。 所提供的標記必須前置 Bearer，例如 Bearer YOUR_AUTH_TOKEN。 你可以閱讀我們關於 使用 Microsoft Entra ID 認證的操作指南。

REST API 版本管理

服務 API 會透過 api-version 查詢參數來進行版本控制。 所有版本皆遵循 YYYY -MM-DD 日期結構。 For example:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-06-01

資料平面推論

文章其餘部分將介紹 2025-04-01-preview Azure OpenAI 資料平面推論規範的預覽版本。

如果你在找最新 GA API 版本的文件，請參考 最新的 GA 資料平面推論 API

完成 - 創建

POST https://{endpoint}/openai/deployments/{deployment-id}/completions?api-version=2025-04-01-preview

為所提供的提示詞、參數及所選模型建立補全。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
best_of	整數	在 best_of 伺服器端產生完成項目，並回傳「最佳」（每個標記日誌機率最高的完成）。 結果無法直播。 當與 一起使用 n時 best_of ，控制候選完成數，並 n 指定回傳 À¢â'¬â€œ best_of 的數量必須大於 n。 註： 由於這個參數會產生許多完成任務，它可能會迅速消耗你的代幣配額。 謹慎使用，並確保你對 和 max_tokens的設定stop合理。	No	1
echo	boolean	除了完成題外，還要回敬提示	No	False
frequency_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新標記在文本中現有的頻率來懲罰，降低模型逐字重複同一行的可能性。	No	0
logit_bias	物件	修改特定標記出現在完成項目中的可能性。 接受一個 JSON 物件，將 GPT 分名器中由 token ID 指定）映射到從 -100 到 100 的偏值。 數學上，偏誤會加到模型產生的對數值上，然後再抽樣。 具體效果因模型而異，但介於 -1 與1之間的數值應降低或增加選擇的可能性;像 -100 或 100 這類數值應該會導致封鎖或專屬選擇相關代幣。 舉例來說，你可以通過， {"50256": -100} 以防止 <|endoftext|> 標記被產生。	No	None
logprobs	整數	包含最可能輸出標記的對數機率 logprobs ，以及所選標記。 例如，若 logprobs 為 5，API 會回傳 5 個最可能的標記清單。 API 總是回傳取樣標記的 ， logprob 因此回應中可能包含最多的 logprobs+1 元素。 最大 logprobs 值為5。	No	None
max_tokens	整數	完成過程中可產生的最大代幣數量。 你的提示 max_tokens 詞的標記數不能超過模型的上下文長度。	No	16
n	整數	每個提示要產生多少個完成題。 註： 由於這個參數會產生許多完成任務，它可能會迅速消耗你的代幣配額。 謹慎使用，並確保你對 和 max_tokens的設定stop合理。	No	1
presence_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新代幣是否出現在文本中來懲罰，增加模型談論新主題的可能性。	No	0
提示	字串或陣列	生成完成函數的提示，編碼為字串、字串陣列、標記陣列或標記陣列。 請注意， <|endoftext|> 是模型在訓練時看到的文件分隔符，因此如果未指定提示詞，模型會像從新文件開始一樣產生。	Yes
seed	整數	若有指定，系統會盡力以確定性方式取樣，使得重複請求且參數相同 seed 時應返回相同結果。 確定性並非保證，你應該參考 system_fingerprint 回應參數來監控後端的變化。	No
stop	字串或陣列	最多有四個序列，API 會停止產生更多代幣。 回傳的文字不會包含停止音序列。	No
串流	boolean	是否要回溯部分進度。 若設定為 token，代幣會在伺服器有資料時以事件形式傳送，串流以訊息終止data: [DONE]。 範例 Python 程式碼。	No	False
suffix	字串	插入文字完成後的後綴。 此參數僅支援於 gpt-3.5-turbo-instruct。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更集中且具決定性。 我們通常建議改變這個或 top_p 兩者都做。	No	1
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	createCompletionResponse

狀態代碼： 預設

說明：無法提供服務

Content-Type	Type	Description
application/json	errorResponse

Examples

Example

為所提供的提示詞、參數及所選模型建立補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/completions?api-version=2025-04-01-preview

{
 "prompt": [
  "tell me a joke about mango"
 ],
 "max_tokens": 32,
 "temperature": 1.0,
 "n": 1
}

回應：狀態代碼：200

{
  "body": {
    "id": "cmpl-7QmVI15qgYVllxK0FtxVGG6ywfzaq",
    "created": 1686617332,
    "choices": [
      {
        "text": "es\n\nWhat do you call a mango who's in charge?\n\nThe head mango.",
        "index": 0,
        "finish_reason": "stop",
        "logprobs": null
      }
    ],
    "usage": {
      "completion_tokens": 20,
      "prompt_tokens": 6,
      "total_tokens": 26
    }
  }
}

嵌入 - 創建

POST https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version=2025-04-01-preview

取得一個能被機器學習模型和演算法輕鬆處理的給定輸入向量表示。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串	部署型號的部署ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
dimensions	整數	輸出嵌入應有的維度數。 僅支援於 text-embedding-3 及後期型號。	No
encoding_format	字串	格式是要將嵌入還回。 可以是 float 或 base64。 預設為 float。	No
輸入	字串或陣列	輸入文字嵌入，編碼為字串或標記陣列。 若要在同一請求中嵌入多個輸入，需傳遞一個字串陣列或標記陣列陣列。 輸入不得超過模型的最大輸入標記數（8,192個標記 text-embedding-ada-002），不能是空字串，且任何陣列的維度必須不超過2,048維或以下。	Yes
input_type	字串	輸入類型的嵌入搜尋	No
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控與偵測濫用行為。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	物件

Examples

Example

回傳給定提示的嵌入。

POST https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version=2025-04-01-preview

{
 "input": [
  "this is a test"
 ]
}

回應：狀態代碼：200

{
  "body": {
    "data": [
      {
        "index": 0,
        "embedding": [
          -0.012838088,
          -0.007421397,
          -0.017617522,
          -0.028278312,
          -0.018666342,
          0.01737855,
          -0.01821495,
          -0.006950092,
          -0.009937238,
          -0.038580645,
          0.010674067,
          0.02412286,
          -0.013647936,
          0.013189907,
          0.0021125758,
          0.012406612,
          0.020790534,
          0.00074595667,
          0.008397198,
          -0.00535031,
          0.008968075,
          0.014351576,
          -0.014086051,
          0.015055214,
          -0.022211088,
          -0.025198232,
          0.0065186154,
          -0.036350243,
          0.009180495,
          -0.009698266,
          0.009446018,
          -0.008463579,
          -0.0020113448
        ]
      }
    ],
    "usage": {
      "prompt_tokens": 4,
      "total_tokens": 4
    }
  }
}

聊天完成 - 創建

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

為聊天訊息建立一個完成

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
audio	物件	音訊輸出參數。 當音訊輸出被請求時 modalities: ["audio"]，必須 。	No
└─ format	列舉	指定輸出音訊格式。 必須是 wav、 mp3、 flac、 opus或 pcm16之一。 可能的值：wav， mp3， flacopuspcm16	No
└─ voice	列舉	指定聲音類型。 支援語態為 alloy、 echo、 fable、 onyxnovashimmer、 和 。 可能的值：alloy， echo， fableonyxnovashimmer	No
data_sources	陣列	使用 Azure OpenAI 聊天擴充功能的設定條目。 此額外規範僅與 Azure OpenAI 相容。	No
frequency_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新標記在文本中現有的頻率來懲罰，降低模型逐字重複同一行的可能性。	No	0
function_call	string 或 chatCompletionFunctionCallOption	已被棄用，改為 tool_choice。 控制模型呼叫哪個函式（若有的話）。 none 表示模型不會呼叫函式，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫函式。 指定特定函數 會 {"name": "my_function"} 迫使模型呼叫該函數。 none 當沒有函式存在時，是預設值。 auto 若函式存在，則為預設值。	No
functions	陣列	已被棄用，改為 tools。 模型可能產生 JSON 輸入的函數清單。	No
logit_bias	物件	修改特定標記出現在完成項目中的可能性。 接受一個 JSON 物件，將代幣（由代幣化器中由其 token ID 指定）映射到從 -100 到 100 的偏向值。 數學上，偏誤會加到模型產生的對數值上，然後再抽樣。 具體效果因模型而異，但介於 -1 與1之間的數值應降低或增加選擇的可能性;像 -100 或 100 這類數值應該會導致封鎖或專屬選擇相關代幣。	No	None
logprobs	boolean	是否要回傳輸出標記的對數機率。 若為真，則回傳每個輸出符號在 content 的 message對數機率。	No	False
max_completion_tokens	整數	完成化可產生的標記數量上限，包括可見輸出標記與推理標記。	No
max_tokens	整數	聊天完成時能產生的最大代幣數量。 輸入標記與產生標記的總長度受模型上下文長度限制。	No
messages	陣列	這是目前對話內容的清單。 範例 Python 程式碼。	Yes
中繼資料	物件	開發者定義的標籤與值，用於在儲存的完成儀表板中篩選完成事項。	No
modalities	ChatCompletionModalities	你希望模型為此請求產生的輸出類型。 大多數模型都能產生文字，這是預設的： ["text"] 該 gpt-4o-audio-preview 模型也可用於產生音訊。 若要請求此模型同時產生文字與音訊回應，您可以使用： ["text", "audio"]	No
n	整數	每則輸入訊息要產生多少個聊天結束選項。 你將根據所有選項中產生的代幣數量收費。 盡量降低n1成本。	No	1
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
預測	PredictionContent	預測輸出的配置，當模型響應的大部分部分事先已知時，能大幅改善反應時間。 這種情況最常見於你重新生成檔案時，內容大部分只做些微調整。	No
presence_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新代幣是否出現在文本中來懲罰，增加模型談論新主題的可能性。	No	0
reasoning_effort	列舉	僅限 O1 模型 限制推理模型的推理努力。 目前支援的值為 low、 medium、 high和 。 減少推理努力能帶來更快的回應，並減少回應中用於推理的標記。 可能的值： low， medium， high	No
response_format	ResponseFormatText 或 ResponseFormatJsonObject 或 ResponseFormatJsonSchema	一個指定模型必須輸出格式的物件。 相容於 GPT-4o、GPT-4o mini、GPT-4 Turbo 以及所有更新於 Tar 的 gpt-3.5-turbo-1106 Turbo 模型。 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型符合你提供的 JSON 架構。 設定啟用 { "type": "json_object" } JSON 模式，保證模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
seed	整數	此功能目前仍處於測試階段。 若有指定，系統會盡力以確定性方式取樣，使得重複請求且參數相同 seed 時應返回相同結果。 確定性並非保證，你應該參考 system_fingerprint 回應參數來監控後端的變化。	No
stop	字串或陣列	最多有 4 個序列，API 停止產生更多標記。	No
儲存	boolean	是否要儲存此聊天完成請求的輸出，以便用於我們的模型蒸餾或評估產品。	No
串流	boolean	若設定為此，會傳送部分訊息 delta，類似 ChatGPT 中的訊息。 代幣會以僅資料伺服器 發送的事件 形式發送，當事件可用時，串流會以訊息結束 data: [DONE] 。 範例 Python 程式碼。	No	False
stream_options	chatCompletionStreamOptions	串流回應選項。 只有在你設定 stream: true時才會設定這個。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更集中且具決定性。 我們通常建議改變這個或 top_p 兩者都做。	No	1
tool_choice	chatCompletionToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 這表示模型不會呼叫任何工具，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫一個或多個工具。 required 表示模型必須呼叫一個或多個工具。 指定特定工具 透過 會 {"type": "function", "function": {"name": "my_function"}} 強制模型呼叫該工具。 none 當沒有工具時，預設是。 auto 如果有工具，則是預設。	No
tools	陣列	模型可能呼叫的工具清單。 目前僅支援函式作為工具。 利用此資料提供模型可能產生 JSON 輸入的函式清單。 最多支援 128 個函式。	No
top_logprobs	整數	一個介於0到20之間的整數，表示每個標記位置最可能回傳的標記數量，每個標記具有對數機率。 logprobs 若使用此參數，必須設定為 true 。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No
user_security_context	userSecurityContext	使用者安全情境包含多個參數，描述 AI 應用程式本身及與 AI 應用程式互動的最終使用者。 這些領域協助您的資安營運團隊調查並減輕安全事件，提供全面的方法來保護您的 AI 應用。 了解更多 關於使用 適用於雲端的 Microsoft Defender 保護 AI 應用的方法。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	物件

狀態代碼： 預設

說明：無法提供服務

Content-Type	Type	Description
application/json	errorResponse

Examples

Example

為所提供的提示詞、參數及所選模型建立補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "system",
   "content": "you are a helpful assistant that talks like a pirate"
  },
  {
   "role": "user",
   "content": "can you tell me how to care for a parrot?"
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Ahoy matey! So ye be wantin' to care for a fine squawkin' parrot, eh? Well, shiver me timbers, let ol' Cap'n Assistant share some wisdom with ye! Here be the steps to keepin' yer parrot happy 'n healthy:\n\n1. Secure a sturdy cage: Yer parrot be needin' a comfortable place to lay anchor! Be sure ye get a sturdy cage, at least double the size of the bird's wingspan, with enough space to spread their wings, yarrrr!\n\n2. Perches 'n toys: Aye, parrots need perches of different sizes, shapes, 'n textures to keep their feet healthy. Also, a few toys be helpin' to keep them entertained 'n their minds stimulated, arrrh!\n\n3. Proper grub: Feed yer feathered friend a balanced diet of high-quality pellets, fruits, 'n veggies to keep 'em strong 'n healthy. Give 'em fresh water every day, or ye\u00e2\u20ac\u2122ll have a scurvy bird on yer hands!\n\n4. Cleanliness: Swab their cage deck! Clean their cage on a regular basis: fresh water 'n food daily, the floor every couple of days, 'n a thorough scrubbing ev'ry few weeks, so the bird be livin' in a tidy haven, arrhh!\n\n5. Socialize 'n train: Parrots be a sociable lot, arrr! Exercise 'n interact with 'em daily to create a bond 'n maintain their mental 'n physical health. Train 'em with positive reinforcement, treat 'em kindly, yarrr!\n\n6. Proper rest: Yer parrot be needin' \u00e2\u20ac\u2122bout 10-12 hours o' sleep each night. Cover their cage 'n let them slumber in a dim, quiet quarter for a proper night's rest, ye scallywag!\n\n7. Keep a weather eye open for illness: Birds be hidin' their ailments, arrr! Be watchful for signs of sickness, such as lethargy, loss of appetite, puffin' up, or change in droppings, and make haste to a vet if need be.\n\n8. Provide fresh air 'n avoid toxins: Parrots be sensitive to draft and pollutants. Keep yer quarters well ventilated, but no drafts, arrr! Be mindful of toxins like Teflon fumes, candles, or air fresheners.\n\nSo there ye have it, me hearty! With proper care 'n commitment, yer parrot will be squawkin' \"Yo-ho-ho\" for many years to come! Good luck, sailor, and may the wind be at yer back!"
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

根據 Azure Search 資料和系統指派的管理身份建立一個完成文件。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "azure_search",
   "parameters": {
    "endpoint": "https://your-search-endpoint.search.windows.net/",
    "index_name": "{index name}",
    "authentication": {
     "type": "system_assigned_managed_identity"
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content.",
                "title": "Citation Title",
                "filepath": "contoso.txt",
                "url": "https://contoso.blob.windows.net/container/contoso.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

根據 Azure Search 影像向量資料建立一個完成文件。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "azure_search",
   "parameters": {
    "endpoint": "https://your-search-endpoint.search.windows.net/",
    "index_name": "{index name}",
    "query_type": "vector",
    "fields_mapping": {
     "image_vector_fields": [
      "image_vector"
     ]
    },
    "authentication": {
     "type": "api_key",
     "key": "{api key}"
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion."
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

根據 Azure Search 向量資料、先前的助理訊息及使用者指派的管理身份建立完成文件。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a cat?"
  },
  {
   "role": "assistant",
   "content": "Content of the completion [doc1].",
   "context": {
    "intent": "cat care"
   }
  },
  {
   "role": "user",
   "content": "how about dog?"
  }
 ],
 "data_sources": [
  {
   "type": "azure_search",
   "parameters": {
    "endpoint": "https://your-search-endpoint.search.windows.net/",
    "authentication": {
     "type": "user_assigned_managed_identity",
     "managed_identity_resource_id": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
    },
    "index_name": "{index name}",
    "query_type": "vector",
    "embedding_dependency": {
     "type": "deployment_name",
     "deployment_name": "{embedding deployment name}"
    },
    "in_scope": true,
    "top_n_documents": 5,
    "strictness": 3,
    "role_information": "You are an AI assistant that helps people find information.",
    "fields_mapping": {
     "content_fields_separator": "\\n",
     "content_fields": [
      "content"
     ],
     "filepath_field": "filepath",
     "title_field": "title",
     "url_field": "url",
     "vector_fields": [
      "contentvector"
     ]
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content 2.",
                "title": "Citation Title 2",
                "filepath": "contoso2.txt",
                "url": "https://contoso.blob.windows.net/container/contoso2.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

為提供的 Azure Cosmos 資料庫建立一個補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "azure_cosmos_db",
   "parameters": {
    "authentication": {
     "type": "connection_string",
     "connection_string": "mongodb+srv://rawantest:{password}$@{cluster-name}.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"
    },
    "database_name": "vectordb",
    "container_name": "azuredocs",
    "index_name": "azuredocindex",
    "embedding_dependency": {
     "type": "deployment_name",
     "deployment_name": "{embedding deployment name}"
    },
    "fields_mapping": {
     "content_fields": [
      "content"
     ],
     "vector_fields": [
      "contentvector"
     ]
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content.",
                "title": "Citation Title",
                "filepath": "contoso.txt",
                "url": "https://contoso.blob.windows.net/container/contoso.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

為所提供的 Mongo 資料庫建立補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "mongo_db",
   "parameters": {
    "authentication": {
     "type": "username_and_password",
     "username": "<username>",
     "password": "<password>"
    },
    "endpoint": "<endpoint_name>",
    "app_name": "<application name>",
    "database_name": "sampledb",
    "collection_name": "samplecollection",
    "index_name": "sampleindex",
    "embedding_dependency": {
     "type": "deployment_name",
     "deployment_name": "{embedding deployment name}"
    },
    "fields_mapping": {
     "content_fields": [
      "content"
     ],
     "vector_fields": [
      "contentvector"
     ]
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content.",
                "title": "Citation Title",
                "filepath": "contoso.txt",
                "url": "https://contoso.blob.windows.net/container/contoso.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

為所提供的 Elasticsearch 建立一個補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "elasticsearch",
   "parameters": {
    "endpoint": "https://your-elasticsearch-endpoint.eastus.azurecontainer.io",
    "index_name": "{index name}",
    "authentication": {
     "type": "key_and_key_id",
     "key": "{key}",
     "key_id": "{key id}"
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content.",
                "title": "Citation Title",
                "filepath": "contoso.txt",
                "url": "https://contoso.blob.windows.net/container/contoso.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

Example

為所提供的 Pinecone 資源建立補全。

POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2025-04-01-preview

{
 "messages": [
  {
   "role": "user",
   "content": "can you tell me how to care for a dog?"
  }
 ],
 "data_sources": [
  {
   "type": "pinecone",
   "parameters": {
    "authentication": {
     "type": "api_key",
     "key": "{api key}"
    },
    "environment": "{environment name}",
    "index_name": "{index name}",
    "embedding_dependency": {
     "type": "deployment_name",
     "deployment_name": "{embedding deployment name}"
    },
    "fields_mapping": {
     "title_field": "title",
     "url_field": "url",
     "filepath_field": "filepath",
     "content_fields": [
      "content"
     ],
     "content_fields_separator": "\n"
    }
   }
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn",
    "created": 1686676106,
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "Content of the completion [doc1].",
          "context": {
            "citations": [
              {
                "content": "Citation content.",
                "title": "Citation Title",
                "filepath": "contoso.txt",
                "url": "https://contoso.blob.windows.net/container/contoso.txt",
                "chunk_id": "0"
              }
            ],
            "intent": "dog care"
          }
        }
      }
    ],
    "usage": {
      "completion_tokens": 557,
      "prompt_tokens": 33,
      "total_tokens": 590
    }
  }
}

轉錄 - 建立

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2025-04-01-preview

將音訊轉錄成輸入語言。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: multipart/form-data

Name	類型	Description	Required	Default
型號	字串	要用的型號識別碼。 選項為 gpt-4o-transcribe、 gpt-4o-mini-transcribe、 gpt-4o-mini-transcribe-2025-12-15、 whisper-1gpt-4o-transcribe-diarize和 。	Yes
檔案	字串	要轉錄的音訊檔案物件。	Yes
語言	字串	輸入音訊的語言。 以 ISO-639-1 格式提供輸入語言可提升準確度與延遲。	No
提示	字串	可選文字用來引導模型風格或延續先前的音訊片段。 提示詞應該與音頻語言相符。	No
response_format	audioResponseFormat	定義輸出格式。	No
temperature	number	取樣溫度介於0到1之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 若設為 0，模型會利用對數機率自動升溫，直到達到某些臨界點為止。	No	0
timestamp_granularities[]	陣列	此轉錄時需填寫的時間戳和細節。 response_format 必須設定 verbose_json 為使用時間戳記的細度。 支持以下選項之一或兩者： word，或 segment。 注意：區段時間戳記不會增加延遲，但產生字時間戳會產生額外的延遲。	No	['segment']

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	物件
text/plain	字串	輸出格式的文字轉錄（當 response_format 為 text或 vttsrt之一時）。

Examples

Example

從提供的語音資料中取得文字轉錄及相關元資料。

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "text": "A structured object when requesting json or verbose_json"
  }
}

Example

從提供的語音資料中取得文字轉錄及相關元資料。

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2025-04-01-preview

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

回應：狀態代碼：200

{
  "type": "string",
  "example": "plain text when requesting text, srt, or vtt"
}

翻譯 - 創作

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2025-04-01-preview

將輸入音訊轉錄並翻譯成英文文字。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: multipart/form-data

Name	類型	Description	Required	Default
檔案	字串	要翻譯的音訊檔案。	Yes
提示	字串	可選文字用來引導模型風格或延續先前的音訊片段。 題目應該是英文。	No
response_format	audioResponseFormat	定義輸出格式。	No
temperature	number	取樣溫度介於0到1之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 若設為 0，模型會利用對數機率自動升溫，直到達到某些臨界點為止。	No	0

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	物件
text/plain	字串	以輸出格式轉錄文字（當response_format為文字、VTT 或 SRT 格式時）。

Examples

Example

從提供的語音資料中取得英文轉錄文字及相關元資料。

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2025-04-01-preview

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

回應：狀態代碼：200

{
  "body": {
    "text": "A structured object when requesting json or verbose_json"
  }
}

Example

從提供的語音資料中取得英文轉錄文字及相關元資料。

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2025-04-01-preview

"---multipart-boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"file.wav\"\nContent-Type: application/octet-stream\n\nRIFF..audio.data.omitted\n---multipart-boundary--"

回應：狀態代碼：200

{
  "type": "string",
  "example": "plain text when requesting text, srt, or vtt"
}

語音 - 創作

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/speech?api-version=2025-04-01-preview

從輸入文字產生音訊。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: multipart/form-data

Name	類型	Description	Required	Default
輸入	字串	合成音訊的文字。 最大長度為 4,096 字元。	Yes
response_format	列舉	合成音訊的格式。 可能的值：mp3， opus， aacflacwavpcm	No
speed	number	合成音效的速度。 從 中選擇一個值 0.25 到 4.0。 1.0 是預設值。	No	1.0
voice	列舉	用於語音合成的聲音。 可能的值：alloy， echo， fableonyxnovashimmer	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/octet-stream	字串

Examples

Example

從提供的文字合成音訊。

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/speech?api-version=2025-04-01-preview

{
 "input": "Hi! What are you going to make?",
 "voice": "fable",
 "response_format": "mp3"
}

回應：狀態代碼：200

{
  "body": "101010101"
}

影像生成 - 創建

POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2025-04-01-preview

根據特定影像生成模型部署，從文字說明產生一批影像

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
背景	imageBackground	允許設定產生影像背景的透明度。 此參數僅支援 gpt-image-1 系列模型。	No	auto
n	整數	要產生的影像數量。 對於 dall-e-3，僅支援 n=1。	No	1
output_compression	整數	產生影像的壓縮等級（0-100%）。 此參數僅支援帶有 jpeg 輸出格式的 gpt-image-1 系列模型。	No	100
output_format	imagesOutputFormat	產生影像回傳的檔案格式。 僅支援 GPT-Image-1 系列機型。	No	png
提示	字串	這是想要圖片的文字描述。 GPT-image-1 系列最大長度為 32000 字元，dall-e-3 則為 4000 字元	Yes
partial_images	整數	需要產生的部分影像數量。 此參數用於回傳部分影像的串流回應。 數值必須介於0到3之間。 當設定為 0 時，回應會是單一圖片，在一次串流事件中傳送。 請注意，若完整影像產生速度較快，最終影像可能會在部分影像數量尚未完整生成前傳送。	0
串流	boolean	在串流模式下編輯圖片。	no	false
quality	imageQuality	所產生的影像品質。	No	auto
response_format	imagesResponseFormat	產生影像回傳的格式。 這個參數不支援 gpt-image-1-series 模型，因為 -series 模型總是會回傳 base64 編碼的影像。 可能的值： url， b64_json。	No	url
size	imageSize	產生的影像大小。	No	auto
樣式	imageStyle	產生的圖片風格。 只支援 DALL-E-3。	No	vivid
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

Responses

狀態代碼： 200

Description: Ok

Content-Type	Type	Description
application/json	generateImagesResponse

狀態代碼： 預設

說明：發生錯誤。

Content-Type	Type	Description
application/json	dalleErrorResponse

Examples

Example

在提示下創作圖片。

POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2025-04-01-preview

{
 "prompt": "In the style of WordArt, Microsoft Clippy wearing a cowboy hat.",
 "n": 1,
 "style": "natural",
 "quality": "standard"
}

回應：狀態代碼：200

{
  "body": {
    "created": 1698342300,
    "data": [
      {
        "revised_prompt": "A vivid, natural representation of Microsoft Clippy wearing a cowboy hat.",
        "prompt_filter_results": {
          "sexual": {
            "severity": "safe",
            "filtered": false
          },
          "violence": {
            "severity": "safe",
            "filtered": false
          },
          "hate": {
            "severity": "safe",
            "filtered": false
          },
          "self_harm": {
            "severity": "safe",
            "filtered": false
          },
          "profanity": {
            "detected": false,
            "filtered": false
          },
          "custom_blocklists": {
            "filtered": false,
            "details": []
          }
        },
        "url": "https://dalletipusw2.blob.core.windows.net/private/images/e5451cc6-b1ad-4747-bd46-b89a3a3b8bc3/generated_00.png?se=2023-10-27T17%3A45%3A09Z&...",
        "content_filter_results": {
          "sexual": {
            "severity": "safe",
            "filtered": false
          },
          "violence": {
            "severity": "safe",
            "filtered": false
          },
          "hate": {
            "severity": "safe",
            "filtered": false
          },
          "self_harm": {
            "severity": "safe",
            "filtered": false
          }
        }
      }
    ]
  }
}

影像生成 - 編輯

POST https://{endpoint}/openai/deployments/{deployment-id}/images/edits?api-version=2025-04-01-preview

在特定 gpt-image-1 模型部署中，從文字說明中編輯圖片

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
deployment-id	路徑	Yes	字串
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: multipart/form-data

Name	類型	Description	Required	Default
圖片	字串或陣列	圖片需要編輯。 必須是支援的影像檔案或一組影像陣列。 每張圖片應該是 png 或 jpg 檔案，大小於 50MB。	Yes
input_fidelity	字串	控制模型在匹配輸入影像的風格與特徵（尤其是臉部特徵）時所投入的努力。 此參數僅支援 gpt-image-1 系列模型。 支持與 highlow。	no	low.
遮罩	字串	另一張圖片的完全透明區域（例如alpha為零）指示圖片應編輯的位置。 若提供多張影像，遮罩會套用在第一張影像上。 必須是有效的 PNG 檔案，大小小於 4MB，且尺寸與圖片相同。	No
n	整數	要產生的影像數量。 必須介於1到10之間。	No	1
提示	字串	這是想要圖片的文字描述。 最大長度為32000字元。	Yes
quality	imageQuality	所產生的影像品質。	No	auto
partial_images	需要產生的部分影像數量。 此參數用於回傳部分影像的串流回應。 數值必須介於0到3之間。 當設定為 0 時，回應會是單一圖片，在一次串流事件中傳送。 請注意，若完整影像產生速度較快，最終影像可能會在部分影像數量尚未完整生成前傳送。
串流	boolean	在串流模式下編輯圖片。	no	false
response_format	imagesResponseFormat	產生影像回傳的格式。	No	url
size	imageSize	產生的影像大小。	No	auto
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

Responses

狀態代碼： 200

Description: Ok

Content-Type	Type	Description
application/json	generateImagesResponse

狀態代碼： 預設

說明：發生錯誤。

Content-Type	Type	Description
application/json	dalleErrorResponse

名單 - 助理教練

Note

助理 API 已被棄用，將於 2026 年 8 月 26 日正式退休。 請使用一般可用的 Microsoft Foundry Agents 服務。 請依照 遷移指南 更新你的工作負載。 Learn more.

GET https://{endpoint}/openai/assistants?api-version=2025-04-01-preview

回傳一份助理名單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listAssistantsResponse

Examples

Example

回傳一份助理名單。

GET https://{endpoint}/openai/assistants?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "asst_abc123",
        "object": "assistant",
        "created_at": 1707257477,
        "name": "Stock Analyst",
        "description": null,
        "model": "gpt-4-1106-preview",
        "instructions": "You are a financial analyst that analyzes stock market prices and other financial data present on user uploaded files or by calling external APIs.",
        "tools": [
          {
            "type": "code_interpreter"
          }
        ],
        "tool_resources": {},
        "metadata": {},
        "top_p": 1.0,
        "temperature": 1.0,
        "response_format": "auto"
      },
      {
        "id": "asst_abc456",
        "object": "assistant",
        "created_at": 1698982718,
        "name": "My Assistant",
        "description": null,
        "model": "gpt-4-turbo",
        "instructions": "You are a helpful assistant designed to make me better at coding!",
        "tools": [],
        "tool_resources": {},
        "metadata": {},
        "top_p": 1.0,
        "temperature": 1.0,
        "response_format": "auto"
      },
      {
        "id": "asst_abc789",
        "object": "assistant",
        "created_at": 1698982643,
        "name": null,
        "description": null,
        "model": "gpt-4-turbo",
        "instructions": null,
        "tools": [],
        "tool_resources": {},
        "metadata": {},
        "top_p": 1.0,
        "temperature": 1.0,
        "response_format": "auto"
      }
    ],
    "first_id": "asst_abc123",
    "last_id": "asst_abc789",
    "has_more": false
  }
}

Create - 助理

POST https://{endpoint}/openai/assistants?api-version=2025-04-01-preview

建立一個有模型和說明的助理。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
description	字串	助理的描述。 最大長度為512字元。	No
instructions	字串	助理使用的系統指令。 最大長度為 256,000 字元。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串		Yes
name	字串	助理的名字。 最大長度為 256 字元。	No
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	這個助理附著的向量儲存庫。 助理最多只能附加一個向量儲存。	No
└─ vector_stores	陣列	一個用 file_ids 建立向量儲存並附加到這個助理的輔助工具。 助理最多只能附加一個向量儲存。	No
tools	陣列	助理上啟用的工具清單。 每位助理最多可攜帶128種工具。 工具可以是類型 code_interpreter、、 retrieval或 function。	No	[]
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	assistantObject

Examples

Example

建立一個有模型和說明的助理。

POST https://{endpoint}/openai/assistants?api-version=2025-04-01-preview

{
 "name": "Math Tutor",
 "instructions": "When a customer asks about a specific math problem, use Python to evaluate their query.",
 "tools": [
  {
   "type": "code_interpreter"
  }
 ],
 "model": "gpt-4-1106-preview"
}

回應：狀態代碼：200

{
  "body": {
    "id": "asst_4nsG2qgNzimRPE7MazXTXbU7",
    "object": "assistant",
    "created_at": 1707295707,
    "name": "Math Tutor",
    "description": null,
    "model": "gpt-4-1106-preview",
    "instructions": "When a customer asks about a specific math problem, use Python to evaluate their query.",
    "tools": [
      {
        "type": "code_interpreter"
      }
    ],
    "metadata": {},
    "top_p": 1.0,
    "temperature": 1.0,
    "response_format": "auto"
  }
}

取得 - 助理

GET https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

叫來一名助理。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
assistant_id	路徑	Yes	字串	助理的身分證要取回。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	assistantObject

Examples

Example

叫來一名助理。

GET https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "asst_abc123",
    "object": "assistant",
    "created_at": 1699009709,
    "name": "HR Helper",
    "description": null,
    "model": "gpt-4-turbo",
    "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
    "tools": [
      {
        "type": "file_search"
      }
    ],
    "metadata": {},
    "top_p": 1.0,
    "temperature": 1.0,
    "response_format": "auto"
  }
}

Modify - 助理

POST https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

修改助理。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
assistant_id	路徑	Yes	字串	助理的ID可以修改。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
description	字串	助理的描述。 最大長度為512字元。	No
instructions	字串	助理使用的系統指令。 最大長度為 32768 字元。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串		No
name	字串	助理的名字。 最大長度為 256 字元。	No
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	覆蓋工具 code_interpreter 所提供的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	會覆蓋綁定在這個助理上的向量儲存。 助理最多只能附加一個向量儲存。	No
tools	陣列	助理上啟用的工具清單。 每位助理最多可攜帶128種工具。 工具可以是類型 code_interpreter、、 retrieval或 function。	No	[]
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	assistantObject

Examples

Example

修改助理。

POST https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

{
 "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
 "tools": [
  {
   "type": "file_search"
  }
 ],
 "model": "gpt-4-turbo"
}

回應：狀態代碼：200

{
  "body": {
    "id": "asst_123",
    "object": "assistant",
    "created_at": 1699009709,
    "name": "HR Helper",
    "description": null,
    "model": "gpt-4-turbo",
    "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
    "tools": [
      {
        "type": "file_search"
      }
    ],
    "tool_resources": {
      "file_search": {
        "vector_store_ids": []
      }
    },
    "metadata": {},
    "top_p": 1.0,
    "temperature": 1.0,
    "response_format": "auto"
  }
}

刪除 - 助理

DELETE https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

刪除助理。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
assistant_id	路徑	Yes	字串	要刪除助理的ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	deleteAssistantResponse

Examples

Example

刪除一位助理。

DELETE https://{endpoint}/openai/assistants/{assistant_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "asst_4nsG2qgNzimRPE7MazXTXbU7",
    "object": "assistant.deleted",
    "deleted": true
  }
}

創建 - 討論串

Note

助理 API 已被棄用，將於 2026 年 8 月 26 日正式退休。 請使用一般可用的 Microsoft Foundry Agents 服務。 請依照 遷移指南 更新你的工作負載。 Learn more.

POST https://{endpoint}/openai/threads?api-version=2025-04-01-preview

建立一個討論串。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
messages	陣列	一串訊息作為開啟討論串的清單。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
tool_resources	物件	這是一組在本串中提供給助理工具的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	向量商店附在本串。 執行緒最多可連接一個向量儲存庫。	No
└─ vector_stores	陣列	一個幫忙用 file_ids 建立向量儲存庫並附在這個討論串裡。 執行緒最多可連接一個向量儲存庫。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	threadObject

Examples

Example

這樣會產生一條線索。

POST https://{endpoint}/openai/threads?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "object": "thread",
    "created_at": 1707297136,
    "metadata": {}
  }
}

取得 - 討論串

GET https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

取回一條線索。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	要取回的執行緒 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	threadObject

Examples

Example

取回一條線索。

GET https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "object": "thread",
    "created_at": 1707297136,
    "metadata": {},
    "tool_resources": {
      "code_interpreter": {
        "file_ids": []
      }
    }
  }
}

修改 - 線程

POST https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

修改一個討論串。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	要修改的主題 ID。 只有 可以 metadata 修改。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
tool_resources	物件	這是一組在本串中提供給助理工具的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	向量商店附在本串。 執行緒最多可連接一個向量儲存庫。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	threadObject

Examples

Example

修改一個討論串。

POST https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

{
 "metadata": {
  "modified": "true",
  "user": "abc123"
 }
}

回應：狀態代碼：200

{
  "body": {
    "id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "object": "thread",
    "created_at": 1707297136,
    "metadata": {
      "modified": "true",
      "user": "abc123"
    },
    "tool_resources": {}
  }
}

刪除 - 討論串

DELETE https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

刪除一個討論串。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	要刪除的討論串的 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	deleteThreadResponse

Examples

Example

刪除一個討論串。

DELETE https://{endpoint}/openai/threads/{thread_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "object": "thread.deleted",
    "deleted": true
  }
}

列表 - 訊息

Note

助理 API 已被棄用，將於 2026 年 8 月 26 日正式退休。 請使用一般可用的 Microsoft Foundry Agents 服務。 請依照 遷移指南 更新你的工作負載。 Learn more.

GET https://{endpoint}/openai/threads/{thread_id}/messages?api-version=2025-04-01-preview

回傳給定執行緒的訊息清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	訊息所屬的執行緒的 ID。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
run_id	查詢	No	字串	用產生訊息的執行 ID 來過濾訊息。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listMessagesResponse

Examples

Example

List Messages

GET https://{endpoint}/openai/threads/{thread_id}/messages?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "msg_abc123",
        "object": "thread.message",
        "created_at": 1699016383,
        "assistant_id": null,
        "thread_id": "thread_abc123",
        "run_id": null,
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": {
              "value": "How does AI work? Explain it in simple terms.",
              "annotations": []
            }
          }
        ],
        "attachments": [],
        "metadata": {}
      },
      {
        "id": "msg_abc456",
        "object": "thread.message",
        "created_at": 1699016383,
        "assistant_id": null,
        "thread_id": "thread_abc123",
        "run_id": null,
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": {
              "value": "Hello, what is AI?",
              "annotations": []
            }
          }
        ],
        "attachments": [],
        "metadata": {}
      }
    ],
    "first_id": "msg_abc123",
    "last_id": "msg_abc456",
    "has_more": false
  }
}

創作 - 訊息

POST https://{endpoint}/openai/threads/{thread_id}/messages?api-version=2025-04-01-preview

建立訊息。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	要建立訊息的串程 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
attachments	陣列	附有與訊息相關的檔案清單，以及應該加入的工具。	No
內容	字串	訊息的內容。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
角色	字串	創造訊息的實體的角色。 允許的數值包括： - user表示訊息是由實際使用者發送，且大多數情況下應用來表示使用者產生的訊息。 - assistant表示訊息是由助理產生的。 利用這個值將助理的訊息插入對話中。	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	messageObject

Examples

Example

建立訊息。

POST https://{endpoint}/openai/threads/{thread_id}/messages?api-version=2025-04-01-preview

{
 "role": "user",
 "content": "What is the cube root of the sum of 12, 14, 1234, 4321, 90000, 123213541223, 443123123124, 5423324234, 234324324234, 653434534545, 200000000, 98237432984, 99999999, 99999999999, 220000000000, 3309587702? Give me the answer rounded to the nearest integer without commas or spaces."
}

回應：狀態代碼：200

{
  "body": {
    "id": "msg_as3XIk1tpVP3hdHjWBGg3uG4",
    "object": "thread.message",
    "created_at": 1707298421,
    "assistant_id": null,
    "thread_id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "run_id": null,
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": {
          "value": "What is the cube root of the sum of 12, 14, 1234, 4321, 90000, 123213541223, 443123123124, 5423324234, 234324324234, 653434534545, 200000000, 98237432984, 99999999, 99999999999, 220000000000, 3309587702? Give me the answer rounded to the nearest integer without commas or spaces.",
          "annotations": []
        }
      }
    ],
    "attachments": [],
    "metadata": {}
  }
}

取得 - 訊息

GET https://{endpoint}/openai/threads/{thread_id}/messages/{message_id}?api-version=2025-04-01-preview

取回訊息。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	此訊息所屬的主題ID。
message_id	路徑	Yes	字串	要取回訊息的 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	messageObject

Examples

Example

取回訊息。

GET https://{endpoint}/openai/threads/{thread_id}/messages/{message_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "msg_as3XIk1tpVP3hdHjWBGg3uG4",
    "object": "thread.message",
    "created_at": 1707298421,
    "thread_id": "thread_v7V4csrNOxtNmgcwGg496Smx",
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": {
          "value": "What is the cube root of the sum of 12, 14, 1234, 4321, 90000, 123213541223, 443123123124, 5423324234, 234324324234, 653434534545, 200000000, 98237432984, 99999999, 99999999999, 220000000000, 3309587702? Give me the answer rounded to the nearest integer without commas or spaces.",
          "annotations": []
        }
      }
    ],
    "file_ids": [],
    "assistant_id": null,
    "run_id": null,
    "metadata": {}
  }
}

Modify - 訊息

POST https://{endpoint}/openai/threads/{thread_id}/messages/{message_id}?api-version=2025-04-01-preview

修改訊息。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	此訊息所屬的主題ID。
message_id	路徑	Yes	字串	要修改訊息的 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	messageObject

Examples

Example

修改訊息。

POST https://{endpoint}/openai/threads/{thread_id}/messages/{message_id}?api-version=2025-04-01-preview

{
 "metadata": {
  "modified": "true",
  "user": "abc123"
 }
}

回應：狀態代碼：200

{
  "body": {
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1699017614,
    "assistant_id": null,
    "thread_id": "thread_abc123",
    "run_id": null,
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": {
          "value": "How does AI work? Explain it in simple terms.",
          "annotations": []
        }
      }
    ],
    "file_ids": [],
    "metadata": {
      "modified": "true",
      "user": "abc123"
    }
  }
}

創建 - 執行執行

Note

助理 API 已被棄用，將於 2026 年 8 月 26 日正式退休。 請使用一般可用的 Microsoft Foundry Agents 服務。 請依照 遷移指南 更新你的工作負載。 Learn more.

POST https://{endpoint}/openai/threads/runs?api-version=2025-04-01-preview

建立一個執行緒，一次執行。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
assistant_id	字串	執行此執行的助理 ID。	Yes
instructions	字串	覆蓋助理的預設系統訊息。 這對於每次執行時調整行為非常有用。	No
max_completion_tokens	整數	在整個遊戲過程中可使用的完成代幣數量。 該跑法會盡力只使用指定數量的完成標記，且在多回合中完成。 若執行超過完成標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
max_prompt_tokens	整數	在整個過程中可使用的提示代幣數量。 這次遊戲會盡力只使用指定數量的提示代幣，且在多回合中進行。 若執行次數超過指定提示標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串	執行此執行的模型 ID。 若此處提供值，該值將覆蓋與助理相關的模型。 若不符合，則會使用與助理相關的模型。	No
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
stream_options	chatCompletionStreamOptions	串流回應選項。 只有在你設定 stream: true時才會設定這個。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
執行緒	createThreadRequest		No
tool_choice	assistantsApiToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。	No
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	這個助理附著的向量商店 ID。 助理最多只能附加一個向量儲存。	No
tools	陣列	覆寫助理這次跑動時可用的工具。 這對於每次執行時調整行為非常有用。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1
truncation_strategy	truncationObject	控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

建立一個執行緒，一次執行。

POST https://{endpoint}/openai/threads/runs?api-version=2025-04-01-preview

{
 "assistant_id": "asst_abc123",
 "thread": {
  "messages": [
   {
    "role": "user",
    "content": "Explain deep learning to a 5 year old."
   }
  ]
 }
}

回應：狀態代碼：200

{
  "body": {
    "id": "run_abc123",
    "object": "thread.run",
    "created_at": 1699076792,
    "assistant_id": "asst_abc123",
    "thread_id": "thread_abc123",
    "status": "queued",
    "started_at": null,
    "expires_at": 1699077392,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": null,
    "required_action": null,
    "last_error": null,
    "model": "gpt-4-turbo",
    "instructions": "You are a helpful assistant.",
    "tools": [],
    "tool_resources": {},
    "metadata": {},
    "temperature": 1.0,
    "top_p": 1.0,
    "max_completion_tokens": null,
    "max_prompt_tokens": null,
    "truncation_strategy": {
      "type": "auto",
      "last_messages": null
    },
    "incomplete_details": null,
    "usage": null,
    "response_format": "auto",
    "tool_choice": "auto"
  }
}

列表- 得分

GET https://{endpoint}/openai/threads/{thread_id}/runs?api-version=2025-04-01-preview

回傳屬於執行緒的執行清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	該執行串所屬的 ID。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listRunsResponse

Examples

Example

回傳屬於執行緒的執行清單。

GET https://{endpoint}/openai/threads/{thread_id}/runs?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "run_abc123",
        "object": "thread.run",
        "created_at": 1699075072,
        "assistant_id": "asst_abc123",
        "thread_id": "thread_abc123",
        "status": "completed",
        "started_at": 1699075072,
        "expires_at": null,
        "cancelled_at": null,
        "failed_at": null,
        "completed_at": 1699075073,
        "last_error": null,
        "model": "gpt-4-turbo",
        "instructions": null,
        "incomplete_details": null,
        "tools": [
          {
            "type": "code_interpreter"
          }
        ],
        "tool_resources": {
          "code_interpreter": {
            "file_ids": [
              "file-abc123",
              "file-abc456"
            ]
          }
        },
        "metadata": {},
        "usage": {
          "prompt_tokens": 123,
          "completion_tokens": 456,
          "total_tokens": 579
        },
        "temperature": 1.0,
        "top_p": 1.0,
        "max_prompt_tokens": 1000,
        "max_completion_tokens": 1000,
        "truncation_strategy": {
          "type": "auto",
          "last_messages": null
        },
        "response_format": "auto",
        "tool_choice": "auto"
      },
      {
        "id": "run_abc456",
        "object": "thread.run",
        "created_at": 1699063290,
        "assistant_id": "asst_abc123",
        "thread_id": "thread_abc123",
        "status": "completed",
        "started_at": 1699063290,
        "expires_at": null,
        "cancelled_at": null,
        "failed_at": null,
        "completed_at": 1699063291,
        "last_error": null,
        "model": "gpt-4-turbo",
        "instructions": null,
        "incomplete_details": null,
        "tools": [
          {
            "type": "code_interpreter"
          }
        ],
        "tool_resources": {
          "code_interpreter": {
            "file_ids": [
              "file-abc123",
              "file-abc456"
            ]
          }
        },
        "metadata": {},
        "usage": {
          "prompt_tokens": 123,
          "completion_tokens": 456,
          "total_tokens": 579
        },
        "temperature": 1.0,
        "top_p": 1.0,
        "max_prompt_tokens": 1000,
        "max_completion_tokens": 1000,
        "truncation_strategy": {
          "type": "auto",
          "last_messages": null
        },
        "response_format": "auto",
        "tool_choice": "auto"
      }
    ],
    "first_id": "run_abc123",
    "last_id": "run_abc456",
    "has_more": false
  }
}

創建 - 執行

POST https://{endpoint}/openai/threads/{thread_id}/runs?api-version=2025-04-01-preview

創造一個跑動。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	要執行的主題 ID。
include[]	查詢	No	陣列	回覆中需包含的額外欄位清單。 目前唯一支援的值是 step_details.tool_calls[*].file_search.results[*].content 擷取檔案搜尋結果內容。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
additional_instructions	字串	在執行指令的最後附加額外指令。 這對於每次執行修改行為且不會覆蓋其他指令非常有用。	No
additional_messages	陣列	在建立執行前，先向執行緒新增訊息。	No
assistant_id	字串	執行此執行的助理 ID。	Yes
instructions	字串	覆蓋助理的預設系統訊息。 這對於每次執行時調整行為非常有用。	No
max_completion_tokens	整數	在整個遊戲過程中可使用的完成代幣數量。 該跑法會盡力只使用指定數量的完成標記，且在多回合中完成。 若執行超過完成標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
max_prompt_tokens	整數	在整個過程中可使用的提示代幣數量。 這次遊戲會盡力只使用指定數量的提示代幣，且在多回合中進行。 若執行次數超過指定提示標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串	執行此執行的模型 ID。 若此處提供值，該值將覆蓋與助理相關的模型。 若不符合，則會使用與助理相關的模型。	No
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_choice	assistantsApiToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。	No
tools	陣列	覆寫助理這次跑動時可用的工具。 這對於每次執行時調整行為非常有用。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1
truncation_strategy	truncationObject	控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

創造一個跑動。

POST https://{endpoint}/openai/threads/{thread_id}/runs?api-version=2025-04-01-preview

{
 "assistant_id": "asst_abc123"
}

回應：狀態代碼：200

{
  "body": {
    "id": "run_abc123",
    "object": "thread.run",
    "created_at": 1699063290,
    "assistant_id": "asst_abc123",
    "thread_id": "thread_abc123",
    "status": "queued",
    "started_at": 1699063290,
    "expires_at": null,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": 1699063291,
    "last_error": null,
    "model": "gpt-4-turbo",
    "instructions": null,
    "incomplete_details": null,
    "tools": [
      {
        "type": "code_interpreter"
      }
    ],
    "metadata": {},
    "usage": null,
    "temperature": 1.0,
    "top_p": 1.0,
    "max_prompt_tokens": 1000,
    "max_completion_tokens": 1000,
    "truncation_strategy": {
      "type": "auto",
      "last_messages": null
    },
    "response_format": "auto",
    "tool_choice": "auto"
  }
}

快跑

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}?api-version=2025-04-01-preview

跑回一分。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	是被執行的討論串的 ID。
run_id	路徑	Yes	字串	要取回的行動編號。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

跑了一分。

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "run_HsO8tYM4K5AAMAHgK0J3om8Q",
    "object": "thread.run",
    "created_at": 1707303196,
    "assistant_id": "asst_JtTwHk28cIocgFXZPCBxhOzl",
    "thread_id": "thread_eRNwflE3ncDYak1np6MdMHJh",
    "status": "completed",
    "started_at": 1707303197,
    "expires_at": null,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": 1707303201,
    "last_error": null,
    "model": "gpt-4-1106-preview",
    "instructions": "You are an AI model that empowers every person and every organization on the planet to achieve more.",
    "tools": [],
    "file_ids": [],
    "metadata": {}
  }
}

修改 - 運行

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}?api-version=2025-04-01-preview

修改跑動。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	是被執行的討論串的 ID。
run_id	路徑	Yes	字串	要修改的 ID。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

修改跑動。

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}?api-version=2025-04-01-preview

{
 "metadata": {
  "user_id": "user_abc123"
 }
}

回應：狀態代碼：200

{
  "body": {
    "id": "run_abc123",
    "object": "thread.run",
    "created_at": 1699075072,
    "assistant_id": "asst_abc123",
    "thread_id": "thread_abc123",
    "status": "completed",
    "started_at": 1699075072,
    "expires_at": null,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": 1699075073,
    "last_error": null,
    "model": "gpt-4-turbo",
    "instructions": null,
    "incomplete_details": null,
    "tools": [
      {
        "type": "code_interpreter"
      }
    ],
    "tool_resources": {
      "code_interpreter": {
        "file_ids": [
          "file-abc123",
          "file-abc456"
        ]
      }
    },
    "metadata": {
      "user_id": "user_abc123"
    },
    "usage": {
      "prompt_tokens": 123,
      "completion_tokens": 456,
      "total_tokens": 579
    },
    "temperature": 1.0,
    "top_p": 1.0,
    "max_prompt_tokens": 1000,
    "max_completion_tokens": 1000,
    "truncation_strategy": {
      "type": "auto",
      "last_messages": null
    },
    "response_format": "auto",
    "tool_choice": "auto"
  }
}

提交 - 執行工具輸出

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2025-04-01-preview

當執行中 且 status: "requires_action"required_action.type 是 submit_tool_outputs時，這個端點可以用來提交工具呼叫的輸出，當它們全部完成後。 所有輸出必須一次性提交。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	這個跑動所屬的串碼ID。
run_id	路徑	Yes	字串	需要提交工具輸出的執行編號。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
tool_outputs	陣列	一份提交輸出的工具清單。	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

當執行中 且 status: "requires_action"required_action.type 是 submit_tool_outputs時，這個端點可以用來提交工具呼叫的輸出，當它們全部完成後。 所有輸出必須一次性提交。

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2025-04-01-preview

{
 "tool_outputs": [
  {
   "tool_call_id": "call_001",
   "output": "70 degrees and sunny."
  }
 ]
}

回應：狀態代碼：200

{
  "body": {
    "id": "run_123",
    "object": "thread.run",
    "created_at": 1699075592,
    "assistant_id": "asst_123",
    "thread_id": "thread_123",
    "status": "queued",
    "started_at": 1699075592,
    "expires_at": 1699076192,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": null,
    "last_error": null,
    "model": "gpt-4-turbo",
    "instructions": null,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": [
                  "celsius",
                  "fahrenheit"
                ]
              }
            },
            "required": [
              "location"
            ]
          }
        }
      }
    ],
    "metadata": {},
    "usage": null,
    "temperature": 1.0,
    "top_p": 1.0,
    "max_prompt_tokens": 1000,
    "max_completion_tokens": 1000,
    "truncation_strategy": {
      "type": "auto",
      "last_messages": null
    },
    "response_format": "auto",
    "tool_choice": "auto"
  }
}

取消 - 逃跑

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2025-04-01-preview

取消一個為 in_progress的跑動。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	這個執行串所屬的 ID。
run_id	路徑	Yes	字串	取消的行動編號。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runObject

Examples

Example

取消一個為 in_progress的跑動。

POST https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "run_abc123",
    "object": "thread.run",
    "created_at": 1699076126,
    "assistant_id": "asst_abc123",
    "thread_id": "thread_abc123",
    "status": "cancelling",
    "started_at": 1699076126,
    "expires_at": 1699076726,
    "cancelled_at": null,
    "failed_at": null,
    "completed_at": null,
    "last_error": null,
    "model": "gpt-4-turbo",
    "instructions": "You summarize books.",
    "tools": [
      {
        "type": "file_search"
      }
    ],
    "tool_resources": {
      "file_search": {
        "vector_store_ids": [
          "vs_123"
        ]
      }
    },
    "metadata": {},
    "usage": null,
    "temperature": 1.0,
    "top_p": 1.0,
    "response_format": "auto"
  }
}

列表 - 跑步步驟

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2025-04-01-preview

回傳屬於某次執行的執行步驟清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	執行與執行步驟所屬的執行緒 ID。
run_id	路徑	Yes	字串	跑跑步驟所屬的 ID。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
api-version	查詢	Yes	字串
include[]	查詢	No	陣列	回覆中需包含的額外欄位清單。 目前唯一支援的值是 step_details.tool_calls[*].file_search.results[*].content 擷取檔案搜尋結果內容。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listRunStepsResponse

Examples

Example

回傳屬於某次執行的執行步驟清單。

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "step_abc123",
        "object": "thread.run.step",
        "created_at": 1699063291,
        "run_id": "run_abc123",
        "assistant_id": "asst_abc123",
        "thread_id": "thread_abc123",
        "type": "message_creation",
        "status": "completed",
        "cancelled_at": null,
        "completed_at": 1699063291,
        "expired_at": null,
        "failed_at": null,
        "last_error": null,
        "step_details": {
          "type": "message_creation",
          "message_creation": {
            "message_id": "msg_abc123"
          }
        },
        "usage": {
          "prompt_tokens": 123,
          "completion_tokens": 456,
          "total_tokens": 579
        }
      }
    ],
    "first_id": "step_abc123",
    "last_id": "step_abc456",
    "has_more": false
  }
}

Get - 跑步

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2025-04-01-preview

取得跑壘。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
thread_id	路徑	Yes	字串	執行與執行步驟所屬的執行緒 ID。
run_id	路徑	Yes	字串	跑步所屬的跑道ID。
step_id	路徑	Yes	字串	執行步驟的 ID。
include[]	查詢	No	陣列	回覆中需包含的額外欄位清單。 目前唯一支援的值是 step_details.tool_calls[*].file_search.results[*].content 擷取檔案搜尋結果內容。
api-version	查詢	Yes	字串

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	runStepObject

Examples

Example

取得跑壘。

GET https://{endpoint}/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "step_abc123",
    "object": "thread.run.step",
    "created_at": 1699063291,
    "run_id": "run_abc123",
    "assistant_id": "asst_abc123",
    "thread_id": "thread_abc123",
    "type": "message_creation",
    "status": "completed",
    "cancelled_at": null,
    "completed_at": 1699063291,
    "expired_at": null,
    "failed_at": null,
    "last_error": null,
    "step_details": {
      "type": "message_creation",
      "message_creation": {
        "message_id": "msg_abc123"
      }
    },
    "usage": {
      "prompt_tokens": 123,
      "completion_tokens": 456,
      "total_tokens": 579
    }
  }
}

列表 - 向量儲存庫

GET https://{endpoint}/openai/vector_stores?api-version=2025-04-01-preview

回傳一份向量儲存清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listVectorStoresResponse

Examples

Example

回傳一份向量儲存清單。

GET https://{endpoint}/openai/vector_stores?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "vs_abc123",
        "object": "vector_store",
        "created_at": 1699061776,
        "name": "Support FAQ",
        "bytes": 139920,
        "file_counts": {
          "in_progress": 0,
          "completed": 3,
          "failed": 0,
          "cancelled": 0,
          "total": 3
        }
      },
      {
        "id": "vs_abc456",
        "object": "vector_store",
        "created_at": 1699061776,
        "name": "Support FAQ v2",
        "bytes": 139920,
        "file_counts": {
          "in_progress": 0,
          "completed": 3,
          "failed": 0,
          "cancelled": 0,
          "total": 3
        }
      }
    ],
    "first_id": "vs_abc123",
    "last_id": "vs_abc456",
    "has_more": false
  }
}

Create - 向量儲存

POST https://{endpoint}/openai/vector_stores?api-version=2025-04-01-preview

建立一個向量商店。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
chunking_strategy	autoChunkingStrategyRequestParam 或 staticChunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。 僅當 file_ids 非空時才適用。	No
expires_after	vectorStoreExpirationAfter	向量商店的過期政策。	No
file_ids	陣列	一份向量儲存應該使用的檔案 ID 清單。 這類工具很 file_search 有用，可以存取檔案。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
name	字串	向量商店的名稱。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreObject

Examples

Example

建立向量儲存。

POST https://{endpoint}/openai/vector_stores?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "vs_abc123",
    "object": "vector_store",
    "created_at": 1699061776,
    "name": "Support FAQ",
    "bytes": 139920,
    "file_counts": {
      "in_progress": 0,
      "completed": 3,
      "failed": 0,
      "cancelled": 0,
      "total": 3
    }
  }
}

取得 - 向量商店

GET https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

取得向量儲存。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	要取回向量儲存的 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreObject

Examples

Example

取得向量儲存。

GET https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "vs_abc123",
    "object": "vector_store",
    "created_at": 1699061776
  }
}

Modify - 向量儲存

POST https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

修改向量儲存。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	要修改向量儲存的 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
expires_after	vectorStoreExpirationAfter	向量商店的過期政策。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
name	字串	向量商店的名稱。	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreObject

Examples

Example

修改向量儲存。

POST https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

{
 "name": "Support FAQ"
}

回應：狀態代碼：200

{
  "body": {
    "id": "vs_abc123",
    "object": "vector_store",
    "created_at": 1699061776,
    "name": "Support FAQ",
    "bytes": 139920,
    "file_counts": {
      "in_progress": 0,
      "completed": 3,
      "failed": 0,
      "cancelled": 0,
      "total": 3
    }
  }
}

刪除 - 向量儲存

DELETE https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

刪除向量儲存。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	要刪除的向量儲存的 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	deleteVectorStoreResponse

Examples

Example

刪除向量儲存。

DELETE https://{endpoint}/openai/vector_stores/{vector_store_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "vs_abc123",
    "object": "vector_store.deleted",
    "deleted": true
  }
}

列表 - 向量儲存檔案

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/files?api-version=2025-04-01-preview

回傳一份向量儲存檔案的清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案所屬的向量儲存的 ID。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
篩選	查詢	No	字串 可能的值：in_progress， ， completedfailed，cancelled	依檔案狀態篩選。 其中一位 in_progress， completed， failed， cancelled。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listVectorStoreFilesResponse

Examples

Example

回傳一份向量儲存檔案的清單。

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/files?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "file-abc123",
        "object": "vector_store.file",
        "created_at": 1699061776,
        "vector_store_id": "vs_abc123"
      },
      {
        "id": "file-abc456",
        "object": "vector_store.file",
        "created_at": 1699061776,
        "vector_store_id": "vs_abc123"
      }
    ],
    "first_id": "file-abc123",
    "last_id": "file-abc456",
    "has_more": false
  }
}

建立 - 向量儲存檔案

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/files?api-version=2025-04-01-preview

透過將檔案附加到向量儲存庫來建立向量儲存檔案。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	用來建立檔案的向量儲存裝置的 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
chunking_strategy	chunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。	No
file_id	字串	一個向量儲存應該使用的檔案 ID。 這類工具很 file_search 有用，可以存取檔案。	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileObject

Examples

Example

透過將檔案附加到向量儲存庫來建立向量儲存檔案。

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/files?api-version=2025-04-01-preview

{
 "file_id": "file-abc123"
}

回應：狀態代碼：200

{
  "body": {
    "id": "file-abc123",
    "object": "vector_store.file",
    "created_at": 1699061776,
    "usage_bytes": 1234,
    "vector_store_id": "vs_abcd",
    "status": "completed",
    "last_error": null
  }
}

取得 - 向量儲存檔案

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}?api-version=2025-04-01-preview

取得向量儲存檔案。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案所屬的向量儲存的 ID。
file_id	路徑	Yes	字串	被取回的檔案 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileObject

Examples

Example

取得向量儲存檔案。

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "file-abc123",
    "object": "vector_store.file",
    "created_at": 1699061776,
    "vector_store_id": "vs_abcd",
    "status": "completed",
    "last_error": null
  }
}

刪除 - 向量儲存檔案

DELETE https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}?api-version=2025-04-01-preview

刪除一個向量儲存檔案。 這樣會把檔案從向量儲存中移除，但檔案本身不會被刪除。 要刪除檔案，請使用刪除檔案端點。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案所屬的向量儲存的 ID。
file_id	路徑	Yes	字串	要刪除的檔案 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	deleteVectorStoreFileResponse

Examples

Example

刪除一個向量儲存檔案。 這樣會把檔案從向量儲存中移除，但檔案本身不會被刪除。 要刪除檔案，請使用刪除檔案端點。

DELETE https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "file_abc123",
    "object": "vector_store.file.deleted",
    "deleted": true
  }
}

Updatevectorstorefileattributes

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}?api-version=2025-04-01-preview

更新向量儲存檔案的屬性。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案所屬的向量儲存的 ID。
file_id	路徑	Yes	字串	檔案的 ID 用來更新屬性。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
attributes	VectorStoreFileAttributes	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是最大長度為 512 字元的字串、布林值或數字。	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileObject

擷取向量儲存檔案內容

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/files/{file_id}/content?api-version=2025-04-01-preview

取得向量儲存檔案中解析後的內容。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	向量商店的 ID。
file_id	路徑	Yes	字串	向量儲存中檔案的 ID。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	VectorStoreFileContentResponse

搜尋向量儲存

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/search?api-version=2025-04-01-preview

在向量儲存庫中搜尋相關區塊，並根據查詢和檔案屬性篩選器。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	搜尋向量儲存的 ID。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
filters	比較濾波器 或 複合濾波器	一個根據檔案屬性套用的篩選器。	No
max_num_results	整數	回傳的結果數量。 這個數字應該介於1到50之間。	No	10
查詢	字串或陣列	搜尋的查詢字串	Yes
ranking_options	物件	搜尋排名選項。	No
└─ ranker	列舉	可能的值： auto， default-2024-11-15	No
└─ score_threshold	number		No	0
rewrite_query	boolean	是否要重寫向量搜尋的自然語言查詢。	No	False

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	VectorStoreSearchResultsPage

建立 - 向量儲存檔案批次

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches?api-version=2025-04-01-preview

建立向量儲存檔案批次。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	向量儲存裝置的 ID，用來建立檔案批次。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
chunking_strategy	chunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。	No
file_ids	陣列	一份向量儲存應該使用的檔案 ID 清單。 這類工具很 file_search 有用，可以存取檔案。	Yes

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileBatchObject

Examples

Example

建立向量儲存檔案批次。

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches?api-version=2025-04-01-preview

{
 "file_ids": [
  "file-abc123",
  "file-abc456"
 ]
}

回應：狀態代碼：200

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0
  }
}

取得 - 向量儲存檔案批次

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}?api-version=2025-04-01-preview

取得向量儲存批次檔案。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案批次所屬的向量儲存的 ID。
batch_id	路徑	Yes	字串	正在取回的檔案批次的 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileBatchObject

Examples

Example

取得向量儲存批次檔案。

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "vsfb_abc123",
    "object": "vector_store.file_batch",
    "created_at": 1699061776,
    "vector_store_id": "vs_abc123",
    "status": "in_progress",
    "file_counts": {
      "in_progress": 1,
      "completed": 1,
      "failed": 0,
      "cancelled": 0,
      "total": 0
    }
  }
}

取消 - 向量儲存檔案批次

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel?api-version=2025-04-01-preview

取消向量儲存批次檔案。 此方法嘗試盡快取消該批次檔案的處理。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案批次所屬的向量儲存的 ID。
batch_id	路徑	Yes	字串	要取消的檔案批次 ID。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	vectorStoreFileBatchObject

Examples

Example

取消向量儲存批次檔案。 此方法嘗試盡快取消該批次檔案的處理。

POST https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "id": "vsfb_abc123",
    "object": "vector_store.file_batch",
    "created_at": 1699061776,
    "vector_store_id": "vs_abc123",
    "status": "cancelling",
    "file_counts": {
      "in_progress": 12,
      "completed": 3,
      "failed": 0,
      "cancelled": 0,
      "total": 15
    }
  }
}

列表 - 向量儲存檔案批次檔案

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}/files?api-version=2025-04-01-preview

會以批次回傳一份向量儲存檔案清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
vector_store_id	路徑	Yes	字串	檔案所屬的向量儲存的 ID。
batch_id	路徑	Yes	字串	檔案所屬的批次 ID。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	依照物件的時間戳記排序 created_at 順序。 asc 分別為升序與 desc 降序。
after	查詢	No	字串	一個用於分頁的游標。 after 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，最後以 obj_foo 結尾，你接下來的呼叫可以包含 after =obj_foo，以便取得清單的下一頁。
before	查詢	No	字串	一個用於分頁的游標。 before 是一個定義你在清單中位置的物件 ID。 例如，如果你提出一個清單請求並收到 100 個物件，從 obj_foo 開始，你的後續呼叫可以包含 before=obj_foo，以取得清單的前一頁。
篩選	查詢	No	字串 可能的值：in_progress， ， completedfailed，cancelled	依檔案狀態篩選。 其中一位 in_progress， completed， failed， cancelled。
api-version	查詢	Yes	字串	api version

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	listVectorStoreFilesResponse

Examples

Example

回傳一份向量儲存檔案的清單。

GET https://{endpoint}/openai/vector_stores/{vector_store_id}/file_batches/{batch_id}/files?api-version=2025-04-01-preview

回應：狀態代碼：200

{
  "body": {
    "object": "list",
    "data": [
      {
        "id": "file-abc123",
        "object": "vector_store.file",
        "created_at": 1699061776,
        "vector_store_id": "vs_abc123"
      },
      {
        "id": "file-abc456",
        "object": "vector_store.file",
        "created_at": 1699061776,
        "vector_store_id": "vs_abc123"
      }
    ],
    "first_id": "file-abc123",
    "last_id": "file-abc456",
    "has_more": false
  }
}

Create - 即時會話

POST https://{endpoint}/openai/realtimeapi/sessions?api-version=2025-04-01-preview

建立一個臨時 API 令牌，用於客戶端應用，使用 Realtime API。 可以設定與用戶端事件相同的會話參數 session.update 。 它會以一個會話物件回應，並附有一 client_secret 把包含可用臨時 API 憑證的金鑰，該憑證可用於驗證即時 API 的瀏覽器用戶端。

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
input_audio_format	列舉	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸入音訊必須為 16 位元 PCM，取樣率為 24kHz，單聲道（mono），且位元組序為小端序。 可能的值： pcm16， g711_ulaw， g711_alaw	No
input_audio_noise_reduction	物件	輸入音訊降噪配置。 這個設定可以設定 null 為關閉。 降噪濾波器會將輸入音訊緩衝區的音訊加入，然後再送入 VAD 與模型。 過濾音訊可提升 VAD 與轉向偵測的準確度（減少誤報），並透過提升輸入音訊的感知來提升模型效能。	No
└─ type	列舉	降噪類型。 near_field 是用於近距離講話的麥克風，如耳機 far_field ;則是用於遠場麥克風，如筆記型電腦或會議室麥克風。 可能的值： near_field， far_field	No
input_audio_transcription	物件	輸入音訊轉錄設定預設為關閉，開啟後可設定為 null 關閉。 輸入音訊轉錄並非模型本身，因為模型直接接收音訊。 轉錄在轉 錄端 點以非同步方式執行，應視為輸入音訊內容的指引，而非模型所聽到的精確內容。 客戶可選擇設定轉錄語言與提示，這些功能為轉錄服務提供額外指引。	No
└─ language	字串	輸入音訊的語言。 以 ISO-639-1 （例如 en）格式提供輸入語言，能提升準確度與延遲。	No
└─ model	字串	用於轉錄的模型，目前的選項有 gpt-4o-transcribe、 gpt-4o-transcribe-diarize、 gpt-4o-mini-transcribegpt-4o-mini-transcribe-2025-12-15whisper-1、 和 。	No
└─ prompt	字串	可選文字用來引導模型風格或延續先前的音訊片段。 對於 whisper-1，提示詞是一串關鍵字。 對模型而言 gpt-4o-transcribe ，提示是自由文字串，例如「expect words with technology but technology」。	No
instructions	字串	預設系統指令（即系統訊息）會置於模型呼叫之前。 此欄位允許客戶引導模型對期望的回應進行調整。 模型可以被指導回應內容與格式（例如「極簡潔」、「表現友善」、「這裡有良好回應的範例」）以及音頻行為（例如「快速說話」、「將情感注入聲音」、「經常笑」）。 這些指令不保證模型一定會遵守，但它們會為模型提供所需的行為指引。 請注意，伺服器會設定預設指令，若未設定此欄位，會被使用，且會在會話開始時的事件中可見 session.created 。	No
max_response_output_tokens	整數或字串	單一助理回應的最大輸出標記數，包含工具呼叫。 提供介於 1 到 4096 之間的整數，以限制輸出標記，或 inf 表示給定模型的最大可用標記數。 預設為 inf。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
型號	字串	本次會話所使用的部署名稱。	No
output_audio_format	列舉	輸出音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸出音訊以 24kHz 的取樣率進行。 可能的值： pcm16， g711_ulaw， g711_alaw	No
temperature	number	模型取樣溫度限制為 [0.6， 1.2]。 對於音響機型，強烈建議溫度為 0.8 以達到最佳效能。	No	0.8
tool_choice	字串	模型如何選擇工具。 選項為 auto、 none、 required或指定函數。	No	auto
tools	陣列	模型可用的工具（功能）。	No
turn_detection	物件	回合偵測的設定，伺服器 VAD 或語義 VAD。 此設定可設定 null 為關閉，此時用戶端必須手動觸發模型回應。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。 語意型 VAD 則更進階，並結合回合偵測模型（結合 VAD）語義上估算使用者是否已講完話，並根據此機率動態設定逾時。 例如，如果使用者的音訊以 uhhm漸漸消失，模型會被分成低機率，並等待使用者繼續說話的時間。 這對於較自然的對話很有用，但可能延遲較高。	No
└─ create_response	boolean	當 VAD 停止事件發生時，是否要自動產生回應。	No	True
└─ eagerness	列舉	只用於 semantic_vad 模式。 模型的積極回應。 low 會等更久讓使用者繼續說話，且 high 回應速度會更快。 auto 是預設值，且等價於 medium。 可能的值：low， ， mediumhigh，auto	No
└─ interrupt_response	boolean	當 VAD 開始事件發生時，是否應該自動中斷任何進行中的回應並輸出到預設對話（即 conversation 的 auto）。	No	True
└─ prefix_padding_ms	整數	只用於 server_vad 模式。 VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	只用於 server_vad 模式。 靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	只用於 server_vad 模式。 VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	列舉	轉向偵測的類型。 可能的值： server_vad， semantic_vad	No
voice	VoiceIdsShared		No

Responses

狀態代碼： 200

說明：會議成功建立。

Content-Type	Type	Description
application/json	RealtimeSessionCreateResponse

建立 - 轉錄實時會話

POST https://{endpoint}/openai/realtimeapi/transcription_sessions?api-version=2025-04-01-preview

為客戶端應用程式建立一個臨時 API 令牌，專門用於即時轉錄的 Realtime API。 可以設定與用戶端事件相同的會話參數 transcription_session.update 。 它會以一個會話物件回應，並附有一 client_secret 把包含可用臨時 API 憑證的金鑰，該憑證可用於驗證即時 API 的瀏覽器用戶端。

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
include	陣列	這是抄本中要包含的項目集合。 目前可用的項目包括： - item.input_audio_transcription.logprobs	No
input_audio_format	列舉	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸入音訊必須為 16 位元 PCM，取樣率為 24kHz，單聲道（mono），且位元組序為小端序。 可能的值： pcm16， g711_ulaw， g711_alaw	No
input_audio_noise_reduction	物件	輸入音訊降噪配置。 這個設定可以設定 null 為關閉。 降噪濾波器會將輸入音訊緩衝區的音訊加入，然後再送入 VAD 與模型。 過濾音訊可提升 VAD 與轉向偵測的準確度（減少誤報），並透過提升輸入音訊的感知來提升模型效能。	No
└─ type	列舉	降噪類型。 near_field 是用於近距離講話的麥克風，如耳機 far_field ;則是用於遠場麥克風，如筆記型電腦或會議室麥克風。 可能的值： near_field， far_field	No
input_audio_transcription	物件	輸入音訊轉錄的設定。 客戶可選擇設定轉錄語言與提示，這些功能為轉錄服務提供額外指引。	No
└─ language	字串	輸入音訊的語言。 以 ISO-639-1 （例如 en）格式提供輸入語言，能提升準確度與延遲。	No
└─ model	列舉	目前用於轉錄的模型有 gpt-4o-transcribe、 gpt-4o-mini-transcribe、 gpt-4o-mini-transcribe-2025-12-15、 whisper-1和 。 可能的值：gpt-4o-transcribe， ， gpt-4o-mini-transcribegpt-4o-mini-transcribe-2025-12-15，whisper-1	No
└─ prompt	字串	可選文字用來引導模型風格或延續先前的音訊片段。 對於 whisper-1，提示詞是一串關鍵字。 對模型而言 gpt-4o-transcribe ，提示是自由文字串，例如「expect words with technology but technology」。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
turn_detection	物件	回合偵測的設定，伺服器 VAD 或語義 VAD。 此設定可設定 null 為關閉，此時用戶端必須手動觸發模型回應。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。 語意型 VAD 則更進階，並結合回合偵測模型（結合 VAD）語義上估算使用者是否已講完話，並根據此機率動態設定逾時。 例如，如果使用者的音訊以 uhhm漸漸消失，模型會被分成低機率，並等待使用者繼續說話的時間。 這對於較自然的對話很有用，但可能延遲較高。	No
└─ create_response	boolean	當 VAD 停止事件發生時，是否要自動產生回應。 無法進行轉錄。	No	True
└─ eagerness	列舉	只用於 semantic_vad 模式。 模型的積極回應。 low 會等更久讓使用者繼續說話，且 high 回應速度會更快。 auto 是預設值，且等價於 medium。 可能的值：low， ， mediumhigh，auto	No
└─ interrupt_response	boolean	當 VAD 開始事件發生時，是否應該自動中斷任何進行中的回應並輸出到預設對話（即 conversation 的 auto）。 無法進行轉錄。	No	True
└─ prefix_padding_ms	整數	只用於 server_vad 模式。 VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	只用於 server_vad 模式。 靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	只用於 server_vad 模式。 VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	列舉	轉向偵測的類型。 可能的值： server_vad， semantic_vad	No

Responses

狀態代碼： 200

說明：會議成功建立。

Content-Type	Type	Description
application/json	RealtimeTranscriptionSessionCreateResponse

Responses

POST https://{endpoint}/openai/responses?api-version=2025-04-01-preview

創造一個模型回應。

Request Body

Content-Type: application/json

Name	類型	Description	Required	Default
include	陣列		No
輸入	字串或陣列	Model inputs	Yes
instructions	字串	在模型上下文中插入系統（或開發者）訊息作為第一個項目。 使用與 previous_response_id時，前一個回應的指令不會被帶到下一個回應。 這讓替換系統（或開發者）訊息變得簡單。	No
max_output_tokens	整數	一個回應可產生的代幣數量上限，包括可見的輸出代幣和對話狀態。	No
parallel_tool_calls	boolean	是否允許模型平行執行工具呼叫。	No	True
previous_response_id	字串	之前對模型回應的唯一 ID。 利用這點創造多回合的對話。 了解更多關於會話狀態的資訊。	No
reasoning	Reasoning	推理模型的配置選項。	No
儲存	boolean	是否要儲存產生的模型回應，以便日後透過 API 檢索。	No	True
串流	boolean	若設定為 true，模型回應資料會在透過 伺服器發送事件產生時串流給用戶端。 更多資訊請參考下方的串流專區。	No	False
收發簡訊	物件	模型對文字回應的設定選項。 可以是純文字或結構化的 JSON 資料。 Learn more: - 文字輸入與輸出 - 結構化輸出	No
└─ format	TextResponseFormatConfiguration	一個指定模型必須輸出格式的物件。 設定 { "type": "json_schema" } 功能啟用結構化輸出，確保模型符合你提供的 JSON 架構。 預設格式是 { "type": "text" } 沒有額外選項。 不建議用於 GPT-4o 及更新型號： 設定啟用 { "type": "json_object" } 舊版 JSON 模式，確保模型產生的訊息是有效的 JSON。 支援 的模型會偏好使用json_schema	No
tool_choice	ToolChoiceOptions 或 ToolChoiceTypes 或 ToolChoiceFunction	模型在產生回應時應該如何選擇使用哪個（或多個工具）來進行回應。 請參閱參數， tools 了解如何指定模型可呼叫哪些工具。	No
tools	陣列	模型在產生回應時可能會呼叫的一系列工具。 你可以透過設定 tool_choice 參數來指定要使用哪個工具。 你可以提供模型兩類工具： - 內建工具：由 OpenAI 提供以擴充 model's capabilities	No
truncation	列舉	模型響應所採用的截斷策略。 - auto：如果此回應及先前回應的上下文超過模型的上下文視窗大小，模型會透過在對話中刪除輸入項目來截斷回應以符合上下文視窗。 - disabled （預設）：若模型回應超過模型的上下文視窗大小，請求將以 400 錯誤失敗。 可能的值： auto， disabled	No

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	response
text/event-stream	responseStreamEvent

狀態代碼： 預設

說明：無法提供服務

Content-Type	Type	Description
application/json	errorResponse

回應 API - 輸入項目

GET https://{endpoint}/openai/responses/{response_id}?api-version=2025-04-01-preview

取得具有指定 ID 的模型回應。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
response_id	路徑	Yes	字串	要取得的回應識別碼。
include	查詢	No	陣列	回應中需包含額外欄位。 更多資訊請參閱 include 上方回應建立參數。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	response

狀態代碼： 預設

說明：無法提供服務

Content-Type	Type	Description
application/json	errorResponse

Delete response

DELETE https://{endpoint}/openai/responses/{response_id}?api-version=2025-04-01-preview

刪除具有指定 ID 的模型回應。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
response_id	路徑	Yes	字串	刪除回應的ID。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

狀態代碼： 404

描述：未找到

Content-Type	Type	Description
application/json	error

狀態代碼： 預設

說明：無法提供服務

Content-Type	Type	Description
application/json	errorResponse

回應 API - 回應項目清單

GET https://{endpoint}/openai/responses/{response_id}/input_items?api-version=2025-04-01-preview

回傳給定回應的輸入項目清單。

URI Parameters

Name	In	Required	類型	Description
端點	路徑	Yes	string url	支援的 Azure OpenAI 端點（協定與主機名稱，例如： https://aoairesource.openai.azure.com請將「aoairesource」替換成你的 Azure OpenAI 資源名稱）。 https://{your-resource-name}.openai.azure.com
response_id	路徑	Yes	字串	回應的 ID，用來擷取輸入項目。
limit	查詢	No	整數	限制可歸還的物品數量。 限制範圍在1到100之間，預設為20。
順序	查詢	No	字串 可能的值： asc， desc	還輸入項目的順序。 預設為 asc。 - asc： 按升序回傳輸入項目。 - desc： 以遞減順序回傳輸入項目。
after	查詢	No	字串	一個項目 ID，用於分頁後的項目列表。
before	查詢	No	字串	一個用於分頁的項目 ID，用於之前的項目。

Request Header

使用基於權杖的認證或 API 金鑰。 建議使用基於憑證的認證來驗證，且更安全。

Name	Required	類型	Description
Authorization	True	字串	Example:Authorization: Bearer {Azure_OpenAI_Auth_Token} 使用 Azure CLI 產生認證憑證： az account get-access-token --resource https://cognitiveservices.azure.com Type: oauth2 授權網址： https://login.microsoftonline.com/common/oauth2/v2.0/authorize 範圍： https://ai.azure.com/.default
api-key	True	字串	請在此提供Azure OpenAI API key

Responses

狀態代碼： 200

Description: OK

Content-Type	Type	Description
application/json	responseItemList

Components

errorResponse

Name	類型	Description	Required	Default
錯誤	error		No

errorBase

Name	類型	Description	Required	Default
字碼	字串		No
訊息	字串		No

錯誤

Name	類型	Description	Required	Default
inner_error	innerError	內部錯誤加上額外細節。	No
param	字串		No
型別	字串		No

innerError

內部錯誤加上額外細節。

Name	類型	Description	Required	Default
字碼	innerErrorCode	內部錯誤物件的錯誤代碼。	No
content_filter_results	contentFilterPromptResults	關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。	No

innerErrorCode

內部錯誤物件的錯誤代碼。

Property	Value
Description	內部錯誤物件的錯誤代碼。
Type	字串
Values	ResponsibleAIPolicyViolation

dalleErrorResponse

Name	類型	Description	Required	Default
錯誤	dalleError		No

dalleError

Name	類型	Description	Required	Default
inner_error	dalleInnerError	內部錯誤加上額外細節。	No
param	字串		No
型別	字串		No

dalleInnerError

內部錯誤加上額外細節。

Name	類型	Description	Required	Default
字碼	innerErrorCode	內部錯誤物件的錯誤代碼。	No
content_filter_results	dalleFilterResults	關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。	No
revised_prompt	字串	如果提示有任何修改，就是用來產生圖片的提示。	No

contentFilterCompletionTextSpan

描述生成完結文字中的一個跨度。 偏移量 0 是補全文字的第一個 UTF32 碼點。

Name	類型	Description	Required	Default
completion_end_offset	整數	偏移第一個 UTF32 碼點，該碼點被排除在 span 之外。 對於空跨，這個欄位總是等於completion_start_offset。 對於非空的跨度，這個欄位總是大於completion_start_offset。	Yes
completion_start_offset	整數	起始區間的 UTF32 碼點的偏移量。	Yes

contentFilterResultBase

Name	類型	Description	Required	Default
filtered	boolean		Yes

contentFilterSeverityResult

Name	類型	Description	Required	Default
filtered	boolean		Yes
severity	字串		No

contentFilterDetectedResult

Name	類型	Description	Required	Default
detected	boolean		No
filtered	boolean		Yes

contentFilterDetectedWithCitationResult

Name	類型	Description	Required	Default
citation	物件		No
└─ URL	字串		No
└─ license	字串		No

contentFilterDetectedWithCompletionTextSpansResult

Name	類型	Description	Required	Default
details	陣列		No

contentFilterIdResult

Name	類型	Description	Required	Default
filtered	boolean		Yes
id	字串		No

contentFilterResultsBase

關於內容過濾結果的資訊。

Name	類型	Description	Required	Default
custom_blocklists	contentFilterDetailedResults	內容過濾會顯示被篩選區段的內容過濾 ID 細節。	No
錯誤	errorBase		No
hate	contentFilterSeverityResult		No
profanity	contentFilterDetectedResult		No
self_harm	contentFilterSeverityResult		No
sexual	contentFilterSeverityResult		No
violence	contentFilterSeverityResult		No

contentFilterPromptResults

關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。

Name	類型	Description	Required	Default
custom_blocklists	contentFilterDetailedResults	內容過濾會顯示被篩選區段的內容過濾 ID 細節。	No
錯誤	errorBase		No
hate	contentFilterSeverityResult		No
indirect_attack	contentFilterDetectedResult		No
jailbreak	contentFilterDetectedResult		No
profanity	contentFilterDetectedResult		No
self_harm	contentFilterSeverityResult		No
sexual	contentFilterSeverityResult		No
violence	contentFilterSeverityResult		No

contentFilterChoiceResults

關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於第三方簡訊和髒話的資訊，是否已被偵測到，以及是否被過濾過。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。

Name	類型	Description	Required	Default
custom_blocklists	contentFilterDetailedResults	內容過濾會顯示被篩選區段的內容過濾 ID 細節。	No
錯誤	errorBase		No
hate	contentFilterSeverityResult		No
profanity	contentFilterDetectedResult		No
protected_material_code	contentFilterDetectedWithCitationResult		No
protected_material_text	contentFilterDetectedResult		No
self_harm	contentFilterSeverityResult		No
sexual	contentFilterSeverityResult		No
ungrounded_material	contentFilterDetectedWithCompletionTextSpansResult		No
violence	contentFilterSeverityResult		No

contentFilterDetailedResults

內容過濾會顯示被篩選區段的內容過濾 ID 細節。

Name	類型	Description	Required	Default
details	陣列		No
filtered	boolean		Yes

promptFilterResult

請求中單一提示的內容過濾結果。

Name	類型	Description	Required	Default
content_filter_results	contentFilterPromptResults	關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。	No
prompt_index	整數		No

promptFilterResults

針對請求中零或多個提示的內容篩選結果。 在串流請求中，不同提示的結果可能在不同時間或順序出現。

此元件未定義屬性。

dalleContentFilterResults

關於內容過濾結果的資訊。

Name	類型	Description	Required	Default
hate	contentFilterSeverityResult		No
self_harm	contentFilterSeverityResult		No
sexual	contentFilterSeverityResult		No
violence	contentFilterSeverityResult		No

dalleFilterResults

關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。

Name	類型	Description	Required	Default
custom_blocklists	contentFilterDetailedResults	內容過濾會顯示被篩選區段的內容過濾 ID 細節。	No
hate	contentFilterSeverityResult		No
jailbreak	contentFilterDetectedResult		No
profanity	contentFilterDetectedResult		No
self_harm	contentFilterSeverityResult		No
sexual	contentFilterSeverityResult		No
violence	contentFilterSeverityResult		No

chatCompletionsRequestCommon

Name	類型	Description	Required	Default
frequency_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新標記在文本中現有的頻率來懲罰，降低模型逐字重複同一行的可能性。	No	0
logit_bias	物件	修改特定標記出現在完成項目中的可能性。 接受一個 json 物件，將標記器中由標記 ID 指定的標記映射到從 -100 到 100 的偏向值。 數學上，偏差會加到模型產生的對數值上，然後再進行抽樣。 具體效果因模型而異，但介於 -1 與1之間的數值應降低或增加選擇的可能性;像 -100 或 100 這類數值應該會導致封鎖或專屬選擇相關代幣。	No
max_completion_tokens	整數	完成化可產生的標記數量上限，包括可見輸出標記與推理標記。	No
max_tokens	整數	產生答案允許的最大代幣數。 預設情況下，模型可返回的標記數量為（4096 - 提示標記）。 這和 O1 系列機型不相容。	No	4096
中繼資料	物件	開發者定義的標籤與值，用於在儲存的完成儀表板中篩選完成事項。	No
presence_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新代幣是否出現在文本中來懲罰，增加模型談論新主題的可能性。	No	0
stop	字串或陣列	最多有 4 個序列，API 停止產生更多標記。	No
儲存	boolean	是否要儲存此聊天完成請求的輸出，以便用於我們的模型蒸餾或評估產品。	No
串流	boolean	若設定為此，會傳送部分訊息 delta，類似 ChatGPT 中的訊息。 代幣會以僅資料伺服器發送的事件形式發送，當事件可用時，串流會以訊息結束 data: [DONE] 。	No	False
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	No	1
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表最終使用者的獨特識別碼，能幫助 Azure OpenAI 監控並偵測濫用行為。	No

createCompletionRequest

Name	類型	Description	Required	Default
best_of	整數	在 best_of 伺服器端產生完成項目，並回傳「最佳」（每個標記日誌機率最高的完成）。 結果無法直播。 當與 一起使用 n時 best_of ，控制候選完成項目的數量並 n 指定要回傳的數量。 best_of 必須大於 n。 註： 由於這個參數會產生許多完成任務，它可能會迅速消耗你的代幣配額。 謹慎使用，並確保你對 和 max_tokens的設定stop合理。	No	1
echo	boolean	除了完成題外，還要回敬提示	No	False
frequency_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新標記在文本中現有的頻率來懲罰，降低模型逐字重複同一行的可能性。	No	0
logit_bias	物件	修改特定標記出現在完成項目中的可能性。 接受一個 JSON 物件，將 GPT 分名器中由 token ID 指定）映射到從 -100 到 100 的偏值。 數學上，偏差會加到模型產生的對數值上，然後再進行抽樣。 具體效果因模型而異，但介於 -1 與1之間的數值應降低或增加選擇的可能性;像 -100 或 100 這類數值應該會導致封鎖或專屬選擇相關代幣。 舉例來說，你可以通過， {"50256": -100} 以防止 <|endoftext|> 標記被產生。	No	None
logprobs	整數	包含最可能輸出標記的對數機率 logprobs ，以及所選標記。 例如，如果 logprobs 是 5，API 會回傳 5 個最可能的標記清單。 API 會回傳取樣標記的 ， logprob 因此回應中可能包含最多的 logprobs+1 元素。 最大 logprobs 值為5。	No	None
max_tokens	整數	完成過程中能產生的最大代幣數量。 你的提示 max_tokens 詞的標記數不能超過模型的上下文長度。	No	16
n	整數	每個提示要產生多少個完成題。 註： 由於這個參數會產生許多完成任務，它可能會迅速消耗你的代幣配額。 謹慎使用，並確保你對 和 max_tokens的設定stop合理。	No	1
presence_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新代幣是否出現在文本中來懲罰，增加模型談論新主題的可能性。	No	0
提示	字串或陣列	生成補全的提示，編碼為字串、字串陣列、標記陣列或標記陣列。 請注意， <|endoftext|> 是模型在訓練時看到的文件分隔符，因此如果未指定提示詞，模型會像從新文件開始一樣產生。	Yes
seed	整數	若有指定，系統會盡力以確定性方式取樣，使得重複請求且參數相同 seed 時應返回相同結果。 確定性並非保證，你應該參考 system_fingerprint 回應參數來監控後端的變化。	No
stop	字串或陣列	最多有 4 個序列，API 停止產生更多標記。 回傳的文字不會包含停止音序列。	No
串流	boolean	是否要回溯部分進度。 若設定為 token，代幣會在伺服器有資料時以事件形式傳送，串流以訊息終止data: [DONE]。 範例 Python 程式碼。	No	False
suffix	字串	插入文字完成後的後綴。 此參數僅支援於 gpt-3.5-turbo-instruct。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	No	1
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

createCompletionResponse

代表 API 的補全回應。 注意：串流與非串流回應物件的形狀相同（與聊天端點不同）。

Name	類型	Description	Required	Default
choices	陣列	模型為輸入提示產生的完成選項清單。	Yes
created	整數	Unix 的時間戳記（以秒計）顯示完成完成的建立時間。	Yes
id	字串	完成的唯一識別碼。	Yes
型號	字串	用於完備的模型。	Yes
物件	列舉	物件類型，永遠是「text_completion」 可能的數值： text_completion	Yes
prompt_filter_results	promptFilterResults	針對請求中零或多個提示的內容篩選結果。 在串流請求中，不同提示的結果可能在不同時間或順序出現。	No
system_fingerprint	字串	這個指紋代表模型所使用的後端配置。 可與請求參數結合使用 seed ，以了解何時後端變更可能影響確定性。	No
使用方式	completionUsage	完成請求的使用統計數據。	No

createChatCompletionRequest

Name	類型	Description	Required	Default
audio	物件	音訊輸出參數。 當音訊輸出被請求時 modalities: ["audio"]，必須 。	No
└─ format	列舉	指定輸出音訊格式。 必須是 wav、 mp3、 flac、 opus或 pcm16之一。 可能的值：wav， mp3， flacopuspcm16	No
└─ voice	列舉	指定聲音類型。 支援語態為 alloy、 echo、 fable、 onyxnovashimmer、 和 。 可能的值：alloy， echo， fableonyxnovashimmer	No
data_sources	陣列	使用 Azure OpenAI 聊天擴充功能的設定條目。 此額外規範僅與 Azure OpenAI 相容。	No
frequency_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新標記在文本中現有的頻率來懲罰，降低模型逐字重複同一行的可能性。	No	0
function_call	string 或 chatCompletionFunctionCallOption	已被棄用，改為 tool_choice。 控制模型呼叫哪個函式（若有的話）。 none 表示模型不會呼叫函式，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫函式。 指定特定函數 會 {"name": "my_function"} 迫使模型呼叫該函數。 none 當沒有函式存在時，是預設值。 auto 若函式存在，則為預設值。	No
functions	陣列	已被棄用，改為 tools。 模型可能產生 JSON 輸入的函數清單。	No
logit_bias	物件	修改特定標記出現在完成項目中的可能性。 接受一個 JSON 物件，將代幣（由代幣化器中由其 token ID 指定）映射到從 -100 到 100 的偏向值。 數學上，偏差會加到模型產生的對數值上，然後再進行抽樣。 具體效果因模型而異，但介於 -1 與1之間的數值應降低或增加選擇的可能性;像 -100 或 100 這類數值應該會導致封鎖或專屬選擇相關代幣。	No	None
logprobs	boolean	是否要回傳輸出標記的對數機率。 若為真，則回傳每個輸出符號在 content 的 message對數機率。	No	False
max_completion_tokens	整數	完成化可產生的標記數量上限，包括可見輸出標記與推理標記。	No
max_tokens	整數	聊天完成時能產生的最大代幣數量。 輸入標記與產生標記的總長度受模型上下文長度限制。	No
messages	陣列	這是目前對話內容的清單。 範例 Python 程式碼。	Yes
中繼資料	物件	開發者定義的標籤與值，用於在儲存的完成儀表板中篩選完成事項。	No
modalities	ChatCompletionModalities	你希望模型為此請求產生的輸出類型。 大多數模型都能產生文字，這是預設的： ["text"] 該 gpt-4o-audio-preview 模型也可用於產生音訊。 若要請求此模型同時產生文字與音訊回應，您可以使用： ["text", "audio"]	No
n	整數	每則輸入訊息要產生多少個聊天結束選項。 請注意，你將根據所有選項中產生的代幣數量收費。 盡量降低n1成本。	No	1
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
預測	PredictionContent	預測輸出的配置，當模型響應的大部分部分事先已知時，能大幅改善反應時間。 這種情況最常見於你重新生成檔案時，內容大部分只做些微調整。	No
presence_penalty	number	數字介於 -2.0 到 2.0 之間。 正值會根據新代幣是否出現在文本中來懲罰，增加模型談論新主題的可能性。	No	0
reasoning_effort	列舉	僅限 O1 模型 限制推理模型的推理努力。 目前支援的值為 low、 medium、 high和 。 減少推理努力能帶來更快的回應，並減少回應中用於推理的標記。 可能的值： low， medium， high	No
response_format	ResponseFormatText 或 ResponseFormatJsonObject 或 ResponseFormatJsonSchema	一個指定模型必須輸出格式的物件。 相容於 GPT-4o、GPT-4o mini、GPT-4 Turbo 以及所有更新於 Tar 的 gpt-3.5-turbo-1106 Turbo 模型。 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型符合你提供的 JSON 架構。 設定啟用 { "type": "json_object" } JSON 模式，保證模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
seed	整數	此功能目前仍處於測試階段。 若有指定，系統會盡力以確定性方式取樣，使得重複請求且參數相同 seed 時應返回相同結果。 確定性並非保證，你應該參考 system_fingerprint 回應參數來監控後端的變化。	No
stop	字串或陣列	最多有 4 個序列，API 停止產生更多標記。	No
儲存	boolean	是否要儲存此聊天完成請求的輸出，以便用於我們的模型蒸餾或評估產品。	No
串流	boolean	若設定為此，會傳送部分訊息 delta，類似 ChatGPT 中的訊息。 代幣會以僅資料伺服器 發送的事件 形式發送，當事件可用時，串流會以訊息結束 data: [DONE] 。 範例 Python 程式碼。	No	False
stream_options	chatCompletionStreamOptions	串流回應選項。 只有在你設定 stream: true時才會設定這個。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	No	1
tool_choice	chatCompletionToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫一個或多個工具。 required 表示模型必須呼叫一個或多個工具。 指定特定工具 透過 會 {"type": "function", "function": {"name": "my_function"}} 強制模型呼叫該工具。 none 當沒有工具時，預設是。 auto 如果有工具，則是預設。	No
tools	陣列	模型可能呼叫的工具清單。 目前僅支援函式作為工具。 利用此資料提供模型可能產生 JSON 輸入的函式清單。 最多支援 128 個函式。	No
top_logprobs	整數	一個介於0到20之間的整數，表示每個標記位置最可能回傳的標記數量，每個標記具有對數機率。 logprobs 若使用此參數，必須設定為 true 。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No
user_security_context	userSecurityContext	使用者安全情境包含多個參數，描述 AI 應用程式本身及與 AI 應用程式互動的最終使用者。 這些領域協助您的資安營運團隊調查並減輕安全事件，提供全面的方法來保護您的 AI 應用。 了解更多 關於使用 適用於雲端的 Microsoft Defender 保護 AI 應用的方法。	No

userSecurityContext

使用者安全情境包含多個參數，描述 AI 應用程式本身及與 AI 應用程式互動的最終使用者。 這些領域協助您的資安營運團隊調查並減輕安全事件，提供全面的方法來保護您的 AI 應用。 了解更多 關於使用 適用於雲端的 Microsoft Defender 保護 AI 應用的方法。

Name	類型	Description	Required	Default
application_name	字串	申請名稱。 敏感個人資訊不應包含在本欄位。	No
end_user_id	字串	此識別碼為 Microsoft Entra ID（前稱 Azure Active Directory）使用者物件 ID，用於生成式 AI 應用中驗證終端使用者。 敏感個人資訊不應包含在本欄位。	No
end_user_tenant_id	字串	最終使用者所屬的 Microsoft 365 租戶 ID。 當生成式 AI 應用是多租戶時，這是必須的。	No
source_ip	字串	擷取原始用戶端的 IP 位址，接受 IPv4 與 IPv6 兩種格式。	No

chatCompletionFunctions

Name	類型	Description	Required	Default
description	字串	描述函式的功能，模型用來決定何時以及如何呼叫函式。	No
name	字串	要呼叫的函式名稱。 必須是 a-z、A-Z、0-9，或包含底線和破折號，長度最多為 64。	Yes
parameters	FunctionParameters	函式所接受的參數，描述為 JSON Schema 物件。 請參閱範例指南 ，以及 JSON Schema 參考資料 中關於格式的文件。 省略 parameters 定義了一個參數列表為空的函數。	No

chatCompletionFunctionCallOption

指定特定函數 會 {"name": "my_function"} 迫使模型呼叫該函數。

Name	類型	Description	Required	Default
name	字串	要呼叫的函式名稱。	Yes

chatCompletionFunctionParameters

函式所接受的參數，描述為 JSON Schema 物件。 範例請參考 指南/ ，以及 JSON Schema 參考資料 中關於格式的文件。

此元件未定義屬性。

chatCompletionRequestMessage

此組件可為以下之一：

• ChatCompletionRequestDeveloperMessage
• chatCompletionRequestSystemMessage
• chatCompletionRequestUserMessage
• chatCompletionRequestAssistantMessage
• chatCompletionRequestToolMessage
• chatCompletionRequestFunctionMessage

ChatCompletionRequestDeveloperMessage

開發者提供的指示，模型應遵循，無論使用者發送了什麼訊息。 在 O1 及更新型號中，訊息會 developer 取代先前 system 的訊息。

Name	類型	Description	Required	Default
內容	字串或陣列	開發者訊息的內容。	Yes
name	字串	參與者的可選名字。 提供模型資訊以區分同一角色的參與者。	No
角色	列舉	訊息作者的角色，在此例 developer中。 可能的數值： developer	Yes

chatCompletionRequestSystemMessage

Name	類型	Description	Required	Default
內容	字串或陣列	系統訊息的內容。	Yes
name	字串	參與者的可選名字。 提供模型資訊以區分同一角色的參與者。	No
角色	列舉	訊息作者的角色，在此例 system中。 可能的數值： system	Yes

chatCompletionRequestUserMessage

Name	類型	Description	Required	Default
內容	字串或陣列	使用者訊息的內容。	Yes
name	字串	參與者的可選名字。 提供模型資訊以區分同一角色的參與者。	No
角色	列舉	訊息作者的角色，在此例 user中。 可能的數值： user	Yes

chatCompletionRequestAssistantMessage

Name	類型	Description	Required	Default
內容	字串或陣列	助理訊息的內容。 除非tool_callsfunction_call有規定或是必須的。	No
function_call	物件	已棄用並被 tool_calls取代。 模型產生的函式名稱與參數。	No
└─ arguments	字串	呼叫函式的參數，由模型以 JSON 格式產生。 請注意，模型並不總是產生有效的 JSON，且可能會產生未由函式結構定義的參數。 在呼叫函式前，先驗證程式碼中的參數。	No
└─ name	字串	要呼叫的函式名稱。	No
name	字串	參與者的可選名字。 提供模型資訊以區分同一角色的參與者。	No
refusal	字串	助理的拒絕訊息。	No
角色	列舉	訊息作者的角色，在此例 assistant中。 可能的數值： assistant	Yes
tool_calls	chatCompletionMessageToolCalls	模型產生的工具呼叫，例如函式呼叫。	No

chatCompletionRequestToolMessage

Name	類型	Description	Required	Default
內容	字串或陣列	工具訊息的內容。	Yes
角色	列舉	訊息作者的角色，在此例 tool中。 可能的數值： tool	Yes
tool_call_id	字串	這個訊息正在回應的工具呼叫。	Yes

chatCompletionRequestFunctionMessage

Name	類型	Description	Required	Default
內容	字串	函式訊息的內容。	Yes
name	字串	要呼叫的函式名稱。	Yes
角色	列舉	訊息作者的角色，在此例 function中。 可能的數值： function	Yes

chatCompletionRequestDeveloperMessageContentPart

此組件可為以下之一：

• chatCompletionRequestMessageContentPartText

chatCompletionRequestSystemMessageContentPart

此組件可為以下之一：

• chatCompletionRequestMessageContentPartText

chatCompletionRequestUserMessageContentPart

此組件可為以下之一：

• chatCompletionRequestMessageContentPartText
• chatCompletionRequestMessageContentPartImage
• chatCompletionRequestMessageContentPartAudio

chatCompletionRequestAssistantMessageContentPart

此組件可為以下之一：

• chatCompletionRequestMessageContentPartText
• chatCompletionRequestMessageContentPartRefusal

chatCompletionRequestToolMessageContentPart

此組件可為以下之一：

• chatCompletionRequestMessageContentPartText

chatCompletionRequestMessageContentPartText

Name	類型	Description	Required	Default
收發簡訊	字串	文字內容。	Yes
型別	列舉	內容的類型。 可能的數值： text	Yes

chatCompletionRequestMessageContentPartAudio

Name	類型	Description	Required	Default
input_audio	物件		Yes
└─ data	字串	Base64 編碼音訊資料。	No
└─ format	列舉	編碼音訊資料的格式。 目前支援「wav」和「mp3」。 可能的值： wav， mp3	No
型別	列舉	內容的類型。 永遠如此 input_audio。 可能的數值： input_audio	Yes

chatCompletionRequestMessageContentPartImage

Name	類型	Description	Required	Default
image_url	物件		Yes
└─ detail	列舉	指定影像的細節等級。 在《 願景指南》中了解更多。 可能的值： auto， low， high	No
└─ url	字串	圖片的網址或 base64 編碼的影像資料。	No
型別	列舉	內容的類型。 可能的數值： image_url	Yes

chatCompletionRequestMessageContentPartRefusal

Name	類型	Description	Required	Default
refusal	字串	模型產生的拒絕訊息。	Yes
型別	列舉	內容的類型。 可能的數值： refusal	Yes

azureChatExtensionConfiguration

一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。

###azureChatExtensionConfiguration 的鑑別子

此元件利用特性 type 來區分不同類型：

Type Value	Schema
azure_search	azureSearchChatExtensionConfiguration
azure_cosmos_db	azureCosmosDBChatExtensionConfiguration
elasticsearch	elasticsearchChatExtensionConfiguration
mongo_db	mongoDBChatExtensionConfiguration
pinecone	pineconeChatExtensionConfiguration

Name	類型	Description	Required	Default
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

azureChatExtensionType

一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。

Property	Value
Description	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。
Type	字串
Values	azure_search azure_cosmos_db elasticsearch mongo_db pinecone

azureSearchChatExtensionConfiguration

這是使用 Azure Search 作為 Azure OpenAI 聊天擴充功能時可設定選項的具體表示。

Name	類型	Description	Required	Default
parameters	azureSearchChatExtensionParameters	Azure Search 作為 Azure OpenAI 聊天擴充功能時的參數。	No
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

azureSearchChatExtensionParameters

Azure Search 作為 Azure OpenAI 聊天擴充功能時的參數。

Name	類型	Description	Required	Default
allow_partial_result	boolean	若指定為真，系統將允許使用部分搜尋結果，若所有查詢皆失敗，請求即告失敗。 若未指定或指定為 false，且任何搜尋查詢皆失敗，請求將失敗。	No	False
認證	在 yourDataApiKeyAuthenticationOptions 或 在 yourDataSystemAssignedManagedIdentity 認證 選項 或 on yourDataUserAssignedManagedIdentityAuthenticationOptions， 或在 yourDataAccess TokenAuthenticationOptions 上		Yes
embedding_dependency	onYourDataEndpointVectorizationSource 或 onYourDataDeploymentNameVectorizationSource 或 onYourDataIntegratedVectorizationSource		No
端點	字串	Azure Search 資源的絕對端點路徑。	Yes
fields_mapping	azureSearchIndexFieldMappingOptions	可選設定，用來控制使用配置 Azure Search 資源時欄位的處理方式。	No
篩選	字串	Search filter.	No
in_scope	boolean	查詢是否應該限制使用索引資料。	No
include_contexts	陣列	輸出上下文中包含的屬性。 若未指定，預設值為 citations 和 intent。	No
index_name	字串	在參考的 Azure Search 資源中，使用的索引名稱。	Yes
max_search_queries	整數	重寫查詢的最大數量應送達搜尋提供者，針對一則使用者訊息。 若未指定，系統將決定發送多少查詢。	No
query_type	azureSearchQueryType	當它作為 Azure OpenAI 聊天擴充功能時，應該執行的 Azure Search 檢索查詢類型。	No
semantic_configuration	字串	查詢的額外語意配置。	No
strictness	整數	搜尋相關性過濾的嚴格度。 嚴格度越高，答案的精確度越高但回憶力越低。	No
top_n_documents	整數	設定的最高文件數量，以供已設定的查詢功能。	No

azureSearchIndexFieldMappingOptions

可選設定，用來控制使用配置 Azure Search 資源時欄位的處理方式。

Name	類型	Description	Required	Default
content_fields	陣列	應該被視為內容的索引欄位名稱。	No
content_fields_separator	字串	內容欄位應該使用的分隔符模式。	No
filepath_field	字串	索引欄位名稱，作為檔案路徑。	No
image_vector_fields	陣列	代表影像向量資料的欄位名稱。	No
title_field	字串	用作標題的索引欄位名稱。	No
url_field	字串	索引欄位的名稱，作為網址。	No
vector_fields	陣列	代表向量資料的欄位名稱。	No

azureSearchQueryType

當它作為 Azure OpenAI 聊天擴充功能時，應該執行的 Azure Search 檢索查詢類型。

Property	Value
Description	當它作為 Azure OpenAI 聊天擴充功能時，應該執行的 Azure Search 檢索查詢類型。
Type	字串
Values	simple semantic vector vector_simple_hybrid vector_semantic_hybrid

azureCosmosDBChatExtensionConfiguration

這是使用 Azure Cosmos DB 作為 Azure OpenAI 聊天擴充功能時，可配置選項的具體表示。

Name	類型	Description	Required	Default
parameters	azureCosmosDBChatExtensionParameters	設定 Azure OpenAI On Your Data 聊天擴充時使用的參數，使用 Azure Cosmos DB for MongoDB vCore。	No
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

azureCosmosDBChatExtensionParameters

設定 Azure OpenAI On Your Data 聊天擴充時使用的參數，使用 Azure Cosmos DB for MongoDB vCore。

Name	類型	Description	Required	Default
allow_partial_result	boolean	若指定為真，系統將允許使用部分搜尋結果，若所有查詢皆失敗，請求即告失敗。 若未指定或指定為 false，且任何搜尋查詢皆失敗，請求將失敗。	No	False
認證	onYourDataConnectionStringAuthenticationOptions	Azure OpenAI 在使用連接字串時的認證選項。	Yes
container_name	字串	Azure Cosmos DB 資源容器的名稱。	Yes
database_name	字串	MongoDB vCore 資料庫名稱，用於 Azure Cosmos DB。	Yes
embedding_dependency	onYourDataEndpointVectorizationSource 或 onYourDataDeploymentNameVectorizationSource		Yes
fields_mapping	azureCosmosDBFieldMappingOptions	可選設定，用來控制使用已設定 Azure Cosmos 資料庫資源時欄位的處理方式。	Yes
in_scope	boolean	查詢是否應該限制使用索引資料。	No
include_contexts	陣列	輸出上下文中包含的屬性。 若未指定，預設值為 citations 和 intent。	No
index_name	字串	MongoDB vCore 索引名稱，用於 Azure Cosmos 資料庫。	Yes
max_search_queries	整數	重寫查詢的最大數量應送達搜尋提供者，針對一則使用者訊息。 若未指定，系統將決定發送多少查詢。	No
strictness	整數	搜尋相關性過濾的嚴格度。 嚴格度越高，答案的精確度越高但回憶力越低。	No
top_n_documents	整數	設定的最高文件數量，以供已設定的查詢功能。	No

azureCosmosDBFieldMappingOptions

可選設定，用來控制使用已設定 Azure Cosmos 資料庫資源時欄位的處理方式。

Name	類型	Description	Required	Default
content_fields	陣列	應該被視為內容的索引欄位名稱。	Yes
content_fields_separator	字串	內容欄位應該使用的分隔符模式。	No
filepath_field	字串	索引欄位名稱，作為檔案路徑。	No
title_field	字串	用作標題的索引欄位名稱。	No
url_field	字串	索引欄位的名稱，作為網址。	No
vector_fields	陣列	代表向量資料的欄位名稱。	Yes

elasticsearchChatExtensionConfiguration

這是 Elasticsearch 作為 Azure OpenAI 聊天擴充功能時可設定選項的具體表示。

Name	類型	Description	Required	Default
parameters	elasticsearchChatExtensionParameters	設定 Elasticsearch® 作為 Azure OpenAI 聊天擴充功能時使用的參數。	No
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

elasticsearchChatExtensionParameters

設定 Elasticsearch® 作為 Azure OpenAI 聊天擴充功能時使用的參數。

Name	類型	Description	Required	Default
allow_partial_result	boolean	若指定為真，系統將允許使用部分搜尋結果，若所有查詢皆失敗，請求即告失敗。 若未指定或指定為 false，且任何搜尋查詢皆失敗，請求將失敗。	No	False
認證	onYourDataKeyAndKeyIdAuthenticationOptions 或 onYourDataEncodedApiKeyAuthenticationOptions		Yes
embedding_dependency	onYourDataEndpointVectorizationSource 或 onYourDataDeploymentNameVectorizationSource 或 onYourDataModelIdVectorizationSource		No
端點	字串	Elasticsearch® 的終點。	Yes
fields_mapping	elasticsearchIndexFieldMappingOptions	可選設定，可控制欄位在使用已設定的 Elasticsearch® 資源時如何處理。	No
in_scope	boolean	查詢是否應該限制使用索引資料。	No
include_contexts	陣列	輸出上下文中包含的屬性。 若未指定，預設值為 citations 和 intent。	No
index_name	字串	Elasticsearch® 的索引名稱。	Yes
max_search_queries	整數	重寫查詢的最大數量應送達搜尋提供者，針對一則使用者訊息。 若未指定，系統將決定發送多少查詢。	No
query_type	elasticsearchQueryType	當 Elasticsearch® 作為 Azure OpenAI 聊天擴充功能時，應該執行的擷取查詢類型。	No
strictness	整數	搜尋相關性過濾的嚴格度。 嚴格度越高，答案的精確度越高但回憶力越低。	No
top_n_documents	整數	設定的最高文件數量，以供已設定的查詢功能。	No

elasticsearchIndexFieldMappingOptions

可選設定，可控制欄位在使用已設定的 Elasticsearch® 資源時如何處理。

Name	類型	Description	Required	Default
content_fields	陣列	應該被視為內容的索引欄位名稱。	No
content_fields_separator	字串	內容欄位應該使用的分隔符模式。	No
filepath_field	字串	索引欄位名稱，作為檔案路徑。	No
title_field	字串	用作標題的索引欄位名稱。	No
url_field	字串	索引欄位的名稱，作為網址。	No
vector_fields	陣列	代表向量資料的欄位名稱。	No

elasticsearchQueryType

當 Elasticsearch® 作為 Azure OpenAI 聊天擴充功能時，應該執行的擷取查詢類型。

Property	Value
Description	當 Elasticsearch® 作為 Azure OpenAI 聊天擴充功能時，應該執行的擷取查詢類型。
Type	字串
Values	simple vector

mongoDBChatExtensionConfiguration

Mongo DB 作為 Azure OpenAI 聊天擴充功能時，可配置選項的具體表示。

Name	類型	Description	Required	Default
parameters	mongoDBChatExtensionParameters	使用 Mongo DB 時，設定 Azure OpenAI On Your Data 聊天擴充時應用的參數。	No
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

mongoDBChatExtensionParameters

使用 Mongo DB 時，設定 Azure OpenAI On Your Data 聊天擴充時應用的參數。

Name	類型	Description	Required	Default
allow_partial_result	boolean	若指定為真，系統將允許使用部分搜尋結果，若所有查詢皆失敗，請求即告失敗。 若未指定或指定為 false，且任何搜尋查詢皆失敗，請求將失敗。	No	False
app_name	字串	Mongo 資料庫應用程式的名稱。	Yes
認證	onYourDataUsernameAndPasswordAuthenticationOptions	Azure OpenAI 在使用使用者名稱和密碼時的認證選項。	Yes
collection_name	字串	Mongo DB 收藏的名稱。	Yes
database_name	字串	Mongo 資料庫的名稱。	Yes
embedding_dependency	onYourDataEndpointVectorizationSource 或 onYourDataDeploymentNameVectorizationSource		Yes
端點	字串	Mongo DB 叢集端點的名稱。	Yes
fields_mapping	mongoDBFieldMappingOptions	可選設定，用來控制使用已設定 Mongo 資料庫資源時欄位的處理方式。	Yes
in_scope	boolean	查詢是否應該限制使用索引資料。	No
include_contexts	陣列	輸出上下文中包含的屬性。 若未指定，預設值為 citations 和 intent。	No
index_name	字串	Mongo DB 指數的名稱。	Yes
max_search_queries	整數	重寫查詢的最大數量應送達搜尋提供者，針對一則使用者訊息。 若未指定，系統將決定發送多少查詢。	No
strictness	整數	搜尋相關性過濾的嚴格度。 嚴格度越高，答案的精確度越高但回憶力越低。	No
top_n_documents	整數	設定的最高文件數量，以供已設定的查詢功能。	No

mongoDBFieldMappingOptions

可選設定，用來控制使用已設定 Mongo 資料庫資源時欄位的處理方式。

Name	類型	Description	Required	Default
content_fields	陣列	應該被視為內容的索引欄位名稱。	Yes
content_fields_separator	字串	內容欄位應該使用的分隔符模式。	No
filepath_field	字串	索引欄位名稱，作為檔案路徑。	No
title_field	字串	用作標題的索引欄位名稱。	No
url_field	字串	索引欄位的名稱，作為網址。	No
vector_fields	陣列	代表向量資料的欄位名稱。	Yes

pineconeChatExtensionConfiguration

這是一個針對 Pinecone 作為 Azure OpenAI 聊天擴充功能時可設定選項的具體表示。

Name	類型	Description	Required	Default
parameters	pineconeChatExtensionParameters	配置Azure OpenAI Pinecone聊天擴展的參數。	No
型別	azureChatExtensionType	一個針對單一 Azure OpenAI 聊天擴充套件的配置資料表示。 這將用於聊天完成請求，並應使用 Azure OpenAI 聊天擴充功能來增強回應行為。 此配置僅與 Azure OpenAI 相容。	Yes

pineconeChatExtensionParameters

配置Azure OpenAI Pinecone聊天擴展的參數。

Name	類型	Description	Required	Default
allow_partial_result	boolean	若指定為真，系統將允許使用部分搜尋結果，若所有查詢皆失敗，請求即告失敗。 若未指定或指定為 false，且任何搜尋查詢皆失敗，請求將失敗。	No	False
認證	onYourDataApiKeyAuthenticationOptions	Azure OpenAI 在使用 API 金鑰時的認證選項。	Yes
embedding_dependency	onYourDataDeploymentNameVectorizationSource	Azure OpenAI 在應用向量搜尋時所使用的向量化來源的細節，該來源基於同一 Azure OpenAI 資源中內部嵌入模型部署名稱。	Yes
環境	字串	松果的環境名稱。	Yes
fields_mapping	pineconeFieldMappingOptions	可選設定，用來控制使用設定 Pinecone 資源時欄位的處理方式。	Yes
in_scope	boolean	查詢是否應該限制使用索引資料。	No
include_contexts	陣列	輸出上下文中包含的屬性。 若未指定，預設值為 citations 和 intent。	No
index_name	字串	松果資料庫索引的名稱。	Yes
max_search_queries	整數	重寫查詢的最大數量應送達搜尋提供者，針對一則使用者訊息。 若未指定，系統將決定發送多少查詢。	No
strictness	整數	搜尋相關性過濾的嚴格度。 嚴格度越高，答案的精確度越高但回憶力越低。	No
top_n_documents	整數	設定的最高文件數量，以供已設定的查詢功能。	No

pineconeFieldMappingOptions

可選設定，用來控制使用設定 Pinecone 資源時欄位的處理方式。

Name	類型	Description	Required	Default
content_fields	陣列	應該被視為內容的索引欄位名稱。	Yes
content_fields_separator	字串	內容欄位應該使用的分隔符模式。	No
filepath_field	字串	索引欄位名稱，作為檔案路徑。	No
title_field	字串	用作標題的索引欄位名稱。	No
url_field	字串	索引欄位的名稱，作為網址。	No

onYourDataAuthenticationOptions

Azure OpenAI 在你資料上的認證選項。

onYourData 認證選項的識別器

此元件利用特性 type 來區分不同類型：

Type Value	Schema
api_key	onYourDataApiKeyAuthenticationOptions
connection_string	onYourDataConnectionStringAuthenticationOptions
key_and_key_id	onYourDataKeyAndKeyIdAuthenticationOptions
encoded_api_key	onYourDataEncodedApiKeyAuthenticationOptions
access_token	onYourDataAccessTokenAuthenticationOptions
system_assigned_managed_identity	onYourDataSystemAssignedManagedIdentityAuthenticationOptions
user_assigned_managed_identity	onYourDataUserAssignedManagedIdentityAuthenticationOptions
username_and_password	onYourDataUsernameAndPasswordAuthenticationOptions

Name	類型	Description	Required	Default
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataContextProperty

上下文特性。

Property	Value
Description	上下文特性。
Type	字串
Values	citations intent all_retrieved_documents

onYourDataAuthenticationType

Azure OpenAI 在你的資料上所支援的認證類型。

Property	Value
Description	Azure OpenAI 在你的資料上所支援的認證類型。
Type	字串
Values	api_key connection_string key_and_key_id encoded_api_key access_token system_assigned_managed_identity user_assigned_managed_identity username_and_password

onYourDataApiKeyAuthenticationOptions

Azure OpenAI 在使用 API 金鑰時的認證選項。

Name	類型	Description	Required	Default
Key	字串	用於認證的 API 金鑰。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataConnectionStringAuthenticationOptions

Azure OpenAI 在使用連接字串時的認證選項。

Name	類型	Description	Required	Default
connection_string	字串	用於認證的連線字串。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataKeyAndKeyIdAuthenticationOptions

Azure OpenAI On Your Data 在使用 Elasticsearch 金鑰與金鑰 ID 配對時的認證選項。

Name	類型	Description	Required	Default
Key	字串	Elasticsearch 金鑰用於認證。	No
key_id	字串	用於驗證的 Elasticsearch 金鑰 ID。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataEncodedApiKeyAuthenticationOptions

使用 Elasticsearch 編碼的 API 金鑰時，Azure OpenAI 在你的資料上的認證選項。

Name	類型	Description	Required	Default
encoded_api_key	字串	Elasticsearch 編碼的 API 金鑰用於認證。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataAccessTokenAuthenticationOptions

Azure OpenAI 在使用存取權杖時的認證選項。

Name	類型	Description	Required	Default
access_token	字串	用於驗證的存取權杖。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataSystemAssignedManagedIdentityAuthenticationOptions

Azure OpenAI On Your Data 在使用系統指派管理身份時的認證選項。

Name	類型	Description	Required	Default
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataUserAssignedManagedIdentityAuthenticationOptions

Azure OpenAI 在使用使用者指派的管理身份時，對你的資料進行認證選項。

Name	類型	Description	Required	Default
managed_identity_resource_id	字串	使用者指派的管理身份用於認證的資源 ID。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes

onYourDataUsernameAndPasswordAuthenticationOptions

Azure OpenAI 在使用使用者名稱和密碼時的認證選項。

Name	類型	Description	Required	Default
密碼	字串	The password. 用於認證。	No
型別	onYourDataAuthenticationType	Azure OpenAI 在你的資料上所支援的認證類型。	Yes
使用者名稱	字串	用來驗證的用戶名稱。	No

onYourDataVectorizationSource

Azure OpenAI On Your Data 的向量化來源抽象表示，並具備向量搜尋功能。

此元件利用特性 type 來區分不同類型：

Type Value	Schema
endpoint	onYourDataEndpointVectorizationSource
deployment_name	onYourDataDeploymentNameVectorizationSource
integrated	onYourDataIntegratedVectorizationSource
model_id	onYourDataModelIdVectorizationSource

Name	類型	Description	Required	Default
型別	onYourDataVectorizationSourceType	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。	Yes

onYourDataVectorizationSourceType

代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。

Property	Value
Description	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。
Type	字串
Values	endpoint deployment_name integrated model_id

onYourDataEndpointVectorizationSource

Azure OpenAI On Your Data 在應用向量搜尋時所使用的向量化來源細節，該來源基於公開的 Azure OpenAI 端點嵌入呼叫。

Name	類型	Description	Required	Default
認證	onYourDataApiKeyAuthenticationOptions 或 onYourDataAccessTokenAuthenticationOptions		No
dimensions	整數	嵌入應有的維度數。 僅支援於 text-embedding-3 及後期型號。	No
端點	字串	指定應從中擷取嵌入的資源端點 URL。 它應該是格式 https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings。 API 版本的查詢參數是不允許的。	No
型別	onYourDataVectorizationSourceType	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。	Yes

onYourDataDeploymentNameVectorizationSource

Azure OpenAI On Your Data 在應用向量搜尋時所使用的向量化來源的詳細資訊，該來源基於同一 Azure OpenAI 資源中的內部嵌入模型部署名稱。

Name	類型	Description	Required	Default
deployment_name	字串	指定用於向量化的模型部署名稱。 此模型部署必須在同一 Azure OpenAI 資源中，但 On Your Data 將透過內部呼叫而非公開呼叫使用此模型部署，這使得即使在私人網路中也能進行向量搜尋。	No
dimensions	整數	嵌入應有的維度數。 僅支援於 text-embedding-3 及後期型號。	No
型別	onYourDataVectorizationSourceType	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。	Yes

onYourDataIntegratedVectorizationSource

代表搜尋資源中定義的整合向量器。

Name	類型	Description	Required	Default
型別	onYourDataVectorizationSourceType	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。	Yes

onYourDataModelIdVectorizationSource

Azure OpenAI On Your Data 在應用向量搜尋時所使用的向量化來源的詳細資訊，該來源基於搜尋服務模型 ID。 目前僅由 Elasticsearch 支援。®

Name	類型	Description	Required	Default
model_id	字串	指定用於向量化的模型 ID。 此模型 ID 必須在搜尋服務中定義。	No
型別	onYourDataVectorizationSourceType	代表可用來源：Azure OpenAI On Your Data 可用來設定資料向量化以配合向量搜尋。	Yes

azureChatExtensionsMessageContext

當 Azure OpenAI 聊天擴充功能參與生成對應聊天完成回應時，可獲得的額外上下文資訊表示。 這些上下文資訊只有在使用 Azure OpenAI 請求並設定為匹配擴充功能時才會被填入。

Name	類型	Description	Required	Default
all_retrieved_documents	陣列	所有已取回的文件。	No
citations	陣列	資料來源檢索結果，用於產生回應中的助理訊息。	No
意圖	字串	聊天記錄中偵測到的意圖會傳遞到下一回合，以傳遞上下文。	No

citation

聊天完成回應訊息的引用資訊。

Name	類型	Description	Required	Default
chunk_id	字串	罰單的區塊識別碼。	No
內容	字串	表彰內容。	Yes
filepath	字串	引用的檔案路徑。	No
rerank_score	number	檢索文件的重新排名分數。	No
title	字串	表揚書的標題。	No
url	字串	引用的網址。	No

retrievedDocument

取回的文件。

Name	類型	Description	Required	Default
chunk_id	字串	罰單的區塊識別碼。	No
內容	字串	表彰內容。	Yes
data_source_index	整數	資料來源的索引。	No
filepath	字串	引用的檔案路徑。	No
filter_reason	filterReason	檢索文件的過濾原因。	No
original_search_score	number	檢索文件的原始搜尋分數。	No
rerank_score	number	檢索文件的重新排名分數。	No
search_queries	陣列	用來檢索文件的搜尋查詢。	No
title	字串	表揚書的標題。	No
url	字串	引用的網址。	No

filterReason

檢索文件的過濾原因。

Property	Value
Description	檢索文件的過濾原因。
Type	字串
Values	score rerank

chatCompletionMessageToolCall

Name	類型	Description	Required	Default
函式	物件	模型呼叫的函數。	Yes
└─ arguments	字串	呼叫函式的參數，由模型以 JSON 格式產生。 請注意，模型並不總是產生有效的 JSON，且可能會產生未由函式結構定義的參數。 在呼叫函式前，先驗證程式碼中的參數。	No
└─ name	字串	要呼叫的函式名稱。	No
id	字串	工具呼叫的ID。	Yes
型別	toolCallType	工具呼叫的類型，在此例 function中為 。	Yes

toolCallType

工具呼叫的類型，在此例 function中為 。

Property	Value
Description	工具呼叫的類型，在此例 function中為 。
Type	字串
Values	function

chatCompletionRequestMessageTool

Name	類型	Description	Required	Default
內容	字串	訊息內容。	No
tool_call_id	字串	這個訊息正在回應的工具呼叫。	No

chatCompletionRequestMessageFunction

Name	類型	Description	Required	Default
內容	字串	訊息內容。	No
name	字串	訊息內容。	No
角色	列舉	訊息作者的角色，在此例 function中。 可能的數值： function	No

createChatCompletionResponse

代表模型根據所提供輸入回傳的聊天完成回應。

Name	類型	Description	Required	Default
choices	陣列	聊天完成選項列表。 如果 大於 1， n 則可以多於一個。	Yes
created	整數	Unix 的時間戳（以秒計）顯示聊天完成的時間點。	Yes
id	字串	聊天完成的唯一識別碼。	Yes
型號	字串	聊天完成所使用的模型。	Yes
物件	列舉	物件類型，永遠 chat.completion為 。 可能的數值： chat.completion	Yes
prompt_filter_results	promptFilterResults	針對請求中零或多個提示的內容篩選結果。 在串流請求中，不同提示的結果可能在不同時間或順序出現。	No
system_fingerprint	字串	這個指紋代表模型所使用的後端配置。 可與請求參數結合使用 seed ，以了解何時後端變更可能影響確定性。	No
使用方式	completionUsage	完成請求的使用統計數據。	No

createChatCompletionStreamResponse

代表模型根據所提供輸入回傳的聊天完成回應串流片段。

Name	類型	Description	Required	Default
choices	陣列	聊天完成選項列表。 若 大於 1， n 則可包含多個元素。	Yes
created	整數	Unix 的時間戳（以秒計）顯示聊天完成的時間點。 每個區塊的時間戳記都一樣。	Yes
id	字串	聊天完成的唯一識別碼。 每個區塊的 ID 相同。	Yes
型號	字串	產生完備化的模型。	Yes
物件	列舉	物件類型，永遠 chat.completion.chunk為 。 可能的數值： chat.completion.chunk	Yes
system_fingerprint	字串	這個指紋代表模型所使用的後端配置。 可與請求參數結合使用 seed ，以了解何時後端變更可能影響確定性。	No

chatCompletionStreamResponseDelta

由串流模型回應產生的聊天完成 delta。

Name	類型	Description	Required	Default
內容	字串	區塊訊息的內容。	No
function_call	物件	已棄用並被 tool_calls取代。 模型產生的函式名稱與參數。	No
└─ arguments	字串	呼叫函式的參數，由模型以 JSON 格式產生。 請注意，模型並不總是產生有效的 JSON，且可能會產生未由函式結構定義的參數。 在呼叫函式前，先驗證程式碼中的參數。	No
└─ name	字串	要呼叫的函式名稱。	No
refusal	字串	模型產生的拒絕訊息。	No
角色	列舉	這則訊息作者的角色。 可能的值：system， ， userassistant，tool	No
tool_calls	陣列		No

chatCompletionMessageToolCallChunk

Name	類型	Description	Required	Default
函式	物件		No
└─ arguments	字串	呼叫函式的參數，由模型以 JSON 格式產生。 請注意，模型並不總是產生有效的 JSON，且可能會產生未由函式結構定義的參數。 在呼叫函式前，先驗證程式碼中的參數。	No
└─ name	字串	要呼叫的函式名稱。	No
id	字串	工具呼叫的ID。	No
索引	整數		Yes
型別	列舉	工具的種類。 目前僅 function 支援。 可能的數值： function	No

chatCompletionStreamOptions

串流回應選項。 只有在你設定 stream: true時才會設定這個。

Name	類型	Description	Required	Default
include_usage	boolean	若設定為此，訊息前 data: [DONE] 會再串流一個額外的區塊。 usage此區塊上的欄位顯示整個請求的代幣使用統計，且choices欄位永遠為空陣列。 其他區塊也會包含 usage 欄位，但值為空。	No

chatCompletionChoiceLogProbs

記錄選擇的機率資訊。

Name	類型	Description	Required	Default
內容	陣列	一份包含日誌機率資訊的訊息內容標記清單。	Yes
refusal	陣列	一份包含日誌機率資訊的訊息拒絕令牌清單。	No

chatCompletionTokenLogprob

Name	類型	Description	Required	Default
bytes	陣列	一個整數清單，代表 UTF-8 位元組的代幣表示。 當字元由多個標記表示，且必須組合其位元組表示以產生正確的文字表示時，非常有用。 如果該標記沒有位元組表示，則可能 。null	Yes
logprob	number	此標記的對數機率。	Yes
Token	字串	The token.	Yes
top_logprobs	陣列	在此標記位置上最可能出現的標記及其對數機率列表。 在極少數情況下，退回的數量可能少於申請 top_logprobs 的數量。	Yes

chatCompletionResponseMessage

由模型產生的聊天完成訊息。

Name	類型	Description	Required	Default
audio	物件	若請求音訊輸出模態，此物件包含模型音訊回應的資料。	No
└─ data	字串	Base64 編碼音訊位元組，由模型產生，格式依請求指定。	No
└─ expires_at	整數	Unix 的時間戳記（以秒為單位），表示此音訊回應何時無法在伺服器上存取，無法用於多回合對話。	No
└─ id	字串	此音訊回應的唯一識別碼。	No
└─ transcript	字串	模型產生的音訊逐字稿。	No
內容	字串	訊息內容。	Yes
內容	azureChatExtensionsMessageContext	當 Azure OpenAI 聊天擴充功能參與生成對應聊天完成回應時，可獲得的額外上下文資訊表示。 這些上下文資訊只有在使用 Azure OpenAI 請求並設定為匹配擴充功能時才會被填入。	No
function_call	chatCompletionFunctionCall	已棄用並被 tool_calls取代。 模型產生的函式名稱與參數。	No
refusal	字串	模型產生的拒絕訊息。	Yes
角色	chatCompletionResponseMessageRole	回應訊息作者的角色。	Yes
tool_calls	陣列	模型產生的工具呼叫，例如函式呼叫。	No

chatCompletionResponseMessageRole

回應訊息作者的角色。

Property	Value
Description	回應訊息作者的角色。
Type	字串
Values	assistant

chatCompletionToolChoiceOption

控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫一個或多個工具。 required 表示模型必須呼叫一個或多個工具。 指定特定工具 透過 會 {"type": "function", "function": {"name": "my_function"}} 強制模型呼叫該工具。 none 當沒有工具時，預設是。 auto 如果有工具，則是預設。

此組件可為以下之一：

• chatCompletionNamedToolChoice

chatCompletionNamedToolChoice

指定模型應該使用的工具。 用來強制模型呼叫特定函式。

Name	類型	Description	Required	Default
函式	物件		Yes
└─ name	字串	要呼叫的函式名稱。	No
型別	列舉	工具的種類。 目前僅 function 支援。 可能的數值： function	Yes

ParallelToolCalls

是否在工具使用時啟用平行函式呼叫。

此元件未定義屬性。

PredictionContent

靜態預測輸出內容，例如正在重新生成的文字檔內容。

Name	類型	Description	Required	Default
內容	字串或陣列	產生模型回應時應該匹配的內容。 如果產生的代幣能與此內容相符，整個模型回應就能更快回傳。	Yes
型別	列舉	你想提供的預測內容類型。 此類型目前總是 content。 可能的數值： content	Yes

chatCompletionMessageToolCalls

模型產生的工具呼叫，例如函式呼叫。

此元件未定義屬性。

ChatCompletionModalities

你希望模型為此請求產生的輸出類型。 大多數模型都能產生文字，這是預設的：

["text"]

該 gpt-4o-audio-preview 模型也可用於產生音訊。 若要請求此模型同時產生文字與音訊回應，您可以使用：

["text", "audio"]

此元件未定義屬性。

chatCompletionFunctionCall

已棄用並被 tool_calls取代。 模型產生的函式名稱與參數。

Name	類型	Description	Required	Default
arguments	字串	呼叫函式的參數，由模型以 JSON 格式產生。 請注意，模型並不總是產生有效的 JSON，且可能會產生未由函式結構定義的參數。 在呼叫函式前，先驗證程式碼中的參數。	Yes
name	字串	要呼叫的函式名稱。	Yes

completionUsage

完成請求的使用統計數據。

Name	類型	Description	Required	Default
completion_tokens	整數	生成完成項目中的代幣數量。	Yes
completion_tokens_details	物件	完成過程中使用的代幣分解。	No
└─ accepted_prediction_tokens	整數	使用預測輸出時，則是預測中出現在補全中的符號數量。	No
└─ audio_tokens	整數	由模型產生的音訊輸入標記。	No
└─ reasoning_tokens	整數	由模型產生的推理代幣。	No
└─ rejected_prediction_tokens	整數	使用預測輸出時，是指預測中未出現在補全結果中的符號數量。 然而，與推理代幣一樣，這些代幣仍會計入總完成代幣中，以計算計費、輸出及上下文視窗限制。	No
prompt_tokens	整數	提示詞中的代幣數量。	Yes
prompt_tokens_details	物件	提示代幣的詳細資訊。	No
└─ audio_tokens	整數	提示中出現的音訊輸入標記。	No
└─ cached_tokens	整數	快取的提示代幣數量。	No
total_tokens	整數	請求中使用的總標記數（提示 + 完成數）。	Yes

chatCompletionTool

Name	類型	Description	Required	Default
函式	FunctionObject		Yes
型別	列舉	工具的種類。 目前僅 function 支援。 可能的數值： function	Yes

FunctionParameters

函式所接受的參數，描述為 JSON Schema 物件。 請參閱範例指南 ，以及 JSON Schema 參考資料 中關於格式的文件。

省略 parameters 定義了一個參數列表為空的函數。

此元件未定義屬性。

FunctionObject

Name	類型	Description	Required	Default
description	字串	描述函式的功能，模型用來決定何時以及如何呼叫函式。	No
name	字串	要呼叫的函式名稱。 必須是 a-z、A-Z、0-9，或包含底線和破折號，長度最多為 64。	Yes
parameters	FunctionParameters	函式所接受的參數，描述為 JSON Schema 物件。 請參閱範例指南 ，以及 JSON Schema 參考資料 中關於格式的文件。 省略 parameters 定義了一個參數列表為空的函數。	No
strict	boolean	在產生函式呼叫時是否要啟用嚴格的結構遵循。 若設為真，模型將遵循欄位中 parameters 定義的精確結構。 當 strict 為 時 true，僅支援部分 JSON 架構。	No	False

ResponseFormatText

Name	類型	Description	Required	Default
型別	列舉	所定義的回應格式類型： text 可能的數值： text	Yes

ResponseFormatJsonObject

Name	類型	Description	Required	Default
型別	列舉	所定義的回應格式類型： json_object 可能的數值： json_object	Yes

ResponseFormatJsonSchemaSchema

回應格式的結構，描述為 JSON Schema 物件。

此元件未定義屬性。

ResponseFormatJsonSchema

Name	類型	Description	Required	Default
json_schema	物件		Yes
└─ description	字串	描述回應格式的用途，模型用來決定如何以該格式回應。	No
└─ name	字串	回應格式的名稱。 必須是 a-z、A-Z、0-9，或包含底線和破折號，長度最多為 64。	No
└─ schema	ResponseFormatJsonSchemaSchema	回應格式的結構，描述為 JSON Schema 物件。	No
└─ strict	boolean	在產生輸出時是否要啟用嚴格的結構遵循。 若設為 true，模型將始終遵循欄位中定義 schema 的精確模式。 當 strict 為 時 true，僅支援部分 JSON 架構。	No	False
型別	列舉	所定義的回應格式類型： json_schema 可能的數值： json_schema	Yes

chatCompletionChoiceCommon

Name	類型	Description	Required	Default
finish_reason	字串		No
索引	整數		No

createTranslationRequest

Translation request.

Name	類型	Description	Required	Default
檔案	字串	要翻譯的音訊檔案。	Yes
提示	字串	可選文字用來引導模型風格或延續先前的音訊片段。 題目應該是英文。	No
response_format	audioResponseFormat	定義輸出格式。	No
temperature	number	取樣溫度介於0到1之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 若設為 0，模型會利用對數機率自動升溫，直到達到某些臨界點為止。	No	0

audioResponse

當 response_format 是 json 時，翻譯或轉錄回應

Name	類型	Description	Required	Default
收發簡訊	字串	翻譯或轉錄文本。	Yes

audioVerboseResponse

翻譯或轉錄反應response_format verbose_json

Name	類型	Description	Required	Default
duration	number	Duration.	No
語言	字串	Language.	No
segments	陣列		No
工作	字串	音訊任務類型。	No
收發簡訊	字串	翻譯或轉錄文本。	Yes
words	陣列		No

audioResponseFormat

定義輸出格式。

Property	Value
Description	定義輸出格式。
Type	字串
Values	json text srt verbose_json vtt

createTranscriptionRequest

Transcription request.

Name	類型	Description	Required	Default
檔案	字串	要轉錄的音訊檔案物件。	Yes
語言	字串	輸入音訊的語言。 以 ISO-639-1 格式提供輸入語言可提升準確度與延遲。	No
提示	字串	可選文字用來引導模型風格或延續先前的音訊片段。 提示詞應該與音頻語言相符。	No
response_format	audioResponseFormat	定義輸出格式。	No
temperature	number	取樣溫度介於0到1之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 若設為 0，模型會利用對數機率自動升溫，直到達到某些臨界點為止。	No	0
timestamp_granularities[]	陣列	此轉錄時需填寫的時間戳和細節。 response_format 必須設定 verbose_json 為使用時間戳記的細度。 支持以下選項之一或兩者： word，或 segment。 注意：區段時間戳記不會增加延遲，但產生字時間戳會產生額外的延遲。	No	['segment']

audioSegment

轉錄或翻譯片段。

Name	類型	Description	Required	Default
avg_logprob	number	平均對數機率。	No
compression_ratio	number	Compression ratio.	No
end	number	段端偏移。	No
id	整數	Segment identifier.	No
no_speech_prob	number	「無言語」的機率。	No
seek	number	是段子的偏移。	No
start	number	分段起始偏移。	No
temperature	number	Temperature.	No
收發簡訊	字串	Segment text.	No
tokens	陣列	文字的標記。	No

audioWord

轉錄或翻譯詞。

Name	類型	Description	Required	Default
end	number	字尾抵消。	No
start	number	字詞起始錯置。	No
字組	字串	Word	No

createSpeechRequest

Speech request.

Name	類型	Description	Required	Default
輸入	字串	合成音訊的文字。 最大長度為 4,096 字元。	Yes
response_format	列舉	合成音訊的格式。 可能的值：mp3， opus， aacflacwavpcm	No
speed	number	合成音效的速度。 從 中選擇一個值 0.25 到 4.0。 1.0 是預設值。	No	1.0
voice	列舉	用於語音合成的聲音。 可能的值：alloy， echo， fableonyxnovashimmer	Yes

imageQuality

所產生的影像品質。

Property	Value
Description	所產生的影像品質。
Type	字串
Default	auto
Values	auto high medium low hd standard

imagesResponseFormat

產生影像回傳的格式。

Property	Value
Description	產生影像回傳的格式。
Type	字串
Default	url
Values	url b64_json

imagesOutputFormat

產生影像回傳的檔案格式。 僅支援系列機型。

Property	Value
Description	產生影像回傳的檔案格式。 僅支援 GPT-Image-1 系列機型。
Type	字串
Default	png
Values	png jpeg

imageSize

產生的影像大小。

Property	Value
Description	產生的影像大小。
Type	字串
Default	auto
Values	auto 1792x1024 1024x1792 1024x1024 1024x1536 1536x1024

imageStyle

產生的圖片風格。 只支援 DALL-E-3。

Property	Value
Description	產生的圖片風格。 只支援 DALL-E-3。
Type	字串
Default	vivid
Values	vivid natural

imageBackground

允許設定產生影像背景的透明度。 此參數僅支援 gpt-image-1 系列模型。

Property	Value
Description	允許設定產生影像背景的透明度。 此參數僅支援 gpt-image-1 系列模型。
Type	字串
Default	auto
Values	transparent opaque auto

imageGenerationsRequest

Name	類型	Description	Required	Default
背景	imageBackground	允許設定產生影像背景的透明度。 此參數僅支援 gpt-image-1 系列模型。	No	auto
n	整數	要產生的影像數量。 對於 dall-e-3，僅支援 n=1。	No	1
output_compression	整數	產生影像的壓縮等級（0-100%）。 此參數僅支援帶有 jpeg 輸出格式的 gpt-image-1 系列模型。	No	100
output_format	imagesOutputFormat	產生影像回傳的檔案格式。 僅支援 GPT-Image-1 系列機型。	No	png
提示	字串	這是想要圖片的文字描述。 GPT-image-1 系列型號的最大長度為 32000 字元，dall-e-3 則為 4000 字元	Yes
quality	imageQuality	所產生的影像品質。	No	auto
response_format	imagesResponseFormat	產生影像回傳的格式。 只支援 DALL-E-3。	No	url
size	imageSize	產生的影像大小。	No	auto
樣式	imageStyle	產生的圖片風格。 只支援 DALL-E-3。	No	vivid
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

imageEditsRequest

Name	類型	Description	Required	Default
圖片	字串或陣列	圖片需要編輯。 必須是支援的影像檔案或一組影像陣列。 每張圖片應該是 png 或 jpg 檔案，少於 25MB。	Yes
遮罩	字串	另一張圖片的完全透明區域（例如alpha為零）指示圖片應編輯的位置。 若提供多張影像，遮罩會套用在第一張影像上。 必須是有效的 PNG 檔案，大小小於 4MB，且尺寸與圖片相同。	No
n	整數	要產生的影像數量。	No	1
提示	字串	這是想要圖片的文字描述。 最大長度為32000字元。	Yes
quality	imageQuality	所產生的影像品質。	No	auto
response_format	imagesResponseFormat	產生影像回傳的格式。	No	url
size	imageSize	產生的影像大小。	No	auto
使用者	字串	一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。	No

generateImagesResponse

Name	類型	Description	Required	Default
created	整數	Unix 的時間戳記是該操作建立的時刻。	Yes
資料	陣列	操作成功時，該操作的結果資料	Yes
使用方式	imageGenerationsUsage	代表影像生成請求的代幣使用細節。 僅限於 gpt-image-1 系列機型。	No

imageResult

如果成功，請輸入圖片網址或編碼圖片，否則會報錯。

Name	類型	Description	Required	Default
b64_json	字串	base64 編碼影像	No
content_filter_results	dalleContentFilterResults	關於內容過濾結果的資訊。	No
prompt_filter_results	dalleFilterResults	關於內容過濾類別（仇恨、性、暴力、self_harm）、是否已被偵測到，以及嚴重程度等級（very_low、低、中、高，決定有害內容的強度與風險等級），以及是否已被過濾。 關於越獄內容與髒話的資訊，是否被偵測到，以及是否被過濾。 還有關於客戶封鎖名單的資訊（如果已經過濾過的話）以及它的識別碼。	No
revised_prompt	字串	如果提示有任何修改，就是用來產生圖片的提示。	No
url	字串	圖片網址。	No

imageGenerationsUsage

代表影像生成請求的代幣使用細節。 僅限於 gpt-image-1 系列機型。

Name	類型	Description	Required	Default
input_tokens	整數	輸入標記的數量。	No
input_tokens_details	物件	輸入標記的詳細解析。	No
└─ image_tokens	整數	圖片代幣的數量。	No
└─ text_tokens	整數	文字標記的數量。	No
output_tokens	整數	輸出代幣的數量。	No
total_tokens	整數	所使用的代幣總數。	No

線條

內容行物件由相鄰的內容元素序列組成，例如單字和選取標記。

Name	類型	Description	Required	Default
spans	陣列	一個代表偵測到物件及其包圍盒資訊的範圍陣列。	Yes
收發簡訊	字串		Yes

span

一個表示偵測到物件及其包圍盒資訊的 span 物件。

Name	類型	Description	Required	Default
length	整數	以字元為單位的跨度長度，以 Unicode 碼點計算。	Yes
位移	整數	字元偏移在文字中，從跨度開始處。 此偏移定義為跨度第一個字元的位置，從文字開始計算為 Unicode 碼點。	Yes
多邊形	陣列	一組代表包圍偵測物件的多邊形點的物件陣列。	Yes
收發簡訊	字串	代表偵測到物件的跨度的文字內容。	Yes

runCompletionUsage

與這次跑步相關的使用統計數據。 當執行不處於終端狀態（例如 null、 、 in_progress等）時，這個值將是 queued 。

Name	類型	Description	Required	Default
completion_tokens	整數	在整個過程中使用的完成代幣數量。	Yes
prompt_tokens	整數	在整個遊戲過程中使用的提示代幣數量。	Yes
total_tokens	整數	總使用的代幣數（提示+完成）。	Yes

runStepCompletionUsage

與跑步相關的使用統計數據。 當 Run Step 狀態為 null時，這個值會是 in_progress 。

Name	類型	Description	Required	Default
completion_tokens	整數	在執行步驟中使用的完成代幣數量。	Yes
prompt_tokens	整數	在執行步驟中使用的提示代幣數量。	Yes
total_tokens	整數	總使用的代幣數（提示+完成）。	Yes

assistantsApiResponseFormatOption

指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106.

設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。

設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。

重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。

此組件可為以下之一：

• ResponseFormatText
• ResponseFormatJsonObject
• ResponseFormatJsonSchema

assistantsApiResponseFormat

一個描述模型預期輸出的物件。 如果json_object只有functiontools類型能傳給 Run。 模型是否 text 能回傳文字或所需的值。

Name	類型	Description	Required	Default
型別	字串	必須是其中 text 之一或 json_object。	No	收發簡訊

類型 Enum： AssistantsApiResponseFormat

Value	Description
收發簡訊
json_object

assistantObject

代表一個 assistant 可以呼叫模型並使用工具的。

Name	類型	Description	Required	Default
created_at	整數	Unix 的時間戳（以秒計）顯示助理被建立的時間。	Yes
description	字串	助理的描述。 最大長度為512字元。	Yes
id	字串	識別碼，可以在 API 端點中被參考。	Yes
instructions	字串	助理使用的系統指令。 最大長度為 256,000 字元。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
型號	字串	要用的型號識別碼。	Yes
name	字串	助理的名字。 最大長度為 256 字元。	Yes
物件	字串	物件類型，永遠 assistant為 。	Yes
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	這個助理附著的向量商店 ID。 助理最多只能附加一個向量儲存。	No
tools	陣列	助理上啟用的工具清單。 每位助理最多可攜帶128種工具。 工具可以是類型 code_interpreter、、 file_search或 function。	Yes	[]
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1

物件列舉：AssistantObjectType

Value	Description
助理	物件類型，永遠是助理

createAssistantRequest

Name	類型	Description	Required	Default
description	字串	助理的描述。 最大長度為512字元。	No
instructions	字串	助理使用的系統指令。 最大長度為 256,000 字元。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串		Yes
name	字串	助理的名字。 最大長度為 256 字元。	No
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	這個助理附著的向量儲存庫。 助理最多只能附加一個向量儲存。	No
└─ vector_stores	陣列	一個用 file_ids 建立向量儲存並附加到這個助理的輔助工具。 助理最多只能附加一個向量儲存。	No
tools	陣列	助理上啟用的工具清單。 每位助理最多可攜帶128種工具。 工具可以是類型 code_interpreter、、 retrieval或 function。	No	[]
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1

modifyAssistantRequest

Name	類型	Description	Required	Default
description	字串	助理的描述。 最大長度為512字元。	No
instructions	字串	助理使用的系統指令。 最大長度為 32768 字元。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串		No
name	字串	助理的名字。 最大長度為 256 字元。	No
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	覆蓋工具 code_interpreter 所提供的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	會覆蓋綁定在這個助理上的向量儲存。 助理最多只能附加一個向量儲存。	No
tools	陣列	助理上啟用的工具清單。 每位助理最多可攜帶128種工具。 工具可以是類型 code_interpreter、、 retrieval或 function。	No	[]
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1

deleteAssistantResponse

Name	類型	Description	Required	Default
deleted	boolean		Yes
id	字串		Yes
物件	字串		Yes

物件列舉：DeleteAssistantResponseState

Value	Description
assistant.deleted

listAssistantsResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

assistantToolsCode

Name	類型	Description	Required	Default
型別	字串	所定義的工具類型： code_interpreter	Yes

類型 Enum： assistantToolsCodeType

Value	Description
code_interpreter

assistantToolsFileSearch

Name	類型	Description	Required	Default
file_search	物件	檔案搜尋工具的覆寫。	No
└─ max_num_results	整數	檔案搜尋工具應輸出的最大結果數量。 預設是 GPT-4* 車型 20 波，GPT-3.5 渦輪波 5 波。 這個數字應該介於1到50之間。 請注意，檔案搜尋工具輸出的結果可能少 max_num_results 於結果。	No
型別	字串	所定義的工具類型： file_search	Yes

類型列舉：assistantToolsFileSearchType

Value	Description
file_search

assistantToolsFileSearchTypeOnly

Name	類型	Description	Required	Default
型別	字串	所定義的工具類型： file_search	Yes

類型列舉：assistantToolsFileSearchType

Value	Description
file_search

assistantToolsFunction

Name	類型	Description	Required	Default
函式	物件	函數定義。	Yes
└─ description	字串	描述函式的功能，模型用來決定何時以及如何呼叫函式。	No
└─ name	字串	要呼叫的函式名稱。 必須是 a-z、A-Z、0-9，或包含底線和破折號，長度最多為 64。	No
└─ parameters	chatCompletionFunctionParameters	函式所接受的參數，描述為 JSON Schema 物件。 範例請參考 指南/ ，以及 JSON Schema 參考資料 中關於格式的文件。	No
型別	字串	所定義的工具類型： function	Yes

類型 Enum：assistantToolsFunction

Value	Description
函式

truncationObject

控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。

Name	類型	Description	Required	Default
last_messages	整數	在構建執行情境時，執行緒中最近收到的訊息數量。	No
型別	字串	執行緒的截斷策略。 預設為 auto。 若設為 last_messages，執行緒將被截斷為執行緒中最近 n 則的訊息。 當 設為 auto時，執行緒中間的訊息會被刪除以符合模型的上下文長度。 max_prompt_tokens	Yes

類型 Enum：截斷類型

Value	Description
auto
last_messages

assistantsApiToolChoiceOption

控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。

此組件可為以下之一：

• assistantsNamedToolChoice

assistantsNamedToolChoice

指定模型應該使用的工具。 用來強制模型呼叫特定工具。

Name	類型	Description	Required	Default
函式	物件		No
└─ name	字串	要呼叫的函式名稱。	No
型別	字串	工具的種類。 若型別為 function，函式名稱必須被設定	Yes

類型列舉：AssistantsNamedToolChoiceType

Value	Description
函式
code_interpreter
file_search

runObject

代表執行緒上的執行執行。

Name	類型	Description	Required	Default
assistant_id	字串	執行本次行動的助理身份證件。	Yes
cancelled_at	整數	Unix 的時間戳記（以秒計）表示執行被取消的時間。	Yes
completed_at	整數	Unix 的時間戳記（以秒計）表示執行完成的時間。	Yes
created_at	整數	Unix 的時間戳記（以秒計）代表執行序列建立的時間。	Yes
expires_at	整數	Unix 的時間戳記（以秒計）表示執行結束的時間。	Yes
failed_at	整數	Unix 的時間戳記（以秒計）表示執行失敗的時間。	Yes
id	字串	識別碼，可以在 API 端點中被參考。	Yes
incomplete_details	物件	關於為什麼這段作品不完整的原因。 如果這次跑步沒有不完整，那就會是 null 。	Yes
└─ reason	字串	這段時間未完成的原因。 這會顯示在整個過程中達到的具體代幣上限。	No
instructions	字串	助理用來執行這次任務的指示。	Yes
last_error	物件	這是這次跑動的最後一個錯誤。 如果沒有錯誤，那就會是 null 。	Yes
└─ code	字串	其中一或 server_errorrate_limit_exceeded。	No
└─ message	字串	一個人類易讀的錯誤描述。	No
max_completion_tokens	整數	指定在整個運行過程中已使用的完成代幣數量。	Yes
max_prompt_tokens	整數	指定在整個運行過程中已使用的提示代幣數量。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
型號	字串	助理這次用的模型。	Yes
物件	字串	物件類型，永遠 thread.run為 。	Yes
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
required_action	物件	關於繼續連載所需的行動細節。 如果不需要採取行動，那就不會。null	Yes
└─ submit_tool_outputs	物件	關於本次運行所需的工具輸出細節。	No
└─ tool_calls	陣列	相關工具呼叫清單。	No
└─ type	列舉	目前，這永遠 submit_tool_outputs是。 可能的數值： submit_tool_outputs	No
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	Yes
started_at	整數	Unix 的時間戳記（以秒計）表示執行開始的時間。	Yes
狀態	字串	該跑動的狀態可以是 queued、 in_progress、 requires_actioncancellingcancelledfailedcompletedexpired或 。	Yes
temperature	number	這次使用的取樣溫度。 如果沒設定，預設是 1。	No
thread_id	字串	這次執行中執行的執行緒的 ID。	Yes
tool_choice	assistantsApiToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。	Yes
tools	陣列	助理這次跑動使用的工具清單。	Yes	[]
top_p	number	本次運行所使用的核取樣值。 如果沒設定，預設是 1。	No
truncation_strategy	truncationObject	控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。	Yes
使用方式	runCompletionUsage	與這次跑步相關的使用統計數據。 當執行不處於終端狀態（例如 null、 、 in_progress等）時，這個值將是 queued 。	Yes

物件列舉：runObjectType

Value	Description
thread.run	run 物件型別，永遠是 thread.run

status Enum： RunObjectStatus

Value	Description
queued	排隊狀態
in_progress	in_progress州
requires_action	required_action州
cancelling	取消狀態
cancelled	被取消的國家
failed	失敗國家
completed	完成的國家
expired	過期狀態

createRunRequest

Name	類型	Description	Required	Default
additional_instructions	字串	在執行指令的最後附加額外指令。 這對於每次執行修改行為且不會覆蓋其他指令非常有用。	No
additional_messages	陣列	在建立執行前，先向執行緒新增訊息。	No
assistant_id	字串	執行此執行的助理 ID。	Yes
instructions	字串	覆蓋助理的預設系統訊息。 這對於每次執行時調整行為非常有用。	No
max_completion_tokens	整數	在整個遊戲過程中可使用的完成代幣數量。 該跑法會盡力只使用指定數量的完成標記，且在多回合中完成。 若執行超過完成標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
max_prompt_tokens	整數	在整個過程中可使用的提示代幣數量。 這次遊戲會盡力只使用指定數量的提示代幣，且在多回合中進行。 若執行次數超過指定提示標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串	執行此執行的模型 ID。 若此處提供值，該值將覆蓋與助理相關的模型。 若不符合，則會使用與助理相關的模型。	No
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
tool_choice	assistantsApiToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。	No
tools	陣列	覆寫助理這次跑動時可用的工具。 這對於每次執行時調整行為非常有用。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1
truncation_strategy	truncationObject	控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。	No

listRunsResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

modifyRunRequest

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No

submitToolOutputsRunRequest

Name	類型	Description	Required	Default
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
tool_outputs	陣列	一份提交輸出的工具清單。	Yes

runToolCallObject

工具呼叫物件

Name	類型	Description	Required	Default
函式	物件	函數定義。	Yes
└─ arguments	字串	模型期望你傳遞給函數的參數。	No
└─ name	字串	功能名稱。	No
id	字串	工具呼叫的ID。 這個 ID 必須在你提交工具輸出時參考，並使用提交工具輸出來執行端點。	Yes
型別	字串	輸出所需的工具呼叫類型。 目前，這永遠 function是。	Yes

類型列舉：RunToolCallObjectType

Value	Description
函式

createThreadAndRunRequest

Name	類型	Description	Required	Default
assistant_id	字串	執行此執行的助理 ID。	Yes
instructions	字串	覆蓋助理的預設系統訊息。 這對於每次執行時調整行為非常有用。	No
max_completion_tokens	整數	在整個遊戲過程中可使用的完成代幣數量。 該跑法會盡力只使用指定數量的完成標記，且在多回合中完成。 若執行超過完成標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
max_prompt_tokens	整數	在整個過程中可使用的提示代幣數量。 這次遊戲會盡力只使用指定數量的提示代幣，且在多回合中進行。 若執行次數超過指定提示標記數，執行將以狀態 incomplete結束。 更多資訊請參見 incomplete_details 。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
型號	字串	執行此執行的模型 ID。 若此處提供值，該值將覆蓋與助理相關的模型。 若不符合，則會使用與助理相關的模型。	No
parallel_tool_calls	ParallelToolCalls	是否在工具使用時啟用平行函式呼叫。	No	True
response_format	assistantsApiResponseFormatOption	指定模型必須輸出的格式。 相容於 GPT-4o、GPT-4 Turbo 及自 gpt-3.5-turbo-1106. 設定為 { "type": "json_schema", "json_schema": {...} } 啟用結構化輸出，確保模型與你提供的 JSON 架構相符。 更多資訊請參閱 Structured Outputs 指南。 設定啟用 { "type": "json_object" } JSON 模式，確保模型產生的訊息是有效的 JSON。 重要提示： 使用 JSON 模式時， 你也必須 指示模型透過系統或使用者訊息自行產生 JSON。 若無此，模型可能會產生無盡的空白流，直到產生達到代幣上限，導致請求長時間且看似「卡住」。 另外請注意，若 finish_reason="length"，訊息內容可能會部分中斷，表示產生 max_tokens 次數或對話超過最大上下文長度。	No
串流	boolean	若 true，則回傳執行期間發生的事件串流，作為伺服器發送事件，當執行進入終端狀態並發送 data: [DONE] 訊息時終止。	No
stream_options	chatCompletionStreamOptions	串流回應選項。 只有在你設定 stream: true時才會設定這個。	No	None
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。	No	1
執行緒	createThreadRequest		No
tool_choice	assistantsApiToolChoiceOption	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定特定工具，例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} ，強制模型呼叫該工具。	No
tool_resources	物件	一組由助理工具使用的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	這個助理附著的向量商店 ID。 助理最多只能附加一個向量儲存。	No
tools	陣列	覆寫助理這次跑動時可用的工具。 這對於每次執行時調整行為非常有用。	No
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議調整這個或溫度，但不要兩者兼用。	No	1
truncation_strategy	truncationObject	控制執行緒在執行前如何被截斷。 用這個來控制執行的初始上下文視窗。	No

threadObject

代表包含訊息的執行緒。

Name	類型	Description	Required	Default
created_at	整數	Unix 的時間戳（以秒計）顯示該執行緒被建立的時間。	Yes
id	字串	識別碼，可以在 API 端點中被參考。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
物件	字串	物件類型，永遠 thread為 。	Yes
tool_resources	物件	這是一組在本串中提供給助理工具的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	Yes
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	向量商店附在本串。 執行緒最多可連接一個向量儲存庫。	No

物件列舉：ThreadObjectType

Value	Description
執行緒	執行緒物件的類型，總是 thread

createThreadRequest

Name	類型	Description	Required	Default
messages	陣列	一串訊息作為開啟討論串的清單。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
tool_resources	物件	這是一組在本串中提供給助理工具的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	向量商店附在本串。 執行緒最多可連接一個向量儲存庫。	No
└─ vector_stores	陣列	一個幫忙用 file_ids 建立向量儲存庫並附在這個討論串裡。 執行緒最多可連接一個向量儲存庫。	No

modifyThreadRequest

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
tool_resources	物件	這是一組在本串中提供給助理工具的資源。 這些資源會依照工具類型而定。 例如，工具 code_interpreter 需要檔案 ID 清單，而工具則 file_search 需要向量儲存 ID 清單。	No
└─ code_interpreter	物件		No
└─ file_ids	陣列	提供給 code_interpreter 工具的檔案 ID 清單。 該工具最多可關聯 20 個檔案。	No	[]
└─ file_search	物件		No
└─ vector_store_ids	陣列	向量商店附在本串。 執行緒最多可連接一個向量儲存庫。	No

deleteThreadResponse

Name	類型	Description	Required	Default
deleted	boolean		Yes
id	字串		Yes
物件	字串		Yes

物件枚舉：DeleteThreadResponseObjectState

Value	Description
thread.deleted	刪除執行緒回應物件狀態，為 thread.deleted

listThreadsResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

messageObject

代表線程中的訊息。

Name	類型	Description	Required	Default
assistant_id	字串	如適用，請提供撰寫此訊息的助理的ID。	Yes
attachments	陣列	附帶在訊息上的檔案清單，以及它們被加入的工具。	Yes
completed_at	整數	Unix 的時間戳記（以秒計）表示訊息完成的時間。	Yes
內容	陣列	訊息內容以文字和/或圖片排列。	Yes
created_at	整數	Unix 的時間戳記（以秒計）表示訊息產生的時間。	Yes
id	字串	識別碼，可以在 API 端點中被參考。	Yes
incomplete_at	整數	Unix 的時間戳記（以秒計）表示訊息被標記為不完整。	Yes
incomplete_details	物件	對於不完整的訊息，請詳細說明訊息不完整的原因。	Yes
└─ reason	字串	訊息不完整的原因。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
物件	字串	物件類型，永遠 thread.message為 。	Yes
角色	字串	那個產生訊息的存在。 其中一或 userassistant。	Yes
run_id	字串	如適用，請標示與此訊息撰寫相關的執行編號。	Yes
狀態	字串	訊息的狀態可以是 in_progress、 、 incomplete或 completed。	Yes
thread_id	字串	該訊息所屬的主題串。	Yes

物件列舉：MessageObjectType

Value	Description
thread.message	訊息物件型態為 thread.message

status Enum： MessageObjectStatus

Value	Description
in_progress
incomplete
completed

role 列舉：MessageObjectRole

Value	Description
使用者
助理

messageDeltaObject

代表訊息 delta，即串流過程中訊息中任何欄位的變更。

Name	類型	Description	Required	Default
delta	物件	包含訊息中變更欄位的 delta。	Yes
└─ content	陣列	訊息內容以文字和/或圖片排列。	No
└─ role	字串	那個產生訊息的存在。 其中一或 userassistant。	No
id	字串	訊息的識別碼，可以在 API 端點中引用。	Yes
物件	字串	物件類型，永遠 thread.message.delta為 。	Yes

物件列舉：MessageDeltaObjectType

Value	Description
thread.message.delta

createMessageRequest

Name	類型	Description	Required	Default
attachments	陣列	附有與訊息相關的檔案清單，以及應該加入的工具。	No
內容	字串	訊息的內容。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
角色	字串	創造訊息的實體的角色。 允許的數值包括： - user表示訊息是由實際使用者發送，且大多數情況下應用來表示使用者產生的訊息。 - assistant表示訊息是由助理產生的。 利用這個值將助理的訊息插入對話中。	Yes

role 列舉：CreateMessageRequestRole

Value	Description
使用者
助理

modifyMessageRequest

Name	類型	Description	Required	Default
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No

deleteMessageResponse

Name	類型	Description	Required	Default
deleted	boolean		Yes
id	字串		Yes
物件	字串		Yes

物件枚舉：DeleteMessageResponseObject

Value	Description
thread.message.deleted	刪除訊息回應物件狀態

listMessagesResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

messageContentImageFileObject

在訊息內容中引用影像檔案。

Name	類型	Description	Required	Default
image_file	物件		Yes
└─ file_id	字串	訊息內容中圖片的檔案 ID。	No
型別	字串	永遠如此 image_file。	Yes

類型列舉：MessageContentImageFileObjectType

Value	Description
image_file	訊息內容影像檔案類型

messageContentTextObject

訊息中包含的文字內容。

Name	類型	Description	Required	Default
收發簡訊	物件		Yes
└─ annotations	陣列		No
└─ value	字串	構成文本的資料。	No
型別	字串	永遠如此 text。	Yes

類型列舉：messageContentTextObjectType

Value	Description
收發簡訊	訊息內容文字物件類型

messageContentTextAnnotationsFileCitationObject

訊息中引用特定檔案中與助理或訊息相關的特定引用。 當助理使用「檢索」工具搜尋檔案時產生。

Name	類型	Description	Required	Default
end_index	整數		Yes
file_citation	物件		Yes
└─ file_id	字串	引用來源的檔案編號。	No
start_index	整數		Yes
收發簡訊	字串	訊息內容中需要替換的文字。	Yes
型別	字串	永遠如此 file_citation。	Yes

類型 Enum： FileCitationObjectType

Value	Description
file_citation	檔案引用物件類型

messageContentTextAnnotationsFilePathObject

一個助理使用 code_interpreter 工具產生檔案時產生的檔案網址。

Name	類型	Description	Required	Default
end_index	整數		Yes
file_path	物件		Yes
└─ file_id	字串	產生的檔案 ID。	No
start_index	整數		Yes
收發簡訊	字串	訊息內容中需要替換的文字。	Yes
型別	字串	永遠如此 file_path。	Yes

類型列舉：FilePathObjectType

Value	Description
file_path	檔案路徑物件類型

messageDeltaContentImageFileObject

在訊息內容中引用影像檔案。

Name	類型	Description	Required	Default
image_file	物件		No
└─ file_id	字串	訊息內容中圖片的檔案 ID。	No
索引	整數	訊息中內容索引部分。	Yes
型別	字串	永遠如此 image_file。	Yes

類型列舉：MessageDeltaContentImageFileObjectType

Value	Description
image_file

messageDeltaContentTextObject

訊息中包含的文字內容。

Name	類型	Description	Required	Default
索引	整數	訊息中內容索引部分。	Yes
收發簡訊	物件		No
└─ annotations	陣列		No
└─ value	字串	構成文本的資料。	No
型別	字串	永遠如此 text。	Yes

類型列舉：MessageDeltaContentTextObjectType

Value	Description
收發簡訊

messageDeltaContentTextAnnotationsFileCitationObject

訊息中引用特定檔案中與助理或訊息相關的特定引用。 當助理使用「file_search」工具搜尋檔案時產生。

Name	類型	Description	Required	Default
end_index	整數		No
file_citation	物件		No
└─ file_id	字串	引用來源的檔案編號。	No
└─ quote	字串	檔案裡的具體引述。	No
索引	整數	文字內容部分註解的索引。	Yes
start_index	整數		No
收發簡訊	字串	訊息內容中需要替換的文字。	No
型別	字串	永遠如此 file_citation。	Yes

類型列舉：MessageDeltaContentTextAnnotationsFileCitationObjectType

Value	Description
file_citation

messageDeltaContentTextAnnotationsFilePathObject

一個助理使用 code_interpreter 工具產生檔案時產生的檔案網址。

Name	類型	Description	Required	Default
end_index	整數		No
file_path	物件		No
└─ file_id	字串	產生的檔案 ID。	No
索引	整數	文字內容部分註解的索引。	Yes
start_index	整數		No
收發簡訊	字串	訊息內容中需要替換的文字。	No
型別	字串	永遠如此 file_path。	Yes

類型列舉：MessageDeltaContentTextAnnotationsFilePathObjectType

Value	Description
file_path

runStepObject

代表執行跑的步驟。

Name	類型	Description	Required	Default
assistant_id	字串	與跑步相關的助理ID。	Yes
cancelled_at	整數	Unix 的時間戳記（以秒計）表示執行步被取消的時間。	Yes
completed_at	整數	Unix 的時間戳記（以秒計）表示執行步驟完成的時間。	Yes
created_at	整數	Unix 的時間戳記（以秒計）表示執行步驟建立的時間。	Yes
expired_at	整數	Unix 的時間戳（以秒計）表示執行步驟過期的時間。 若父執行已過期，則該步驟被視為過期。	Yes
failed_at	整數	Unix 的時間戳（以秒計）顯示執行步驟失敗的時間點。	Yes
id	字串	執行步驟的識別碼，可在 API 端點中引用。	Yes
last_error	物件	這是與此執行步驟相關的最後一個錯誤。 如果沒有錯誤，那就會是 null 。	Yes
└─ code	字串	其中一或 server_errorrate_limit_exceeded。	No
└─ message	字串	一個人類易讀的錯誤描述。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
物件	字串	物件類型，永遠 assistant.run.step為 。	Yes
run_id	字串	這個跑步所屬的跑道ID。	Yes
狀態	字串	運行狀態可以是 in_progress、 cancelled、 failed、 completed或 expired。	Yes
step_details	runStepDetailsMessageCreationObject 或 runStepDetailsToolCallsObject	跑步步的細節。	Yes
thread_id	字串	是被執行的討論串的 ID。	Yes
型別	字串	跑步的類型，可以是 message_creation 或 tool_calls。	Yes

物件列舉：RunStepObjectType

Value	Description
assistant.run.step	物件類型，且總是 assistant.run.step

類型列舉：RunStepObjectType

Value	Description
message_creation	message_creation跑步
tool_calls	tool_calls跑步

status Enum： RunStepObjectStatus

Value	Description
in_progress	in_progress運行狀態
cancelled	取消演出狀態
failed	取消演出狀態
completed	取消演出狀態
expired	取消演出狀態

runStepDeltaObject

代表一個執行步驟的 delta，即串流過程中執行步驟中任何變更欄位。

Name	類型	Description	Required	Default
delta	物件	delta 包含在執行步中改變的欄位。	Yes
└─ step_details	runStepDeltaStepDetailsMessageCreationObject 或 runStepDeltaStepDetailsToolCallsObject	跑步步的細節。	No
id	字串	執行步驟的識別碼，可在 API 端點中引用。	Yes
物件	字串	物件類型，永遠 thread.run.step.delta為 。	Yes

物件列舉：RunStepDeltaObjectType

Value	Description
thread.run.step.delta

listRunStepsResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

runStepDetailsMessageCreationObject

透過執行步建立訊息的細節。

Name	類型	Description	Required	Default
message_creation	物件		Yes
└─ message_id	字串	這個執行步驟所產生的訊息的 ID。	No
型別	字串	永遠如此 message_creation。	Yes

類型列舉：RunStepDetailsMessageCreationObjectType

Value	Description
message_creation

runStepDeltaStepDetailsMessageCreationObject

透過執行步建立訊息的細節。

Name	類型	Description	Required	Default
message_creation	物件		No
└─ message_id	字串	這個執行步驟所產生的訊息的 ID。	No
型別	字串	永遠如此 message_creation。	Yes

類型列舉：RunStepDeltaStepDetailsMessageCreationObjectType

Value	Description
message_creation

runStepDetailsToolCallsObject

工具召集的細節。

Name	類型	Description	Required	Default
tool_calls	陣列	執行步涉及一系列工具呼叫。 這些工具可以與三種工具之一相關聯： code_interpreter、或 retrievalfunction。	Yes
型別	字串	永遠如此 tool_calls。	Yes

類型列舉：RunStepDetailsToolCallsObjectType

Value	Description
tool_calls

runStepDeltaStepDetailsToolCallsObject

工具召集的細節。

Name	類型	Description	Required	Default
tool_calls	陣列	執行步涉及一系列工具呼叫。 這些工具可以與三種工具之一相關聯： code_interpreter、或 file_searchfunction。	No
型別	字串	永遠如此 tool_calls。	Yes

類型列舉：RunStepDeltaStepDetailsToolCallsObjectType

Value	Description
tool_calls

runStepDetailsToolCallsCodeObject

程式碼解譯器工具呼叫執行步驟的細節。

Name	類型	Description	Required	Default
code_interpreter	物件	程式碼直譯器工具呼叫定義。	Yes
└─ input	字串	程式碼解譯器工具呼叫的輸入。	No
└─ outputs	陣列	程式碼解譯器工具呼叫的輸出。 程式碼直譯器可以輸出一個或多個項目，包括文字（logs）或圖片（image）。 這些物件各由不同的物件類型表示。	No
id	字串	工具呼叫的ID。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 code_interpreter 。	Yes

類型列舉：RunStepDetailsToolCallsCodeObjectType

Value	Description
code_interpreter

runStepDeltaStepDetailsToolCallsCodeObject

程式碼解譯器工具呼叫執行步驟的細節。

Name	類型	Description	Required	Default
code_interpreter	物件	程式碼直譯器工具呼叫定義。	No
└─ input	字串	程式碼解譯器工具呼叫的輸入。	No
└─ outputs	陣列	程式碼解譯器工具呼叫的輸出。 程式碼直譯器可以輸出一個或多個項目，包括文字（logs）或圖片（image）。 這些物件各由不同的物件類型表示。	No
id	字串	工具呼叫的ID。	No
索引	整數	工具呼叫在工具呼叫陣列中的索引。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 code_interpreter 。	Yes

類型列舉：RunStepDeltaStepDetailsToolCallsCodeObjectType

Value	Description
code_interpreter

runStepDetailsToolCallsCodeOutputLogsObject

程式碼解譯器工具的文字輸出，作為執行步驟的一部分。

Name	類型	Description	Required	Default
記錄	字串	程式碼直譯器工具呼叫的文字輸出。	Yes
型別	字串	永遠如此 logs。	Yes

類型列舉：RunStepDetailsToolCallsCodeLogsObjectType

Value	Description
記錄

runStepDeltaStepDetailsToolCallsCodeOutputLogsObject

程式碼解譯器工具的文字輸出，作為執行步驟的一部分。

Name	類型	Description	Required	Default
索引	整數	輸出陣列中輸出的索引。	Yes
記錄	字串	程式碼直譯器工具呼叫的文字輸出。	No
型別	字串	永遠如此 logs。	Yes

類型列舉：RunStepDeltaStepDetailsToolCallsCodeOutputLogsObjectType

Value	Description
記錄

runStepDetailsToolCallsCodeOutputImageObject

Name	類型	Description	Required	Default
圖片	物件		Yes
└─ file_id	字串	圖片的檔案ID。	No
型別	字串	永遠如此 image。	Yes

類型列舉：RunStepDetailsToolCallsCodeOutputImageObjectType

Value	Description
圖片

runStepDeltaStepDetailsToolCallsCodeOutputImageObject

Name	類型	Description	Required	Default
圖片	物件		No
└─ file_id	字串	圖片的檔案ID。	No
索引	整數	輸出陣列中輸出的索引。	Yes
型別	字串	永遠如此 image。	Yes

類型列舉：RunStepDeltaStepDetailsToolCallsCodeOutputImageObject

Value	Description
圖片

runStepDetailsToolCallsFileSearchObject

Name	類型	Description	Required	Default
file_search	物件	目前，這永遠都是空物。	Yes
└─ results	陣列	檔案搜尋結果。	No
id	字串	工具呼叫物件的 ID。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 file_search 。	Yes

類型列舉：RunStepDetailsToolCallsFileSearchObjectType

Value	Description
file_search

runStepDetailsToolCallsFileSearchResultObject

檔案搜尋的結果實例。

Name	類型	Description	Required	Default
內容	陣列	結果的內容。 只有在透過包含查詢參數請求時，內容才會被納入。	No
file_id	字串	結果所在的檔案 ID 就是在那個檔案裡。	Yes
file_name	字串	結果所在的檔案名稱。	Yes
分數	number	比賽結果的比分。 所有值必須是浮點數，介於 0 到 1 之間。	Yes

runStepDeltaStepDetailsToolCallsFileSearchObject

Name	類型	Description	Required	Default
file_search	物件	目前，這永遠都是空物。	Yes
id	字串	工具呼叫物件的 ID。	No
索引	整數	工具呼叫在工具呼叫陣列中的索引。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 retrieval 。	Yes

類型列舉：RunStepDeltaStepDetailsToolCallsFileSearchObjectType

Value	Description
file_search

runStepDetailsToolCallsFunctionObject

Name	類型	Description	Required	Default
函式	物件	被呼叫的函數定義。	Yes
└─ arguments	字串	參數傳遞給函式。	No
└─ name	字串	功能名稱。	No
└─ output	字串	函數的輸出。 如果產出尚未提交，這將是 null 必要的。	No
id	字串	工具呼叫物件的 ID。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 function 。	Yes

類型列舉：RunStepDetailsToolCallsFunctionObjectType

Value	Description
函式

runStepDeltaStepDetailsToolCallsFunctionObject

Name	類型	Description	Required	Default
函式	物件	被呼叫的函數定義。	No
└─ arguments	字串	參數傳遞給函式。	No
└─ name	字串	功能名稱。	No
└─ output	字串	函數的輸出。 如果產出尚未提交，這將是 null 必要的。	No
id	字串	工具呼叫物件的 ID。	No
索引	整數	工具呼叫在工具呼叫陣列中的索引。	Yes
型別	字串	工具呼叫的類型。 這類工具呼叫永遠都是如此 function 。	Yes

類型列舉：RunStepDetailsToolCallsFunctionObjectType

Value	Description
函式

vectorStoreExpirationAfter

向量商店的過期政策。

Name	類型	Description	Required	Default
錨點	字串	錨定時間戳記，之後則適用到期政策。 支撐錨點： last_active_at。	Yes
days	整數	向量儲存在錨點時間後的天數。	Yes

anchor 列舉：VectorStoreExpirationAfterAnchor

Value	Description
last_active_at	即是過期政策生效的錨點時間戳。

vectorStoreObject

向量儲存是工具可使用的 file_search 處理過檔案集合。

Name	類型	Description	Required	Default
created_at	整數	Unix 的時間戳記（以秒計）表示向量儲存器建立的時間。	Yes
expires_after	vectorStoreExpirationAfter	向量商店的過期政策。	No
expires_at	整數	Unix 的時間戳（以秒計）表示向量儲存庫的到期時間。	No
file_counts	物件		Yes
└─ cancelled	整數	被取消的檔案數量。	No
└─ completed	整數	已成功處理的檔案數量。	No
└─ failed	整數	無法處理的檔案數量。	No
└─ in_progress	整數	目前正在處理的檔案數量。	No
└─ total	整數	檔案總數。	No
id	字串	識別碼，可以在 API 端點中被參考。	Yes
last_active_at	整數	Unix 的時間戳（以秒計）表示向量儲存庫最後啟用的時間。	Yes
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	Yes
name	字串	向量商店的名稱。	Yes
物件	列舉	物件類型，永遠 vector_store為 。 可能的數值： vector_store	Yes
狀態	字串	向量儲存狀態，可以是 expired、 in_progress、 或 completed。 狀態 表示 completed 向量儲存庫已準備好使用。	Yes
usage_bytes	整數	向量儲存中檔案所使用的總位元組數。	Yes

status Enum： VectorStoreObjectStatus

Value	Description
expired
in_progress
completed

createVectorStoreRequest

Name	類型	Description	Required	Default
chunking_strategy	autoChunkingStrategyRequestParam 或 staticChunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。 僅當 file_ids 非空時才適用。	No
expires_after	vectorStoreExpirationAfter	向量商店的過期政策。	No
file_ids	陣列	一份向量儲存應該使用的檔案 ID 清單。 這類工具很 file_search 有用，可以存取檔案。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
name	字串	向量商店的名稱。	No

updateVectorStoreRequest

Name	類型	Description	Required	Default
expires_after	vectorStoreExpirationAfter	向量商店的過期政策。	No
中繼資料	物件	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊非常有用。 鍵長最多可為 64 個字元，數值最多可達 512 個字元。	No
name	字串	向量商店的名稱。	No

listVectorStoresResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

deleteVectorStoreResponse

Name	類型	Description	Required	Default
deleted	boolean		Yes
id	字串		Yes
物件	字串		Yes

物件列舉：DeleteVectorStoreResponseObject

Value	Description
vector_store.deleted	刪除向量儲存回應物件狀態

vectorStoreFileObject

一份附在向量儲存的檔案清單。

Name	類型	Description	Required	Default
chunking_strategy	autoChunkingStrategyRequestParam 或 staticChunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。 僅當 file_ids 非空時才適用。	No
created_at	整數	Unix 的時間戳（以秒計）表示向量儲存檔案建立的時間。	Yes
id	字串	識別碼，可以在 API 端點中被參考。	Yes
last_error	物件	最後一個錯誤與這個向量儲存檔案有關。 如果沒有錯誤，那就會是 null 。	Yes
└─ code	字串	或 。server_errorinvalid_fileunsupported_file	No
└─ message	字串	一個人類易讀的錯誤描述。	No
物件	字串	物件類型，永遠 vector_store.file為 。	Yes
狀態	字串	向量儲存檔案的狀態可以是 in_progress、 、 completedcancelled、 或 failed。 狀態 completed 表示向量儲存檔案已準備好使用。	Yes
usage_bytes	整數	以位元組為單位的向量儲存總使用量。 請注意，這可能與原始檔案大小不同。	Yes
vector_store_id	字串	檔案所附著的向量儲存的 ID。	Yes

物件列舉：VectorStoreFileObjectType

Value	Description
vector_store.file

status Enum： VectorStoreFileObjectStatus

Value	Description
in_progress
completed
cancelled
failed

otherChunkingStrategyResponseParam

當分塊策略未知時，會回傳此值。 通常是因為檔案在 API 概念引入前 chunking_strategy 就已經被索引。

Name	類型	Description	Required	Default
型別	字串	永遠如此 other。	Yes

類型列舉：OtherChunkingStrategyResponseParamType

Value	Description
other

staticChunkingStrategyResponseParam

Name	類型	Description	Required	Default
靜態	staticChunkingStrategy		Yes
型別	字串	永遠如此 static。	Yes

列舉型別：StaticChunkingStrategyResponseParamType

Value	Description
靜態

staticChunkingStrategy

Name	類型	Description	Required	Default
chunk_overlap_tokens	整數	區塊之間重疊的代幣數量。 預設值為 400。 請注意，重疊數不得超過一半。max_chunk_size_tokens	Yes
max_chunk_size_tokens	整數	每個區塊中代幣數量的上限。 預設值為 800。 最小值為 100 ，最大值為 4096。	Yes

autoChunkingStrategyRequestParam

預設策略。 此策略目前使用 a max_chunk_size_tokens 的 和 800chunk_overlap_tokens 的 400。

Name	類型	Description	Required	Default
型別	列舉	永遠如此 auto。 可能的數值： auto	Yes

staticChunkingStrategyRequestParam

Name	類型	Description	Required	Default
靜態	staticChunkingStrategy		Yes
型別	列舉	永遠如此 static。 可能的數值： static	Yes

chunkingStrategyRequestParam

用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。

此組件可為以下之一：

• autoChunkingStrategyRequestParam
• staticChunkingStrategyRequestParam

createVectorStoreFileRequest

Name	類型	Description	Required	Default
chunking_strategy	chunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。	No
file_id	字串	一個向量儲存應該使用的檔案 ID。 這類工具很 file_search 有用，可以存取檔案。	Yes

listVectorStoreFilesResponse

Name	類型	Description	Required	Default
資料	陣列		Yes
first_id	字串		Yes
has_more	boolean		Yes
last_id	字串		Yes
物件	字串		Yes

deleteVectorStoreFileResponse

Name	類型	Description	Required	Default
deleted	boolean		Yes
id	字串		Yes
物件	字串		Yes

物件列舉：DeleteVectorStoreFileResponseObject

Value	Description
vector_store.file.deleted

vectorStoreFileBatchObject

一批附在向量儲存上的檔案。

Name	類型	Description	Required	Default
created_at	整數	Unix 的時間戳（以秒計）表示向量儲存檔案批次建立的時間。	Yes
file_counts	物件		Yes
└─ cancelled	整數	被取消的檔案數量。	No
└─ completed	整數	已處理的檔案數量。	No
└─ failed	整數	無法處理的檔案數量。	No
└─ in_progress	整數	目前正在處理的檔案數量。	No
└─ total	整數	檔案總數。	No
id	字串	識別碼，可以在 API 端點中被參考。	Yes
物件	字串	物件類型，永遠 vector_store.file_batch為 。	Yes
狀態	字串	向量儲存檔案批次狀態，可以是 in_progress、 completed、 cancelledfailed或 。	Yes
vector_store_id	字串	檔案所附著的向量儲存器的 ID。	Yes

物件枚舉：VectorStoreFileBatchObjectType

Value	Description
vector_store.files_batch

status Enum： VectorStoreFileBatchObjectStatus

Value	Description
in_progress
completed
cancelled
failed

createVectorStoreFileBatchRequest

Name	類型	Description	Required	Default
chunking_strategy	chunkingStrategyRequestParam	用於分割檔案的分塊策略。 如果沒設定，我會用這個 auto 策略。	No
file_ids	陣列	一份向量儲存應該使用的檔案 ID 清單。 這類工具很 file_search 有用，可以存取檔案。	Yes

assistantStreamEvent

代表串流時發出的事件。

伺服器傳送事件串流中的每個事件都有 event 一個 and data 屬性：

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

每當新物件被建立、轉換到新狀態，或分段串流（delta）時，我們都會發出事件。 例如，當新一行建立thread.run.created、一行完成時，我們會 發出 。thread.run.completed 當助理選擇在執行中建立訊息時，我們會發出一個 thread.message.created event、一個 thread.message.in_progress 事件、多個 thread.message.delta 事件，最後一個 thread.message.completed 事件。

我們可能會隨時間增加更多事件，因此建議你在程式碼中優雅地處理未知事件。

此組件可為以下之一：

• threadStreamEvent
• runStreamEvent
• runStepStreamEvent
• messageStreamEvent
• errorEvent
• doneEvent

threadStreamEvent

此組件可為以下之一：

thread.created

當新執行緒建立時會發生。

Name	類型	Description	Required	Default
資料	threadObject	代表包含訊息的執行緒。	Yes
事件	字串		Yes

Data: threadObject

事件列舉：ThreadStreamEventEnum

Value	Description
thread.created	執行緒創建事件

---

runStreamEvent

此組件可為以下之一：

thread.run.created

當新一輪新跑道被建立時會發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventCreated

Value	Description
thread.run.created

---

thread.run.queued

當跑動進入狀態 queued 時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventQueued

Value	Description
thread.run.queued

---

thread.run.in_progress

當跑數轉為某 in_progress 個狀態時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

Event Enum： RunStreamEventInProgress（RunStreamEventInProgress）

Value	Description
thread.run.in_progress

---

thread.run.requires_action

當跑動進入狀態 requires_action 時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

Event Enum： RunStreamEventRequiresAction

Value	Description
thread.run.requires_action

---

thread.run.completed

當一次跑完成時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventCompleted（已完成）

Value	Description
thread.run.completed

---

thread.run.failed

當一次跑動失敗時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventFailed

Value	Description
thread.run.failed

---

thread.run.cancelling

當跑動進入狀態 cancelling 時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventCancelling

Value	Description
thread.run.cancelling

---

thread.run.cancelled

當某段跑步被取消時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

事件列舉：RunStreamEventCancelled

Value	Description
thread.run.cancelled

---

thread.run.expired

當連載結束時發生。

Name	類型	Description	Required	Default
資料	runObject	代表執行緒上的執行執行。	Yes
事件	字串		Yes

Data: runObject

Event Enum： RunStreamEventExpired

Value	Description
thread.run.expired

---

runStepStreamEvent

此組件可為以下之一：

thread.run.step.created

當產生執行步時會發生。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

事件列舉：RunStepStreamEventCreated

Value	Description
thread.run.step.created

---

thread.run.step.in_progress

當執行步移動到某個 in_progress 狀態時會發生。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

Event Enum： RunStepStreamEventInProgress

Value	Description
thread.run.step.in_progress

---

thread.run.step.delta

當跑步的部分被流式傳輸時會發生。

Name	類型	Description	Required	Default
資料	runStepDeltaObject	代表一個執行步驟的 delta，即串流過程中執行步驟中任何變更欄位。	Yes
事件	字串		Yes

Data: runStepDeltaObject

Event Enum： RunStepStreamEventDelta

Value	Description
thread.run.step.delta

---

thread.run.step.completed

當執行步驟完成時發生。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

事件列舉：RunStepStreamEventCompleted（已完成）

Value	Description
thread.run.step.completed

---

thread.run.step.failed

當執行步驟失敗時發生。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

事件列舉：RunStepStreamEventFailed

Value	Description
thread.run.step.failed

---

thread.run.step.cancelled

當一個跑步被取消時，會發生這種情況。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

事件列舉：RunStepStreamEventCancelled

Value	Description
thread.run.step.cancelled

---

thread.run.step.expired

當一個跑步結束時會發生。

Name	類型	Description	Required	Default
資料	runStepObject	代表執行跑的步驟。	Yes
事件	字串		Yes

Data: runStepObject

Event Enum： RunStepStreamEventExpired

Value	Description
thread.run.step.expired

---

messageStreamEvent

此組件可為以下之一：

thread.message.created

當訊息被建立時會發生。

Name	類型	Description	Required	Default
資料	messageObject	代表線程中的訊息。	Yes
事件	字串		Yes

Data: messageObject

事件列舉：MessageStreamEventCreated

Value	Description
thread.message.created

---

thread.message.in_progress

當訊息移動到某個 in_progress 狀態時會發生。

Name	類型	Description	Required	Default
資料	messageObject	代表線程中的訊息。	Yes
事件	字串		Yes

Data: messageObject

事件列舉：MessageStreamEventInProgress

Value	Description
thread.message.in_progress

---

thread.message.delta

當訊息的部分內容正在串流時會發生。

Name	類型	Description	Required	Default
資料	messageDeltaObject	代表訊息 delta，即串流過程中訊息中任何欄位的變更。	Yes
事件	字串		Yes

Data: messageDeltaObject

事件列舉：MessageStreamEventDelta

Value	Description
thread.message.delta

---

thread.message.completed

當訊息完成時會發生。

Name	類型	Description	Required	Default
資料	messageObject	代表線程中的訊息。	Yes
事件	字串		Yes

Data: messageObject

事件枚舉：MessageStreamEventCompleted（已完成）

Value	Description
thread.message.completed

---

thread.message.incomplete

當訊息在完成前結束時發生。

Name	類型	Description	Required	Default
資料	messageObject	代表線程中的訊息。	Yes
事件	字串		Yes

Data: messageObject

事件列舉：MessageStreamEventIncomplete

Value	Description
thread.message.incomplete

---

Annotation

此組件可為以下之一：

• FileCitation
• UrlCitation
• FilePath

Click

點擊動作。

Name	類型	Description	Required	Default
button	列舉	顯示點擊時按下的滑鼠按鈕。 其中一個 left、 right、 wheelbackforward、 或 。 可能的值：left， right， wheelbackforward	Yes
型別	列舉	指定事件類型。 對於點擊動作，這個屬性總是設為 click。 可能的數值： click	Yes
x	整數	就是那個點擊發生的 x 座標。	Yes
y	整數	點擊發生的Y座標。	Yes

CodeInterpreterFileOutput

程式碼直譯器工具呼叫的輸出是一個檔案。

Name	類型	Description	Required	Default
files	陣列		Yes
型別	列舉	程式碼直譯器檔案輸出的類型。 永遠如此 files。 可能的數值： files	Yes

CodeInterpreterTextOutput

程式碼直譯工具呼叫的輸出是文字。

Name	類型	Description	Required	Default
記錄	字串	程式碼直譯器工具的日誌呼叫。	Yes
型別	列舉	程式碼直譯器文字輸出的類型。 永遠如此 logs。 可能的數值： logs	Yes

CodeInterpreterTool

一個執行程式碼的工具。

Name	類型	Description	Required	Default
file_ids	陣列	執行程式碼的檔案 ID。	Yes
型別	列舉	程式碼直譯器工具的類型。 永遠如此 code_interpreter。 可能的數值： code_interpreter	Yes

CodeInterpreterToolCall

一個用來執行程式碼的工具呼叫。

Name	類型	Description	Required	Default
字碼	字串	執行程式碼。	Yes
id	字串	程式碼直譯器工具呼叫的唯一 ID。	Yes
results	陣列	代碼直譯器工具呼叫的結果。	Yes
狀態	列舉	程式碼直譯器工具呼叫的狀態。 可能的值： in_progress， interpreting， completed	Yes
型別	列舉	程式碼直譯器工具呼叫的類型。 永遠如此 code_interpreter_call。 可能的數值： code_interpreter_call	Yes

CodeInterpreterToolOutput

此組件可為以下之一：

• CodeInterpreterTextOutput
• CodeInterpreterFileOutput

ComparisonFilter

一種用來將指定屬性鍵與指定值進行比較的篩選器，並透過定義的比較操作進行比較。

Name	類型	Description	Required	Default
Key	字串	關鍵是要與價值進行比較。	Yes
型別	列舉	指定比較運算子：eq， ne， gtgteltlte。 - eq：相等 - ne：不等 - gt：大於 - gte：大於或等 - lt：少於 - lte：小於或等於 可能的值：eq， ne， gtgteltlte	Yes
value	字串、數字或布林值	與屬性鍵比較的值;支援字串、數字或布林型態。	Yes

CompoundFilter

使用或 and組合多個濾波器or。

Name	類型	Description	Required	Default
filters	陣列	可以組合多種濾鏡。 項目可以是 ComparisonFilter 或 CompoundFilter。	Yes
型別	列舉	操作類型： and 或 or。 可能的值： and， or	Yes

ComputerAction

此組件可為以下之一：

• Click
• DoubleClick
• Drag
• KeyPress
• Move
• Screenshot
• Scroll
• Type
• Wait

ComputerScreenshotImage

這是一張電腦截圖圖片，使用電腦使用工具。

Name	類型	Description	Required	Default
file_id	字串	包含截圖的上傳檔案識別碼。	No
image_url	字串	截圖圖片的網址。	No
型別	列舉	指定事件類型。 對於電腦截圖，這個屬性總是設定為 computer_screenshot。 可能的數值： computer_screenshot	Yes

ComputerTool

一個控制虛擬電腦的工具。

Name	類型	Description	Required	Default
display_height	number	電腦顯示器的高度。	Yes
display_width	number	電腦顯示器的寬度。	Yes
環境	列舉	需要控制的電腦環境類型。 可能的值：mac， ， windowsubuntu，browser	Yes
型別	列舉	電腦使用工具的類型。 永遠如此 computer_use_preview。 可能的數值： computer-use-preview	Yes

ComputerToolCall

一個工具呼叫電腦使用工具。

Name	類型	Description	Required	Default
動作	ComputerAction		Yes
call_id	字串	一個用來回應工具呼叫並輸出時使用的識別碼。	Yes
id	字串	電腦通話的唯一ID。	Yes
pending_safety_checks	陣列	電腦通話的待定安全檢查。	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	Yes
型別	列舉	電腦通話的類型。 永遠如此 computer_call。 可能的數值： computer_call	Yes

ComputerToolCallOutput

電腦工具呼叫的輸出。

Name	類型	Description	Required	Default
acknowledged_safety_checks	陣列	API 報告的安全檢查已被開發者承認。	No
call_id	字串	產生輸出的電腦工具呼叫的 ID。	Yes
id	字串	電腦工具呼叫輸出的 ID。	No
輸出	ComputerScreenshotImage	這是一張電腦截圖圖片，使用電腦使用工具。	Yes
狀態	列舉	訊息輸入狀態。 其中一個 in_progress、 completed或 incomplete。 當輸入項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	電腦工具呼叫輸出的類型。 永遠如此 computer_call_output。 可能的數值： computer_call_output	Yes

ComputerToolCallOutputResource

Name	類型	Description	Required	Default
acknowledged_safety_checks	陣列	API 報告的安全檢查已被開發者承認。	No
call_id	字串	產生輸出的電腦工具呼叫的 ID。	Yes
id	字串	電腦呼叫工具輸出的唯一 ID。	Yes
輸出	ComputerScreenshotImage	這是一張電腦截圖圖片，使用電腦使用工具。	Yes
狀態	列舉	訊息輸入狀態。 其中一個 in_progress、 completed或 incomplete。 當輸入項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	電腦工具呼叫輸出的類型。 永遠如此 computer_call_output。 可能的數值： computer_call_output	Yes

ComputerToolCallSafetyCheck

電腦通話的安全檢查正在進行中。

Name	類型	Description	Required	Default
字碼	字串	待進行的安全檢查類型。	Yes
id	字串	待進行的安全檢查身份證。	Yes
訊息	字串	關於即將進行的安全檢查細節。	Yes

Content

多模態輸入與輸出內容。

此組件可為以下之一：

• InputContent
• OutputContent

Coordinate

一個 x/y 座標對，例如 { x: 100, y: 200 }。

Name	類型	Description	Required	Default
x	整數	The x-coordinate.	Yes
y	整數	The y-coordinate.	Yes

CreateModelResponseProperties

Name	類型	Description	Required	Default
中繼資料	Metadata	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是長度最大為 512 字元的字串。	No
型號	字串	用來產生回應的模型。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	No	1
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表最終使用者的獨特識別碼，有助於 OpenAI 監控並偵測濫用行為。 .	No

createResponse

Name	類型	Description	Required	Default
include	陣列	{"$ref": "#/components/schemas/includable/description"}	No
輸入	字串或陣列	將文字、圖片或檔案輸入到模型，用來產生回應。	Yes
instructions	字串	在模型上下文中插入系統（或開發者）訊息作為第一個項目。 使用與 previous_response_id時，前一個回應的指令不會被帶到下一個回應。 這讓替換系統（或開發者）訊息變得簡單。	No
max_output_tokens	整數	一個回應可產生的標記數量上限，包括可見輸出標記與推理標記。	No
parallel_tool_calls	boolean	是否允許模型平行執行工具呼叫。	No	True
previous_response_id	字串	之前對模型回應的唯一 ID。 利用這點創造多回合的對話。	No
reasoning	Reasoning	推理模型的配置選項。	No
儲存	boolean	是否要儲存產生的模型回應，以便日後透過 API 檢索。	No	True
串流	boolean	若設定為 true，模型回應資料會在透過 伺服器發送事件產生時串流給用戶端。	No	False
收發簡訊	物件	模型對文字回應的設定選項。 可以是純文字或結構化的 JSON 資料。 Learn more: - 文字輸入與輸出 - 結構化輸出	No
└─ format	TextResponseFormatConfiguration	一個指定模型必須輸出格式的物件。 設定 { "type": "json_schema" } 功能啟用結構化輸出，確保模型符合你提供的 JSON 架構。 預設格式是 { "type": "text" } 沒有額外選項。 不建議用於 GPT-4o 及更新型號： 設定啟用 { "type": "json_object" } 舊版 JSON 模式，確保模型產生的訊息是有效的 JSON。 支援 的模型會偏好使用json_schema	No
tool_choice	ToolChoiceOptions 或 ToolChoiceTypes 或 ToolChoiceFunction	模型在產生回應時應該如何選擇使用哪個（或多個工具）來進行回應。 請參閱參數， tools 了解如何指定模型可呼叫哪些工具。	No
tools	陣列	模型在產生回應時可能會呼叫的一系列工具。 你可以透過設定 tool_choice 參數來指定要使用哪個工具。 你可以提供模型兩類工具： - 內建工具	No
truncation	列舉	模型響應所採用的截斷策略。 - auto：如果此回應及先前回應的上下文超過模型的上下文視窗大小，模型將截斷 回應以符合上下文視窗，將輸入項目置於對話中段。 - disabled （預設）：若模型回應超過模型的上下文視窗大小，請求將以 400 錯誤失敗。 可能的值： auto， disabled	No

DoubleClick

雙擊操作。

Name	類型	Description	Required	Default
型別	列舉	指定事件類型。 對於雙擊操作，這個屬性總是設定為 double_click。 可能的數值： double_click	Yes
x	整數	雙擊發生的 x 座標。	Yes
y	整數	雙擊發生的 y 座標。	Yes

Drag

拖曳動作。

Name	類型	Description	Required	Default
路徑	陣列	一組座標陣列，代表阻力作用的路徑。 座標會以一組物件陣列的形式出現，例如[{ x: 100, y: 200 }, { x: 200, y: 300 }]	Yes
型別	列舉	指定事件類型。 對於拖曳作用，此性質總是設為 drag。 可能的數值： drag	Yes

EasyInputMessage

一個訊息輸入到模型，角色指示指示依階層進行。 與 developer or system 角色一起給予的指令優先於與該角色一起 user 給予的指令。 帶有該 assistant 角色的訊息假設是由模型在先前互動中產生的。

Name	類型	Description	Required	Default
內容	string 或 InputMessageContentList	文字、圖片或音訊輸入到模型，用以產生回應。 也可以包含先前助理的回覆。	Yes
角色	列舉	訊息輸入的角色。 其中user一個 、 assistant、 systemdeveloper或 。 可能的值：user， ， assistantsystem，developer	Yes
型別	列舉	訊息輸入的類型。 永遠如此 message。 可能的數值： message	No

FileCitation

一份檔案的引用。

Name	類型	Description	Required	Default
file_id	字串	檔案的ID。	Yes
索引	整數	檔案清單中的索引。	Yes
型別	列舉	檔案引用的類型。 永遠如此 file_citation。 可能的數值： file_citation	Yes

FilePath

一個指向檔案的路徑。

Name	類型	Description	Required	Default
file_id	字串	檔案的ID。	Yes
索引	整數	檔案清單中的索引。	Yes
型別	列舉	檔案路徑的類型。 永遠如此 file_path。 可能的數值： file_path	Yes

FileSearchRanker

用來搜尋檔案的排名器。 如果沒特別說明，我會用 auto 排名器。

Property	Value
Description	用來搜尋檔案的排名器。 如果沒特別說明，我會用 auto 排名器。
Type	字串
Values	auto default_2024_08_21

FileSearchTool

一個能從上傳檔案中搜尋相關內容的工具。

Name	類型	Description	Required	Default
filters	比較濾波器 或 複合濾波器	一個根據檔案屬性套用的篩選器。	No
max_num_results	整數	回傳的結果數量。 這個數字應該介於1到50之間。	No
ranking_options	物件	搜尋排名選項。	No
└─ ranker	列舉	用來搜尋檔案的排名器。 可能的值： auto， default-2024-11-15	No
└─ score_threshold	number	檔案搜尋的分數門檻，介於0到1之間。 接近 1 的數字會嘗試只回傳最相關的結果，但可能會回傳較少的結果。	No	0
型別	列舉	檔案搜尋工具的類型。 永遠如此 file_search。 可能的數值： file_search	Yes
vector_store_ids	陣列	向量儲存的 ID 用於搜尋。	Yes

FileSearchToolCall

檔案搜尋工具的結果。

Name	類型	Description	Required	Default
id	字串	檔案搜尋工具的唯一 ID 呼叫。	Yes
queries	陣列	用來搜尋檔案的查詢。	Yes
results	陣列	檔案搜尋工具的結果。	No
狀態	列舉	檔案搜尋工具呼叫狀態。 其中 in_progress之一、 searching或 incompletefailed， 可能的值：in_progress， searching， completedincompletefailed	Yes
型別	列舉	檔案搜尋工具的呼叫類型。 永遠如此 file_search_call。 可能的數值： file_search_call	Yes

FunctionTool

在你自己的程式碼中定義一個函式，模型可以選擇呼叫。

Name	類型	Description	Required	Default
description	字串	功能描述。 模型用來判斷是否要呼叫該函式。	No
name	字串	要呼叫的函式名稱。	Yes
parameters	物件	一個描述函式參數的 JSON 結構物件。	Yes
strict	boolean	是否要強制執行嚴格的參數驗證。 預設。true	Yes
型別	列舉	函式工具的類型。 永遠如此 function。 可能的數值： function	Yes

FunctionToolCall

一個用來執行函式的工具呼叫。

Name	類型	Description	Required	Default
arguments	字串	一個要傳遞給函式的參數的 JSON 字串。	Yes
call_id	字串	模型產生的功能工具呼叫的唯一 ID。	Yes
id	字串	函式工具呼叫的唯一 ID。	Yes
name	字串	要執行的函式名稱。	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	函式工具呼叫的類型。 永遠如此 function_call。 可能的數值： function_call	Yes

FunctionToolCallOutput

函式工具呼叫的輸出。

Name	類型	Description	Required	Default
call_id	字串	模型產生的功能工具呼叫的唯一 ID。	Yes
id	字串	函式工具呼叫輸出的唯一 ID。 當此項目透過 API 回傳時會被填入。	No
輸出	字串	函式工具呼叫的輸出 JSON 字串。	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	函式工具呼叫輸出的類型。 永遠如此 function_call_output。 可能的數值： function_call_output	Yes

FunctionToolCallOutputResource

Name	類型	Description	Required	Default
call_id	字串	模型產生的功能工具呼叫的唯一 ID。	Yes
id	字串	函式呼叫工具輸出的唯一 ID。	Yes
輸出	字串	函式工具呼叫的輸出 JSON 字串。	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	函式工具呼叫輸出的類型。 永遠如此 function_call_output。 可能的數值： function_call_output	Yes

includable

指定額外的輸出資料納入模型回應。 目前支援的數值有：

• file_search_call.results：包含檔案搜尋工具呼叫的搜尋結果。
• message.input_image.image_url：包含輸入訊息中的圖片網址。
• computer_call_output.output.image_url：包含來自電腦通話輸出的影像網址。

Property	Value
Description	指定額外的輸出資料納入模型回應。 目前支援的數值有： - file_search_call.results：包含檔案搜尋工具呼叫的搜尋結果。 - message.input_image.image_url：包含輸入訊息中的圖片網址。 - computer_call_output.output.image_url：包含來自電腦通話輸出的影像網址。
Type	字串
Values	file_search_call.results message.input_image.image_url computer_call_output.output.image_url

InputAudio

一個音訊輸入到模型。

Name	類型	Description	Required	Default
資料	字串	Base64編碼的音訊資料。	Yes
format	列舉	音訊資料的格式。 目前支援的格式有 mp3 和 wav。 可能的值： mp3， wav	Yes
型別	列舉	輸入項目的類型。 永遠如此 input_audio。 可能的數值： input_audio	Yes

InputContent

此組件可為以下之一：

• InputText
• InputImage
• InputFile

InputFile

一個檔案輸入到模型。

Name	類型	Description	Required	Default
file_data	字串	要傳送給模型的檔案內容。	No
file_id	字串	要傳送給模型的檔案 ID。	No
filename	字串	要傳送給模型的檔案名稱。	No
型別	列舉	輸入項目的類型。 永遠如此 input_file。 可能的數值： input_file	Yes

InputImage

一個影像輸入到模型。

Name	類型	Description	Required	Default
detail	列舉	要傳送給模型的影像細節層級。 其中一個 high、 low或 auto。 預設為 auto。 可能的值： high， low， auto	Yes
file_id	字串	要傳送給模型的檔案 ID。	No
image_url	字串	要傳送給模型的圖片網址。 資料網址中包含完全限定的網址或 base64 編碼的影像。	No
型別	列舉	輸入項目的類型。 永遠如此 input_image。 可能的數值： input_image	Yes

InputItem

此組件可為以下之一：

• EasyInputMessage
• Item
• ItemReference

InputMessage

一個訊息輸入到模型，角色指示指示依階層進行。 與 developer or system 角色一起給予的指令優先於與該角色一起 user 給予的指令。

Name	類型	Description	Required	Default
內容	InputMessageContentList	一個或多個輸入項目的清單，包含不同內容 types.	Yes
角色	列舉	訊息輸入的角色。 其中一個 user、 system或 developer。 可能的值： user， system， developer	Yes
狀態	列舉	物品狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	訊息輸入的類型。 總是設定為 message。 可能的數值： message	No

InputMessageContentList

包含不同內容類型的一個或多個輸入項目的清單。

此元件未定義屬性。

InputMessageResource

Name	類型	Description	Required	Default
內容	InputMessageContentList	一個或多個輸入項目的清單，包含不同內容 types.	Yes
id	字串	訊息輸入的唯一 ID。	Yes
角色	列舉	訊息輸入的角色。 其中一個 user、 system或 developer。 可能的值： user， system， developer	Yes
狀態	列舉	物品狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	訊息輸入的類型。 總是設定為 message。 可能的數值： message	No

InputText

一個文字輸入到模型。

Name	類型	Description	Required	Default
收發簡訊	字串	輸入到模型的文字。	Yes
型別	列舉	輸入項目的類型。 永遠如此 input_text。 可能的數值： input_text	Yes

Item

內容項目用於產生回應。

此組件可為以下之一：

• InputMessage
• OutputMessage
• FileSearchToolCall
• ComputerToolCall
• ComputerToolCallOutput
• FunctionToolCall
• FunctionToolCallOutput
• ReasoningItem

ItemReference

一個項目的內部識別碼，供參考。

Name	類型	Description	Required	Default
id	字串	要參考的物品編號。	Yes
型別	列舉	要參考的物品類型。 永遠如此 item_reference。 可能的數值： item_reference	Yes

ItemResource

內容項目用於產生回應。

此組件可為以下之一：

• InputMessageResource
• OutputMessage
• FileSearchToolCall
• ComputerToolCall
• ComputerToolCallOutputResource
• FunctionToolCall
• FunctionToolCallOutputResource

KeyPress

模型想要執行的一組按鍵。

Name	類型	Description	Required	Default
keys	陣列	模型要求按下的按鍵組合。 這是一個由字串組成的陣列，每個字串代表一個鍵。	Yes
型別	列舉	指定事件類型。 對於按鍵動作，這個屬性總是設為 keypress。 可能的數值： keypress	Yes

Metadata

一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。

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

此元件未定義屬性。

ModelResponseProperties

Name	類型	Description	Required	Default
中繼資料	Metadata	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是長度最大為 512 字元的字串。	No
型號	字串	用來產生回應的模型。	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	No	1
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	No	1
使用者	字串	一個代表最終使用者的獨特識別碼，有助於 OpenAI 監控並偵測濫用行為。 .	No

Move

滑鼠移動動作。

Name	類型	Description	Required	Default
型別	列舉	指定事件類型。 對於移動動作，此屬性總是設為 move。 可能的數值： move	Yes
x	整數	移動到的 x 座標。	Yes
y	整數	要移動的 y 座標。	Yes

OutputAudio

模型的音訊輸出。

Name	類型	Description	Required	Default
資料	字串	來自該模型的 Base64 編碼音訊資料。	Yes
文字記錄	字串	模型的音訊資料轉錄。	Yes
型別	列舉	輸出音訊的類型。 永遠如此 output_audio。 可能的數值： output_audio	Yes

OutputContent

此組件可為以下之一：

• OutputText
• Refusal

OutputItem

Name	類型	Description	Required	Default
動作	ComputerAction		Yes
arguments	字串	一個要傳遞給函式的參數的 JSON 字串。	Yes
call_id	字串	一個用來回應工具呼叫並輸出時使用的識別碼。	Yes
內容	陣列	理由說明文本內容。	Yes
id	字串	推理內容的唯一識別碼。	Yes
name	字串	要執行的函式名稱。	Yes
pending_safety_checks	陣列	電腦通話的待定安全檢查。	Yes
queries	陣列	用來搜尋檔案的查詢。	Yes
results	陣列	檔案搜尋工具的結果。	No
角色	列舉	輸出訊息的角色。 永遠如此 assistant。 可能的數值： assistant	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	Yes
型別	列舉	物件的類型。 永遠如此 reasoning。 可能的數值： reasoning	Yes

OutputMessage

模型的輸出訊息。

Name	類型	Description	Required	Default
內容	陣列	輸出訊息的內容。	Yes
id	字串	輸出訊息的唯一 ID。	Yes
角色	列舉	輸出訊息的角色。 永遠如此 assistant。 可能的數值： assistant	Yes
狀態	列舉	訊息輸入狀態。 其中一個 in_progress、 completed或 incomplete。 當輸入項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	Yes
型別	列舉	輸出訊息的類型。 永遠如此 message。 可能的數值： message	Yes

OutputText

模型的文字輸出。

Name	類型	Description	Required	Default
annotations	陣列	文字輸出的註解。	Yes
收發簡訊	字串	模型輸出的文字。	Yes
型別	列舉	輸出文字的類型。 永遠如此 output_text。 可能的數值： output_text	Yes

RealtimeSessionCreateRequest

即時會話物件設定。

Name	類型	Description	Required	Default
input_audio_format	列舉	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸入音訊必須為 16 位元 PCM，取樣率為 24kHz，單聲道（mono），且位元組序為小端序。 可能的值： pcm16， g711_ulaw， g711_alaw	No
input_audio_noise_reduction	物件	輸入音訊降噪配置。 這個設定可以設定 null 為關閉。 降噪濾波器會將輸入音訊緩衝區的音訊加入，然後再送入 VAD 與模型。 過濾音訊可提升 VAD 與轉向偵測的準確度（減少誤報），並透過提升輸入音訊的感知來提升模型效能。	No
└─ type	列舉	降噪類型。 near_field 是用於近距離講話的麥克風，如耳機 far_field ;則是用於遠場麥克風，如筆記型電腦或會議室麥克風。 可能的值： near_field， far_field	No
input_audio_transcription	物件	輸入音訊轉錄設定預設為關閉，開啟後可設定為 null 關閉。 輸入音訊轉錄並非模型本身，因為模型直接接收音訊。 轉錄在轉 錄端 點以非同步方式執行，應視為輸入音訊內容的指引，而非模型所聽到的精確內容。 客戶可選擇設定轉錄語言與提示，這些功能為轉錄服務提供額外指引。	No
└─ language	字串	輸入音訊的語言。 以 ISO-639-1 （例如 en）格式提供輸入語言，能提升準確度與延遲。	No
└─ model	字串	目前用於轉錄的模型有 gpt-4o-transcribe、 gpt-4o-mini-transcribe、 gpt-4o-mini-transcribe-2025-12-15、 whisper-1和 。	No
└─ prompt	字串	可選文字用來引導模型風格或延續先前的音訊片段。 對於 whisper-1，提示詞是一串關鍵字。 對模型而言 gpt-4o-transcribe ，提示是自由文字串，例如「expect words with technology but technology」。	No
instructions	字串	預設系統指令（即系統訊息）會置於模型呼叫之前。 此欄位允許客戶引導模型對期望的回應進行調整。 模型可以被指導回應內容與格式（例如「極簡潔」、「表現友善」、「這裡有良好回應的範例」）以及音頻行為（例如「快速說話」、「將情感注入聲音」、「經常笑」）。 這些指令不保證模型一定會遵守，但它們會為模型提供所需的行為指引。 請注意，伺服器會設定預設指令，若未設定此欄位，會被使用，且會在會話開始時的事件中可見 session.created 。	No
max_response_output_tokens	整數或字串	單一助理回應的最大輸出標記數，包含工具呼叫。 提供介於 1 到 4096 之間的整數，以限制輸出標記，或 inf 表示給定模型的最大可用標記數。 預設為 inf。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
型號	字串	本次會話所使用的部署名稱。	No
output_audio_format	列舉	輸出音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸出音訊以 24kHz 的取樣率進行。 可能的值： pcm16， g711_ulaw， g711_alaw	No
temperature	number	模型取樣溫度限制為 [0.6， 1.2]。 對於音響機型，強烈建議溫度為 0.8 以達到最佳效能。	No	0.8
tool_choice	字串	模型如何選擇工具。 選項為 auto、 none、 required或指定函數。	No	auto
tools	陣列	模型可用的工具（功能）。	No
turn_detection	物件	回合偵測的設定，伺服器 VAD 或語義 VAD。 此設定可設定 null 為關閉，此時用戶端必須手動觸發模型回應。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。 語意型 VAD 則更進階，並結合回合偵測模型（結合 VAD）語義上估算使用者是否已講完話，並根據此機率動態設定逾時。 例如，如果使用者的音訊以 uhhm漸漸消失，模型會被分成低機率，並等待使用者繼續說話的時間。 這對於較自然的對話很有用，但可能延遲較高。	No
└─ create_response	boolean	當 VAD 停止事件發生時，是否要自動產生回應。	No	True
└─ eagerness	列舉	只用於 semantic_vad 模式。 模型的積極回應。 low 會等更久讓使用者繼續說話，且 high 回應速度會更快。 auto 是預設值，且等價於 medium。 可能的值：low， ， mediumhigh，auto	No
└─ interrupt_response	boolean	當 VAD 開始事件發生時，是否應該自動中斷任何進行中的回應並輸出到預設對話（即 conversation 的 auto）。	No	True
└─ prefix_padding_ms	整數	只用於 server_vad 模式。 VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	只用於 server_vad 模式。 靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	只用於 server_vad 模式。 VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	列舉	轉向偵測的類型。 可能的值： server_vad， semantic_vad	No
voice	VoiceIdsShared		No

RealtimeSessionCreateResponse

一個新的即時會話配置，搭配一個臨時金鑰。 鍵的預設 TTL 是一分鐘。

Name	類型	Description	Required	Default
client_secret	物件	API 回傳的臨時金鑰。	Yes
└─ expires_at	整數	標記標記到期的時間戳。 目前所有代幣在一分鐘後失效。	No
└─ value	字串	短暫金鑰可用於用戶端環境，用以驗證與即時 API 的連線。 建議在用戶端環境中使用此功能，而非標準的 API 令牌，後者應該只用於伺服器端。	No
input_audio_format	字串	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。	No
input_audio_transcription	物件	輸入音訊轉錄設定預設為關閉，開啟後可設定為 null 關閉。 輸入音訊轉錄並非模型本身，因為模型直接接收音訊。 轉錄在 Whisper 中非同步執行，應視為粗略指引，而非模型所理解的表示。	No
└─ model	字串	目前唯一支持轉錄的模型是轉錄 whisper-1 的模型。	No
instructions	字串	預設系統指令（即系統訊息）會置於模型呼叫之前。 此欄位允許客戶引導模型對期望的回應進行調整。 模型可以被指導回應內容與格式（例如「要非常簡潔」、「表現友善」、「這裡有良好回應的範例」）以及聽覺行為（例如「快速說話」、「將情感注入你的聲音」、「經常笑」）。 這些指令不保證模型一定會遵守，但它們會為模型提供所需的行為指引。 請注意，伺服器會設定預設指令，若未設定此欄位，會被使用，且會在會話開始時的事件中可見 session.created 。	No
max_response_output_tokens	整數或字串	單一助理回應的最大輸出標記數，包含工具呼叫。 提供介於 1 到 4096 之間的整數，以限制輸出標記，或 inf 表示給定模型的最大可用標記數。 預設為 inf。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
output_audio_format	字串	輸出音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。	No
temperature	number	模型取樣溫度限制為 [0.6， 1.2]。 預設為 0.8。	No
tool_choice	字串	模型如何選擇工具。 選項為 auto、 none、 required或指定函數。	No
tools	陣列	模型可用的工具（功能）。	No
turn_detection	物件	轉彎偵測設定。 可以設定為 null 關閉。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。	No
└─ prefix_padding_ms	整數	VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	字串	目前僅 server_vad 支援一種轉彎偵測。	No
voice	VoiceIdsShared		No

RealtimeTranscriptionSessionCreateRequest

即時轉錄會話物件配置。

Name	類型	Description	Required	Default
include	陣列	這是抄本中要包含的項目集合。 目前可用的項目包括： - item.input_audio_transcription.logprobs	No
input_audio_format	列舉	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。 對於 pcm16，輸入音訊必須為 16 位元 PCM，取樣率為 24kHz，單聲道（mono），且位元組序為小端序。 可能的值： pcm16， g711_ulaw， g711_alaw	No
input_audio_noise_reduction	物件	輸入音訊降噪配置。 這個設定可以設定 null 為關閉。 降噪濾波器會將輸入音訊緩衝區的音訊加入，然後再送入 VAD 與模型。 過濾音訊可提升 VAD 與轉向偵測的準確度（減少誤報），並透過提升輸入音訊的感知來提升模型效能。	No
└─ type	列舉	降噪類型。 near_field 是用於近距離講話的麥克風，如耳機 far_field ;則是用於遠場麥克風，如筆記型電腦或會議室麥克風。 可能的值： near_field， far_field	No
input_audio_transcription	物件	輸入音訊轉錄的設定。 客戶可選擇設定轉錄語言與提示，這些功能為轉錄服務提供額外指引。	No
└─ language	字串	輸入音訊的語言。 以 ISO-639-1 （例如 en）格式提供輸入語言，能提升準確度與延遲。	No
└─ model	列舉	用於轉錄的模型，目前的選項有 gpt-4o-transcribe、 gpt-4o-transcribe-diarize、 gpt-4o-mini-transcribegpt-4o-mini-transcribe-2025-12-15whisper-1、 和 。 可能的值：gpt-4o-transcribe， gpt-4o-transcribe-diarize， gpt-4o-mini-transcribegpt-4o-mini-transcribe-2025-12-15whisper-1	No
└─ prompt	字串	可選文字用來引導模型風格或延續先前的音訊片段。 對於 whisper-1，提示詞是一串關鍵字。 對模型而言 gpt-4o-transcribe ，提示是自由文字串，例如「expect words with technology but technology」。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
turn_detection	物件	回合偵測的設定，伺服器 VAD 或語義 VAD。 此設定可設定 null 為關閉，此時用戶端必須手動觸發模型回應。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。 語意型 VAD 則更進階，並結合回合偵測模型（結合 VAD）語義上估算使用者是否已講完話，並根據此機率動態設定逾時。 例如，如果使用者的音訊以 uhhm漸漸消失，模型會被分成低機率，並等待使用者繼續說話的時間。 這對於較自然的對話很有用，但可能延遲較高。	No
└─ create_response	boolean	當 VAD 停止事件發生時，是否要自動產生回應。 無法進行轉錄。	No	True
└─ eagerness	列舉	只用於 semantic_vad 模式。 模型的積極回應。 low 會等更久讓使用者繼續說話，且 high 回應速度會更快。 auto 是預設值，且等價於 medium。 可能的值：low， ， mediumhigh，auto	No
└─ interrupt_response	boolean	當 VAD 開始事件發生時，是否應該自動中斷任何進行中的回應並輸出到預設對話（即 conversation 的 auto）。 無法進行轉錄。	No	True
└─ prefix_padding_ms	整數	只用於 server_vad 模式。 VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	只用於 server_vad 模式。 靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	只用於 server_vad 模式。 VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	列舉	轉向偵測的類型。 可能的值： server_vad， semantic_vad	No

RealtimeTranscriptionSessionCreateResponse

全新的即時轉錄會話設定。

當透過 REST API 在伺服器上建立會話時，會話物件也會包含一個臨時金鑰。 鍵的預設 TTL 是一分鐘。 當會話透過 WebSocket API 更新時，這個屬性並不存在。

Name	類型	Description	Required	Default
client_secret	物件	API 回傳的臨時金鑰。 只有在伺服器上透過 REST API 建立會話時才會顯示。	Yes
└─ expires_at	整數	標記標記到期的時間戳。 目前所有代幣在一分鐘後失效。	No
└─ value	字串	短暫金鑰可用於用戶端環境，用以驗證與即時 API 的連線。 建議在用戶端環境中使用此功能，而非標準的 API 令牌，後者應該只用於伺服器端。	No
input_audio_format	字串	輸入音訊的格式。 選項為 pcm16、 g711_ulaw、 或 g711_alaw。	No
input_audio_transcription	物件	轉錄模型的配置。	No
└─ language	字串	輸入音訊的語言。 以 ISO-639-1 （例如 en）格式提供輸入語言，能提升準確度與延遲。	No
└─ model	列舉	用於轉錄的模型。 可以是 gpt-4o-transcribe、 gpt-4o-mini-transcribe、 gpt-4o-mini-transcribe-2025-12-15或 whisper-1。 可能的值：gpt-4o-transcribe， ， gpt-4o-mini-transcribegpt-4o-mini-transcribe-2025-12-15，whisper-1	No
└─ prompt	字串	可選文字用來引導模型風格或延續先前的音訊片段。 提示詞應該與音頻語言相符。	No
modalities		模型能回應的模態集合。 要關閉音訊，請將此設定為 [“text”]。	No
turn_detection	物件	轉彎偵測設定。 可以設定為 null 關閉。 伺服器 VAD 表示模型會根據音訊音量偵測語音的開始與結束，並在使用者語音結束時作出回應。	No
└─ prefix_padding_ms	整數	VAD 偵測語音前需要包含的音訊量（以毫秒計）。 預設是 300ms。	No
└─ silence_duration_ms	整數	靜默持續時間以偵測語音停止（以毫秒計）。 預設值為 500ms。 當數值較短時，模型會反應更快，但可能會在使用者短暫停頓時介入。	No
└─ threshold	number	VAD 的啟動門檻（0.0 到 1.0），預設為 0.5。 較高的門檻需要較大聲的聲音來啟動模型，因此在嘈雜環境中表現可能更好。	No
└─ type	字串	目前僅 server_vad 支援一種轉彎偵測。	No

Reasoning

推理模型的配置選項。

Name	類型	Description	Required	Default
投入量	ReasoningEffort	限制推理模型的推理努力。 目前支援的值為 low、 medium、 high和 。 減少推理努力能帶來更快的回應，並減少回應中用於推理的標記。	Yes	適中
摘要	列舉	模型所執行推理的摘要。 這對於除錯和理解模型的推理過程非常有用。 其中一或 concisedetailed。 可能的值： concise， detailed	No

ReasoningItem

描述推理模型在產生回應時所使用的思考鏈。

Name	類型	Description	Required	Default
內容	陣列	理由說明文本內容。	Yes
id	字串	推理內容的唯一識別碼。	Yes
狀態	列舉	物品的狀態。 其中一個 in_progress、 completed或 incomplete。 當項目透過 API 回傳時會被填入。 可能的值： in_progress， completed， incomplete	No
型別	列舉	物件的類型。 永遠如此 reasoning。 可能的數值： reasoning	Yes

Refusal

模特兒拒絕了。

Name	類型	Description	Required	Default
refusal	字串	模型拒絕的解釋。	Yes
型別	列舉	拒絕的類型。 永遠如此 refusal。 可能的數值： refusal	Yes

response

Name	類型	Description	Required	Default
created_at	number	Unix 時間戳記（以秒計）顯示此回應被建立的時間。	Yes
錯誤	ResponseError	當模型未能產生回應時，會回傳一個錯誤物件。	Yes
id	字串	此回應的唯一識別碼。	Yes
incomplete_details	物件	說明回應不完整的原因。	Yes
└─ reason	列舉	回應不完整的原因。 可能的值： max_output_tokens， content_filter	No
instructions	字串	在模型上下文中插入系統（或開發者）訊息作為第一個項目。 使用與 previous_response_id時，前一個回應的指令不會被帶到下一個回應。 這讓替換系統（或開發者）訊息變得簡單。	Yes
max_output_tokens	整數	一個回應可產生的代幣數量上限，包括可見的輸出代幣和對話狀態。	No
中繼資料	Metadata	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是長度最大為 512 字元的字串。	Yes
型號	字串	用來產生回應的模型。	Yes
物件	列舉	此資源的物件類型——始終設為 response。 可能的數值： response	Yes
輸出	陣列	模型產生的一系列內容項目。 - 陣列中 output 項目的長度與順序取決於模型的回應。 - 與其存取陣列中的 output 第一個項目，然後假設它是 assistant 包含模型產生內容的訊息，不如考慮在 SDK 支援時使用該 output_text 屬性。	Yes
output_text	字串	僅 SDK 的便利性屬性，包含陣列中所有 output_text 項目 output （若有）彙總後的文字輸出。 支援於 Python 與 JavaScript SDK 中。	No
parallel_tool_calls	boolean	是否允許模型平行執行工具呼叫。	Yes	True
previous_response_id	字串	之前對模型回應的唯一 ID。 利用這點創造多回合的對話。	No
reasoning	Reasoning	推理模型的配置選項。	No
狀態	列舉	回應產生的狀態。 其中completed一個 、 failed、 in_progressincomplete或 。 可能的值：completed， ， failedin_progress，incomplete	No
temperature	number	取樣溫度該用什麼？介於0到2之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 我們通常建議改變這個或 top_p 兩者都做。	Yes	1
收發簡訊	物件	模型對文字回應的設定選項。 可以是純文字或結構化的 JSON 資料。 Learn more: - 文字輸入與輸出 - 結構化輸出	No
└─ format	TextResponseFormatConfiguration	一個指定模型必須輸出格式的物件。 設定 { "type": "json_schema" } 功能啟用結構化輸出，確保模型符合你提供的 JSON 架構。 預設格式是 { "type": "text" } 沒有額外選項。 不建議用於 GPT-4o 及更新型號： 設定啟用 { "type": "json_object" } 舊版 JSON 模式，確保模型產生的訊息是有效的 JSON。 支援 的模型會偏好使用json_schema	No
tool_choice	ToolChoiceOptions 或 ToolChoiceTypes 或 ToolChoiceFunction	模型在產生回應時應該如何選擇使用哪個（或多個工具）來進行回應。 請參閱參數， tools 了解如何指定模型可呼叫哪些工具。	Yes
tools	陣列	模型在產生回應時可能會呼叫的一系列工具。 你可以透過設定 tool_choice 參數來指定要使用哪個工具。 你可以提供模型兩類工具： - 內建工具	Yes
top_p	number	另一種以溫度抽樣為基礎的替代方案稱為核抽樣，模型考慮以top_p機率質量計算的符號結果。 因此 0.1 表示只考慮包含前 10 個% 機率質量的代幣。 我們通常建議改變這個或 temperature 兩者都做。	Yes	1
truncation	列舉	模型響應所採用的截斷策略。 - auto：如果此回應及先前回應的上下文超過模型的上下文視窗大小，模型會透過在對話中刪除輸入項目來截斷回應以符合上下文視窗。 - disabled （預設）：若模型回應超過模型的上下文視窗大小，請求將以 400 錯誤失敗。 可能的值： auto， disabled	No
使用方式	ResponseUsage	代表代幣使用細節，包括輸入代幣、輸出代幣、輸出代幣的分解，以及總代幣使用量。	No
使用者	字串	一個代表最終使用者的獨特識別碼，有助於 OpenAI 監控並偵測濫用行為。 .	No

ResponseAudioDeltaEvent

當有部分音訊回應時會發出。

Name	類型	Description	Required	Default
delta	字串	一塊 Base64 編碼的回應音訊位元組。	Yes
型別	列舉	活動的類型。 永遠如此 response.audio.delta。 可能的數值： response.audio.delta	Yes

ResponseAudioDoneEvent

當音訊回應完成時會發出。

Name	類型	Description	Required	Default
型別	列舉	活動的類型。 永遠如此 response.audio.done。 可能的數值： response.audio.done	Yes

ResponseAudioTranscriptDeltaEvent

當有部分音訊逐字稿時會發出。

Name	類型	Description	Required	Default
delta	字串	音頻回應的部分逐字稿。	Yes
型別	列舉	活動的類型。 永遠如此 response.audio.transcript.delta。 可能的數值： response.audio.transcript.delta	Yes

ResponseAudioTranscriptDoneEvent

當完整音頻逐字稿完成後發布。

Name	類型	Description	Required	Default
型別	列舉	活動的類型。 永遠如此 response.audio.transcript.done。 可能的數值： response.audio.transcript.done	Yes

ResponseCodeInterpreterCallCodeDeltaEvent

當程式碼直譯器新增部分程式碼片段時會發出。

Name	類型	Description	Required	Default
delta	字串	程式碼直譯器新增的部分程式碼片段。	Yes
output_index	整數	程式碼直譯器呼叫的輸出項目索引正在進行中。	Yes
型別	列舉	活動的類型。 永遠如此 response.code_interpreter_call.code.delta。 可能的數值： response.code_interpreter_call.code.delta	Yes

ResponseCodeInterpreterCallCodeDoneEvent

當程式碼片段輸出被程式碼直譯器最終定稿時會發出。

Name	類型	Description	Required	Default
字碼	字串	程式碼直譯器輸出的最終程式碼片段。	Yes
output_index	整數	程式碼直譯器呼叫的輸出項目索引正在進行中。	Yes
型別	列舉	活動的類型。 永遠如此 response.code_interpreter_call.code.done。 可能的數值： response.code_interpreter_call.code.done	Yes

ResponseCodeInterpreterCallCompletedEvent

當程式碼直譯器呼叫完成時會發出。

Name	類型	Description	Required	Default
code_interpreter_call	CodeInterpreterToolCall	一個用來執行程式碼的工具呼叫。	Yes
output_index	整數	程式碼直譯器呼叫的輸出項目索引正在進行中。	Yes
型別	列舉	活動的類型。 永遠如此 response.code_interpreter_call.completed。 可能的數值： response.code_interpreter_call.completed	Yes

ResponseCodeInterpreterCallInProgressEvent

當程式碼解譯器呼叫進行中時會發出。

Name	類型	Description	Required	Default
code_interpreter_call	CodeInterpreterToolCall	一個用來執行程式碼的工具呼叫。	Yes
output_index	整數	程式碼直譯器呼叫的輸出項目索引正在進行中。	Yes
型別	列舉	活動的類型。 永遠如此 response.code_interpreter_call.in_progress。 可能的數值： response.code_interpreter_call.in_progress	Yes

ResponseCodeInterpreterCallInterpretingEvent

當程式碼直譯器正在主動解讀程式碼片段時會發出。

Name	類型	Description	Required	Default
code_interpreter_call	CodeInterpreterToolCall	一個用來執行程式碼的工具呼叫。	Yes
output_index	整數	程式碼直譯器呼叫的輸出項目索引正在進行中。	Yes
型別	列舉	活動的類型。 永遠如此 response.code_interpreter_call.interpreting。 可能的數值： response.code_interpreter_call.interpreting	Yes

ResponseCompletedEvent

當模型響應完成時會發射。

Name	類型	Description	Required	Default
response	response		Yes
型別	列舉	活動的類型。 永遠如此 response.completed。 可能的數值： response.completed	Yes

ResponseContentPartAddedEvent

當新增內容部分時會發出。

Name	類型	Description	Required	Default
content_index	整數	新增內容部分的索引。	Yes
item_id	字串	內容部分被加入的輸出項目的 ID。	Yes
output_index	整數	內容部分被加入的輸出項目索引。	Yes
組件	OutputContent		Yes
型別	列舉	活動的類型。 永遠如此 response.content_part.added。 可能的數值： response.content_part.added	Yes

ResponseContentPartDoneEvent

當內容部分完成時會發出。

Name	類型	Description	Required	Default
content_index	整數	內容部分的索引已經完成。	Yes
item_id	字串	內容部分被加入的輸出項目的 ID。	Yes
output_index	整數	內容部分被加入的輸出項目索引。	Yes
組件	OutputContent		Yes
型別	列舉	活動的類型。 永遠如此 response.content_part.done。 可能的數值： response.content_part.done	Yes

ResponseCreatedEvent

當回應被產生時會發出的事件。

Name	類型	Description	Required	Default
response	response		Yes
型別	列舉	活動的類型。 永遠如此 response.created。 可能的數值： response.created	Yes

ResponseError

當模型未能產生回應時，會回傳一個錯誤物件。

Name	類型	Description	Required	Default
字碼	ResponseErrorCode	回應的錯誤代碼。	Yes
訊息	字串	一個人類易讀的錯誤描述。	Yes

ResponseErrorCode

回應的錯誤代碼。

Property	Value
Description	回應的錯誤代碼。
Type	字串
Values	server_error rate_limit_exceeded invalid_prompt vector_store_timeout invalid_image invalid_image_format invalid_base64_image invalid_image_url image_too_large image_too_small image_parse_error image_content_policy_violation invalid_image_mode image_file_too_large unsupported_image_media_type empty_image_file failed_to_download_image image_file_not_found

ResponseErrorEvent

當發生錯誤時會發出。

Name	類型	Description	Required	Default
字碼	字串	錯誤代碼。	Yes
訊息	字串	錯誤訊息。	Yes
param	字串	錯誤參數。	Yes
型別	列舉	活動的類型。 永遠如此 error。 可能的數值： error	Yes

ResponseFailedEvent

當回應失敗時會觸發的事件。

Name	類型	Description	Required	Default
response	response		Yes
型別	列舉	活動的類型。 永遠如此 response.failed。 可能的數值： response.failed	Yes

ResponseFileSearchCallCompletedEvent

當檔案搜尋呼叫完成（找到結果）時會發出。

Name	類型	Description	Required	Default
item_id	字串	檔案搜尋呼叫所啟動的輸出項目的 ID。	Yes
output_index	整數	檔案搜尋呼叫的輸出項目索引被啟動。	Yes
型別	列舉	活動的類型。 永遠如此 response.file_search_call.completed。 可能的數值： response.file_search_call.completed	Yes

ResponseFileSearchCallInProgressEvent

當檔案搜尋呼叫啟動時會發出。

Name	類型	Description	Required	Default
item_id	字串	檔案搜尋呼叫所啟動的輸出項目的 ID。	Yes
output_index	整數	檔案搜尋呼叫的輸出項目索引被啟動。	Yes
型別	列舉	活動的類型。 永遠如此 response.file_search_call.in_progress。 可能的數值： response.file_search_call.in_progress	Yes

ResponseFileSearchCallSearchingEvent

當檔案搜尋正在搜尋時會發出。

Name	類型	Description	Required	Default
item_id	字串	檔案搜尋呼叫所啟動的輸出項目的 ID。	Yes
output_index	整數	檔案搜尋呼叫所搜尋的輸出項目索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.file_search_call.searching。 可能的數值： response.file_search_call.searching	Yes

ResponseFunctionCallArgumentsDeltaEvent

當存在部分函數-呼叫參數 delta 時會發出。

Name	類型	Description	Required	Default
delta	字串	新增的函式呼叫參數 delta。	Yes
item_id	字串	函式呼叫參數 delta 所加的輸出項目 ID。	Yes
output_index	整數	函式呼叫參數 delta 所加的輸出項目索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.function_call_arguments.delta。 可能的數值： response.function_call_arguments.delta	Yes

ResponseFunctionCallArgumentsDoneEvent

當函式呼叫參數被最終確定時會發出。

Name	類型	Description	Required	Default
arguments	字串	函式呼叫參數。	Yes
item_id	字串	物品的識別碼。	Yes
output_index	整數	輸出項目的索引。	Yes
型別	列舉	可能的數值： response.function_call_arguments.done	Yes

ResponseInProgressEvent

當回應進行中時會發出。

Name	類型	Description	Required	Default
response	response		Yes
型別	列舉	活動的類型。 永遠如此 response.in_progress。 可能的數值： response.in_progress	Yes

ResponseIncompleteEvent

當回應結束為不完整時，會發出一個事件。

Name	類型	Description	Required	Default
response	response		Yes
型別	列舉	活動的類型。 永遠如此 response.incomplete。 可能的數值： response.incomplete	Yes

responseItemList

一份回應項目清單。

Name	類型	Description	Required	Default
資料	陣列	一份用於產生此回應的項目清單。	Yes
first_id	字串	清單中第一個項目的ID。	Yes
has_more	boolean	是否有更多商品可用。	Yes
last_id	字串	清單中最後一項的ID。	Yes
物件	列舉	回傳的物件類型必須是 list。 可能的數值： list	Yes

ResponseModalities

你希望模型產生的輸出類型。 大多數模型都能產生文字，這是預設的：

["text"]

該 gpt-4o-audio-preview 模型也可用於產生音訊。 若要請求此模型同時產生文字與音訊回應，您可以使用：

["text", "audio"]

此元件未定義屬性。

ResponseModalitiesTextOnly

你希望模型產生的輸出類型。 大多數模型都能產生文字，這是預設的：

["text"]

此 API 很快將支援其他輸出模式，包括音訊與影像。

此元件未定義屬性。

ResponseOutputItemAddedEvent

當新增輸出項目時會發出。

Name	類型	Description	Required	Default
項目	OutputItem		Yes
output_index	整數	新增輸出項目的索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_item.added。 可能的數值： response.output_item.added	Yes

ResponseOutputItemDoneEvent

當輸出項目標記為完成時會發出。

Name	類型	Description	Required	Default
項目	OutputItem		Yes
output_index	整數	標記為完成的輸出項目的索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_item.done。 可能的數值： response.output_item.done	Yes

ResponseProperties

Name	類型	Description	Required	Default
instructions	字串	在模型上下文中插入系統（或開發者）訊息作為第一個項目。 使用與 previous_response_id時，前一個回應的指令不會被帶到下一個回應。 這讓替換系統（或開發者）訊息變得簡單。	No
max_output_tokens	整數	一個回應可產生的代幣數量上限，包括可見的輸出代幣和對話狀態。	No
previous_response_id	字串	之前對模型回應的唯一 ID。 利用這點創造多回合的對話。	No
reasoning	Reasoning	推理模型的配置選項。	No
收發簡訊	物件	模型對文字回應的設定選項。 可以是純文字或結構化的 JSON 資料。 Learn more: - 文字輸入與輸出 - 結構化輸出	No
└─ format	TextResponseFormatConfiguration	一個指定模型必須輸出格式的物件。 設定 { "type": "json_schema" } 功能啟用結構化輸出，確保模型符合你提供的 JSON 架構。 預設格式是 { "type": "text" } 沒有額外選項。 不建議用於 GPT-4o 及更新型號： 設定啟用 { "type": "json_object" } 舊版 JSON 模式，確保模型產生的訊息是有效的 JSON。 支援 的模型會偏好使用json_schema	No
tool_choice	ToolChoiceOptions 或 ToolChoiceTypes 或 ToolChoiceFunction	模型在產生回應時應該如何選擇使用哪個（或多個工具）來進行回應。 請參閱參數， tools 了解如何指定模型可呼叫哪些工具。	No
tools	陣列	模型在產生回應時可能會呼叫的一系列工具。 你可以透過設定 tool_choice 參數來指定要使用哪個工具。 你可以提供模型兩類工具： - 內建工具	No
truncation	列舉	模型響應所採用的截斷策略。 - auto：如果此回應及先前回應的上下文超過模型的上下文視窗大小，模型會透過在對話中刪除輸入項目來截斷回應以符合上下文視窗。 - disabled （預設）：若模型回應超過模型的上下文視窗大小，請求將以 400 錯誤失敗。 可能的值： auto， disabled	No

ResponseRefusalDeltaEvent

當有部分拒絕文本時會發出。

Name	類型	Description	Required	Default
content_index	整數	就是拒絕文本所加入的內容部分的索引。	Yes
delta	字串	新增的拒絕文字。	Yes
item_id	字串	拒絕文字被加入的輸出項目的 ID。	Yes
output_index	整數	拒絕文字被加入的輸出項目索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.refusal.delta。 可能的數值： response.refusal.delta	Yes

ResponseRefusalDoneEvent

當拒絕文字最終確定時會發出。

Name	類型	Description	Required	Default
content_index	整數	內容索引部分是拒絕文本最終確定的部分。	Yes
item_id	字串	拒絕文本最終確定的輸出項目 ID。	Yes
output_index	整數	拒絕文本最終完成的輸出項目索引。	Yes
refusal	字串	拒絕文本最終確定。	Yes
型別	列舉	活動的類型。 永遠如此 response.refusal.done。 可能的數值： response.refusal.done	Yes

responseStreamEvent

Name	類型	Description	Required	Default
註釋	Annotation		Yes
annotation_index	整數	新增註解的索引。	Yes
arguments	字串	函式呼叫參數。	Yes
字碼	字串	錯誤代碼。	Yes
code_interpreter_call	CodeInterpreterToolCall	一個用來執行程式碼的工具呼叫。	Yes
content_index	整數	內容索引部分是文字內容最終完成的部分。	Yes
delta	字串	新增的文字差異。	Yes
項目	OutputItem	標示為完成的輸出項目。	Yes
item_id	字串	輸出項目的 ID，文字內容最終確定。	Yes
訊息	字串	錯誤訊息。	Yes
output_index	整數	文本內容最終完成的輸出項目索引。	Yes
param	字串	錯誤參數。	Yes
組件	OutputContent	內容部分已經完成。	Yes
refusal	字串	拒絕文本最終確定。	Yes
response	response	那個不完整的回應。	Yes
收發簡訊	字串	文字內容已定稿。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_text.done。 可能的數值： response.output_text.done	Yes

ResponseTextAnnotationDeltaEvent

當新增文字註解時會發出。

Name	類型	Description	Required	Default
註釋	Annotation		Yes
annotation_index	整數	新增註解的索引。	Yes
content_index	整數	就是文字註解被加入的內容部分的索引。	Yes
item_id	字串	就是文字註解所加到的輸出項目的 ID。	Yes
output_index	整數	就是加註解的輸出項目的索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_text.annotation.added。 可能的數值： response.output_text.annotation.added	Yes

ResponseTextDeltaEvent

當有額外的文字 delta 時會發出。

Name	類型	Description	Required	Default
content_index	整數	就是新增文字 delta 的內容部分的索引。	Yes
delta	字串	新增的文字差異。	Yes
item_id	字串	就是新增文字 delta 的輸出項目的 ID。	Yes
output_index	整數	文字 delta 所加入的輸出項目索引。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_text.delta。 可能的數值： response.output_text.delta	Yes

ResponseTextDoneEvent

當文字內容最終確定時會發出。

Name	類型	Description	Required	Default
content_index	整數	內容索引部分是文字內容最終完成的部分。	Yes
item_id	字串	輸出項目的 ID，文字內容最終確定。	Yes
output_index	整數	文本內容最終完成的輸出項目索引。	Yes
收發簡訊	字串	文字內容已定稿。	Yes
型別	列舉	活動的類型。 永遠如此 response.output_text.done。 可能的數值： response.output_text.done	Yes

ResponseUsage

代表代幣使用細節，包括輸入代幣、輸出代幣、輸出代幣的分解，以及總代幣使用量。

Name	類型	Description	Required	Default
input_tokens	整數	輸入標記的數量。	Yes
output_tokens	整數	輸出代幣的數量。	Yes
output_tokens_details	物件	輸出代幣的詳細分解。	Yes
└─ reasoning_tokens	整數	推理代幣的數量。	No
total_tokens	整數	所使用的代幣總數。	Yes

Screenshot

截圖動作。

Name	類型	Description	Required	Default
型別	列舉	指定事件類型。 對於截圖動作，這個屬性總是設定為 screenshot。 可能的數值： screenshot	Yes

Scroll

一個捲軸動作。

Name	類型	Description	Required	Default
scroll_x	整數	橫向捲軸的距離。	Yes
scroll_y	整數	垂直捲軸距離。	Yes
型別	列舉	指定事件類型。 對於滾動動作，此性質總是設為 scroll。 可能的數值： scroll	Yes
x	整數	卷軸發生的X座標。	Yes
y	整數	卷軸發生的Y座標。	Yes

StopConfiguration

最多有 4 個序列，API 停止產生更多標記。 回傳的文字不會包含停止音序列。

此組件可為以下之一：

TextResponseFormatConfiguration

一個指定模型必須輸出格式的物件。

配置 { "type": "json_schema" } 功能啟用結構化輸出，確保模型符合你提供的 JSON 架構。

預設格式是 { "type": "text" } 沒有額外選項。

不建議用於 GPT-4o 及更新型號：

設定啟用 { "type": "json_object" } 舊版 JSON 模式，確保模型產生的訊息是有效的 JSON。 支援 的模型會偏好使用json_schema

此組件可為以下之一：

• ResponseFormatText
• TextResponseFormatJsonSchema
• ResponseFormatJsonObject

TextResponseFormatJsonSchema

JSON Schema 回應格式。 用來產生結構化的 JSON 回應。 了解更多關於結構化輸出的資訊。

Name	類型	Description	Required	Default
description	字串	描述回應格式的用途，模型用來決定如何以該格式回應。	No
name	字串	回應格式的名稱。 必須是 a-z、A-Z、0-9，或包含底線和破折號，長度最多為 64。	No
結構描述	ResponseFormatJsonSchemaSchema	回應格式的結構，描述為 JSON Schema 物件。	Yes
strict	boolean	在產生輸出時是否要啟用嚴格的結構遵循。 若設為 true，模型將始終遵循欄位中定義 schema 的精確模式。 當 strict 為 時 true，僅支援部分 JSON 架構。	No	False
型別	列舉	定義的回應格式類型。 永遠如此 json_schema。 可能的數值： json_schema	Yes

Tool

此組件可為以下之一：

• FileSearchTool
• FunctionTool
• ComputerTool

ToolChoiceFunction

使用此選項強制模型呼叫特定函式。

Name	類型	Description	Required	Default
name	字串	要呼叫的函式名稱。	Yes
型別	列舉	對於函式呼叫，型別總是 function。 可能的數值： function	Yes

ToolChoiceOptions

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

none 表示模型不會呼叫任何工具，而是產生訊息。

auto 表示模型可以選擇產生訊息或呼叫一個或多個工具。

required 表示模型必須呼叫一個或多個工具。

Property	Value
Description	控制模型呼叫哪個（如果有）工具。 none 表示模型不會呼叫任何工具，而是產生訊息。 auto 表示模型可以選擇產生訊息或呼叫一個或多個工具。 required 表示模型必須呼叫一個或多個工具。
Type	字串
Values	none auto required

ToolChoiceTypes

表示模型應使用內建工具來產生回應。

Name	類型	Description	Required	Default
型別	列舉	模型應該使用的託管工具類型。 允許的值如下： - file_search - computer_use_preview 可能的值： file_search， computer_use_preview	Yes

類型

一個輸入文字的動作。

Name	類型	Description	Required	Default
收發簡訊	字串	要打字的文字。	Yes
型別	列舉	指定事件類型。 對於型別動作，此性質總是設為 type。 可能的數值： type	Yes

UpdateVectorStoreFileAttributesRequest

Name	類型	Description	Required	Default
attributes	VectorStoreFileAttributes	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是最大長度為 512 字元的字串、布林值或數字。	Yes

UrlCitation

引用一個用於產生模型回應的網路資源。

Name	類型	Description	Required	Default
end_index	整數	訊息中網址引用最後一個字元的索引。	Yes
start_index	整數	訊息中 URL 引用首個字元的索引。	Yes
title	字串	網路資源的標題。	Yes
型別	列舉	引用網址的類型。 永遠如此 url_citation。 可能的數值： url_citation	Yes
url	字串	網路資源的網址。	Yes

VectorStoreFileAttributes

一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是最大長度為 512 字元的字串、布林值或數字。

此元件未定義屬性。

VectorStoreFileContentResponse

代表向量儲存檔案的解析內容。

Name	類型	Description	Required	Default
資料	陣列	解析過檔案內容。	Yes
has_more	boolean	顯示是否有更多內容頁面可供取用。	Yes
next_page	字串	下一頁的代幣（如果有的話）。	Yes
物件	列舉	物件類型，且總是 vector_store.file_content.page 可能的數值： vector_store.file_content.page	Yes

VectorStoreSearchRequest

Name	類型	Description	Required	Default
filters	比較濾波器 或 複合濾波器	一個根據檔案屬性套用的篩選器。	No
max_num_results	整數	回傳的結果數量。 這個數字應該介於1到50之間。	No	10
查詢	字串或陣列	搜尋的查詢字串	Yes
ranking_options	物件	搜尋排名選項。	No
└─ ranker	列舉	可能的值： auto， default-2024-11-15	No
└─ score_threshold	number		No	0
rewrite_query	boolean	是否要重寫向量搜尋的自然語言查詢。	No	False

VectorStoreSearchResultContentObject

Name	類型	Description	Required	Default
收發簡訊	字串	文字內容從搜尋中返回。	Yes
型別	列舉	內容的類型。 可能的數值： text	Yes

VectorStoreSearchResultItem

Name	類型	Description	Required	Default
attributes	VectorStoreFileAttributes	一組 16 組可附加於物件的鍵值對。 這對於以結構化格式儲存物件的額外資訊，以及透過 API 或儀表板查詢物件非常有用。 鍵是長度最大為 64 字元的字串。 值是最大長度為 512 字元的字串、布林值或數字。	Yes
內容	陣列	檔案中的內容區塊。	Yes
file_id	字串	向量儲存檔案的 ID。	Yes
filename	字串	向量儲存檔案的名稱。	Yes
分數	number	結果的相似度分數。	Yes

VectorStoreSearchResultsPage

Name	類型	Description	Required	Default
資料	陣列	搜尋結果項目列表。	Yes
has_more	boolean	顯示是否有更多結果可取。	Yes
next_page	字串	下一頁的代幣（如果有的話）。	Yes
物件	列舉	物件類型，且總是 vector_store.search_results.page 可能的數值： vector_store.search_results.page	Yes
search_query	陣列		Yes

VoiceIdsShared

此元件未定義屬性。

Wait

等待動作。

Name	類型	Description	Required	Default
型別	列舉	指定事件類型。 對於等待動作，此屬性總是設為 wait。 可能的數值： wait	Yes

ReasoningEffort

限制推理模型的推理努力。 目前支援的值為 low、 medium、 high和 。 減少推理努力能帶來更快的回應，並減少回應中用於推理的標記。

Property	Value
Description	限制推理模型的推理努力。 目前支援的值為 low、 medium、 high和 。 減少推理努力能帶來更快的回應，並減少回應中用於推理的標記。
Type	字串
Default	適中
Values	low medium high

errorEvent

發生錯誤時會發生。 這可能是因為內部伺服器錯誤或逾時所致。

Name	類型	Description	Required	Default
資料	error		Yes
事件	字串		Yes

event Enum： ErrorEventEnum

Value	Description
錯誤

doneEvent

當溪流結束時發生。

Name	類型	Description	Required	Default
資料	字串		Yes
事件	字串		Yes

event Enum： DoneEventEnum

Value	Description
done

data Enum： DoneEventDataEnum

Value	Description
[DONE]

Next steps

學習模型 ，以及使用 REST API 微調。 深入了解 驅動 Azure OpenAI 的底層模型。