Azure OpenAI Service REST API 參考

  • 發行項

本文提供 Azure OpenAI 的推斷 REST API 端點詳細數據。

驗證

Azure OpenAI 提供兩種方法進行驗證。 您可以使用 API 金鑰或 Microsoft Entra 識別碼。

  • API 金鑰驗證：針對這種類型的驗證，所有 API 要求都必須在 HTTP 標頭中包含 api-key API 金鑰。 快速入門提供如何使用這種類型的驗證進行呼叫的指引。

  • Microsoft Entra ID 驗證：您可以使用 Microsoft Entra 令牌來驗證 API 呼叫。 驗證令牌會以標頭的形式包含在要求中 Authorization 。 提供的權杖前面必須加上 Bearer，例如 Bearer YOUR_AUTH_TOKEN。 您可以閱讀我們的使用 Microsoft Entra 識別碼進行驗證的作法指南。

REST API 版本控制

服務 API 使用 api-version 查詢參數設定版本。 所有版本都遵循 YYYY-MM-DD 日期結構。 例如：

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

完成

使用完成作業，模型會根據提供的提示產生一或多個預測完成。 服務也可以傳回每個位置替代令牌的機率。

建立完成

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
deployment-id string 必要 您部署模型時所選擇的部署名稱。
api-version string 必要 用於此作業的 API 版本。 這會遵循 YYYY-MM-DD 格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
prompt 字串或陣列 選擇性 <\|endoftext\|> 提示或提示產生完成、編碼為字串或字串數位。 <\|endoftext\|> 是模型在定型期間看到的檔分隔符，因此如果未指定提示，模型就會產生如同從新檔的開頭一樣。
max_tokens 整數 選擇性 16 完成時要產生的權杖數目上限。 提示加上max_tokens的令牌計數不能超過模型的內容長度。 大部分模型的內容長度為 2048 個標記（但支援 4096 的最新模型除外）。
temperature 數值 選擇性 1 要使用的取樣溫度，介於 0 到 2 之間。 較高的值表示模型會承擔更多風險。 嘗試 0.9 以取得更有創意的應用程式，而 0 （argmax sampling） 則為具有定義完善的答案。 我們通常建議變更此或top_p，但不要同時變更這兩者。
top_p 數值 選擇性 1 使用溫度進行取樣的替代方法，稱為核取樣，其中模型會考慮具有top_p機率品質的令牌結果。 因此，0.1 表示只考慮組成前 10% 機率質量的權杖。 我們通常建議改變這個或溫度，但不要同時改變這兩者。
logit_bias map 選擇性 null 修改完成時出現指定標記的可能性。 接受 JSON 物件，將令牌（由 GPT Tokenizer 中的令牌識別碼所指定）對應至 -100 到 100 的相關偏差值。 您可以使用這個 Tokenizer 工具（適用於 GPT-2 和 GPT-3），將文字轉換成令牌識別碼。 在數學上，偏差會加入模型在取樣之前所產生的對數。 確切的效果會因模型而異，但介於 -1 和 1 之間的值應減少或增加選取的可能性;-100 或 100 之類的值應該會導致相關令牌的禁止或獨佔選取。 例如，您可以傳遞 {“50256”： -100} 以防止 <產生 |endoftext|> Token。
user string 選擇性 代表使用者的唯一標識符，可協助監視和偵測濫用
n 整數 選擇性 1 每個提示要產生的完成項數量。 注意：因為此參數會產生許多完成項，所以會快速消耗權杖配額。 請小心使用 ，並確定您有合理的max_tokens和停止設定。
stream boolean 選擇性 False 是否要串流回部分進度。 如果設定，令牌會在數據傳送時以僅限伺服器傳送的事件的形式傳送，而數據流會由數據終止：[DONE] 訊息。
logprobs 整數 選擇性 null 在logprobs上包含最有可能令牌的記錄機率，以及所選的令牌。 例如，如果logprobs為10，API會傳回10個最有可能令牌的清單。 API 一律會傳回取樣令牌的logprob，因此回應中最多可能會有logprobs+1元素。 這個參數不能與 搭配 gpt-35-turbo使用。
suffix string 選擇性 null 插入文字完成之後的後綴。
echo boolean 選擇性 False 除了完成之外，還回顯提示。 這個參數不能與 搭配 gpt-35-turbo使用。
stop 字串或陣列 選擇性 null 最多四個序列，API 將停止產生進一步的令牌。 傳回的文字不會包含停止序列。 針對具有視覺的 GPT-4 Turbo，最多可支援兩個序列。
presence_penalty 數值 選擇性 0 介於 -2.0 和 2.0 之間的數字。 正值會根據權杖迄今為止是否出現在文字中來打壓新權杖，提高模型討論新主題的可能性。
frequency_penalty 數值 選擇性 0 介於 -2.0 和 2.0 之間的數字。 正值會根據目前文字中的現有頻率來懲罰新的標記，減少模型重複相同行動詞的可能性。
best_of 整數 選擇性 1 產生best_of完成伺服器端，並傳回「最佳」（每個標記的記錄機率最低的記錄機率）。 結果不能串流。 搭配 n 使用時，best_of會控制候選完成的數目，n 會指定傳回多少個 – best_of必須大於 n。 注意：因為此參數會產生許多完成項，所以會快速消耗權杖配額。 請小心使用 ，並確定您有合理的max_tokens和停止設定。 這個參數不能與 搭配 gpt-35-turbo使用。

範例要求

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

範例回應

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

在範例回應中， finish_reason 等於 stop。 如果 finish_reason 相等， content_filter 請參閱我們的 內容篩選指南 ，以了解發生的原因。

Embeddings

取得給定輸入的向量表示法，此輸入可由機器學習模型和其他演演算法輕鬆取用。

注意

OpenAI 目前允許使用 text-embedding-ada-002較多的數位輸入。 Azure OpenAI 目前支援最多 16 個的 text-embedding-ada-002 (Version 2)輸入數位列。 兩者都需要每個 API 要求的最大輸入權杖限制，才能在此模型中維持在 8191 之下。

建立內嵌

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
deployment-id string 必要 模型部署的名稱。 您必須先部署模型，才能進行呼叫。
api-version string 必要 用於此作業的 API 版本。 這會遵循 YYYY-MM-DD 格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
input 字串或陣列 Yes N/A 要取得內嵌的輸入文字，編碼為數位或字串。 輸入令牌的數目會根據您使用的模型而有所不同。 僅 text-embedding-ada-002 (Version 2) 支持數位輸入。
user string No Null 代表使用者的唯一標識碼。 這有助於 Azure OpenAI 監視和偵測濫用。 不要傳遞 PII 識別碼，而是使用虛擬識別碼，例如 GUID
encoding_format string No float 要傳回內嵌格式。 可以是 float 或 base64。 預設為 float。

[已在 中 2024-03-01-preview新增]。
dimensions 整數 No 產生的輸出內嵌應具有的維度數目。 僅支援 text-embedding-3 和更新版本的模型。

[已在 ] 中 2024-03-01-preview新增

範例要求

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

範例回應

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

聊天完成

使用 GPT-35-Turbo 和 GPT-4 模型建立聊天訊息的完成。

建立聊天完成

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
deployment-id string 必要 模型部署的名稱。 您必須先部署模型，才能進行呼叫。
api-version string 必要 用於此作業的 API 版本。 這會遵循YYYY-MM-DD或YYYY-MM-DD-preview格式。

支援的版本

要求本文

要求本文包含一系列訊息。 模型會使用先前的訊息作為內容，產生最後一則訊息的回應。

參數 類型 是必要的嗎? 預設 描述
messages 陣列 Yes N/A 與此聊天完成要求相關聯的一系列訊息。 它應該在交談中包含先前的訊息。 每個訊息都有 role 和 content。
role string Yes N/A 指出誰正在提供目前的訊息。 可以是 system、user、assistant、tool或 function。
content 字串或陣列 Yes N/A 訊息的內容。 除非在已啟用視覺的案例中，否則必須是字串。 如果它是訊息的一 user 部分，使用 GPT-4 Turbo 搭配視覺模型，並搭配最新的 API 版本，則必須 content 是結構的陣列，其中每個專案都代表文字或影像：
  • text：輸入文字會以具有下列屬性的結構表示：
    • type = “text”
    • text = 輸入文字
  • images：輸入影像會以具有下列屬性的結構表示：
    • type = “image_url”
    • image_url = 具有下列屬性的結構：
      • url = 影像 URL
      • （選擇性） detail = high、 low或 auto
contentPart object No N/A 使用者的多重強制回應訊息的一部分。 它可以是文字類型或影像類型。 如果文字，它將會是文字字串。 如果 image，它會是 contentPartImage 物件。
contentPartImage object No N/A 代表用戶上傳的影像。 url它具有 屬性，其為影像的 URL 或基底 64 編碼的影像數據。 它也有 detail 屬性，可以是 auto、 low或 high。
enhancements object No N/A 代表聊天所要求的視覺增強功能。 grounding它有 和 ocr 屬性，每個都有布爾enabled屬性。 使用這些參數來要求 OCR 服務和/或物件偵測/地面服務 [GA API 中無法使用 2024-02-01 此預覽參數]。
dataSources object No N/A 表示其他資源數據。 視覺增強功能需要 電腦視覺 資源數據。 它有屬性 type ，它應該是 "AzureComputerVision" 和 parameters 屬性，其具有 endpoint 和 key 屬性。 這些字串應該設定為 電腦視覺 資源的端點 URL 和存取密鑰。

範例要求

僅限文字聊天

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

與視覺交談

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

增強與視覺的聊天

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

範例回應

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

調整輸出格式以方便閱讀，實際輸出是一個沒有換行符的單一文字區塊。

在範例回應中， finish_reason 等於 stop。 如果 finish_reason 相等， content_filter 請參閱我們的 內容篩選指南 ，以了解發生的原因。

重要

functions和 function_call 參數已隨著 API 版本的發行2023-12-01-preview而淘汰。 的取代 functions 是 tools 參數。 的取代 function_call 是 tool_choice 參數。 在 中引進 2023-12-01-preview 的平行函式呼叫僅支援 gpt-35-turbo （1106） 和 gpt-4 （1106-preview） 也稱為 GPT-4 Turbo Preview。

參數 類型 是必要的嗎? 預設 描述
messages 陣列 必要 與此聊天完成要求相關聯的內容訊息集合。 一般使用方式的 開頭是系統角色的聊天訊息 ，其會提供助理行為的指示，後面接著在使用者和助理角色之間交替訊息。
temperature 數值 選擇性 1 要使用的取樣溫度，介於 0 到 2 之間。 0.8 等較高的值會讓輸出更隨機，而 0.2 等較低值會使輸出更專注且具決定性。 我們通常建議改變這個 或 top_p ，但不是兩者。
n 整數 選擇性 1 要為每個輸入訊息產生多少個聊天完成選項。
stream boolean 選擇性 false 如果設定，則會傳送部分訊息差異，就像在ChatGPT中一樣。 令牌會在可用時以僅限數據伺服器傳送的事件的形式傳送，而數據流會由 data: [DONE] 訊息終止。
stop 字串或陣列 選擇性 null 最多 4 個序列，API 將停止產生進一步的令牌。
max_tokens 整數 選擇性 Inf 所產生答案允許的令牌數目上限。 根據預設，模型可以傳回的令牌數目會是 （4096 - 提示令牌）。
presence_penalty 數值 選擇性 0 介於 -2.0 和 2.0 之間的數字。 正值會根據權杖迄今為止是否出現在文字中來打壓新權杖，提高模型討論新主題的可能性。
frequency_penalty 數值 選擇性 0 介於 -2.0 和 2.0 之間的數字。 正值會根據目前文字中的現有頻率來懲罰新的標記，減少模型重複相同行動詞的可能性。
logit_bias object 選擇性 null 修改完成時出現指定標記的可能性。 接受 json 物件，此物件會將令牌（由令牌化工具中的令牌標識碼所指定）對應至 -100 到 100 的相關偏差值。 在數學上，偏差會加入模型在取樣之前所產生的對數。 確切的效果會因模型而異，但介於 -1 和 1 之間的值應減少或增加選取的可能性;-100 或 100 之類的值應該會導致相關令牌的禁止或獨佔選取。
user string 選擇性 代表使用者的唯一標識符，可協助 Azure OpenAI 監視和偵測濫用行為。
function_call 選擇性 [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]控制模型回應函式呼叫的方式。 “none” 表示模型不會呼叫函式，並響應使用者。 auto 表示模型可以在使用者或呼叫函式之間挑選。 透過 {“name”： “my_function”} 指定特定函式會強制模型呼叫該函式。 當沒有任何函式存在時，“none” 是預設值。 auto 如果函式存在，則為預設值。 此參數需要 API 版本 2023-07-01-preview
functions FunctionDefinition[] 選擇性 [Deprecated in 2023-12-01-preview replacement paremeter is tools] 模型可以為其產生 JSON 輸入的函式清單。 此參數需要 API 版本 2023-07-01-preview
tools string （工具的類型。只 function 支援 。 選擇性 模型可以呼叫的工具清單。 目前僅支援函式做為工具。 使用此選項來提供模型可以為其產生 JSON 輸入的函式清單。 此參數需要 API 版本 2023-12-01-preview
tool_choice 字串或物件 選擇性 當沒有任何函式存在時，none 是預設值。 auto 如果函式存在，則為預設值。 控制模型所呼叫的函式（如果有的話）。 None 表示模型不會呼叫函式，而是會產生訊息。 auto 表示模型可以在產生訊息或呼叫函式之間進行選擇。 透過 {“type： ”function“， ”function“： {”name“： ”my_function“}} 指定特定函式，會強制模型呼叫該函式。 此參數需要 API 版本或更新版本 2023-12-01-preview 。

ChatMessage

聊天完成互動內的單一角色屬性訊息。

名稱 類型​​ 描述
content string 與此訊息承載相關聯的文字。
function_call FunctionCall 應該呼叫之函式的名稱和自變數，如模型所產生。
NAME 字串 name此訊息作者的 。 name 如果 role 為 function，則為必要專案，而且應該是回應在 中的 content函式名稱。 可以包含 a-z、A-Z、0-9 和底線，最大長度為 64 個字元。
角色 (role) ChatRole 與此訊息承載相關聯的角色

ChatRole

聊天完成互動內訊息之預定用途的描述。

名稱 類型​​ 描述
assistant string 提供系統指示、使用者提示輸入回應的角色。
函數 string 提供聊天完成函式結果的角色。
系統 string 指示或設定助理行為的角色。
user string 提供聊天完成輸入的角色。

函式

這會與 API 版本 2023-12-01-preview中新增的參數搭配tools使用。

名稱 類型​​ 描述
description string 模型用來選擇函式何時及如何呼叫函式的描述
NAME 字串 要呼叫之函式的名稱。 必須是 a-z、A-Z、0-9，或包含底線和虛線，最大長度為 64
parameters object 函式所接受的參數，描述為 JSON 架構物件。 如需格式的相關文件，請參閱 JSON 架構參考。」

FunctionCall-Deprecated

應該呼叫之函式的名稱和自變數，如模型所產生。 這需要 API 版本 2023-07-01-preview

名稱 類型​​ 描述
參數 string 使用的自變數，以 JSON 格式產生模型所產生的自變數。 模型不一定會產生有效的 JSON，而且可能會捏造函式架構未定義的參數。 在呼叫函式之前，請先驗證程序代碼中的自變數。
NAME 字串 要呼叫的函式名稱。

FunctionDefinition-Deprecated

聊天完成可以叫用的呼叫端指定函式定義，以回應相符的用戶輸入。 這需要 API 版本 2023-07-01-preview

名稱 類型​​ 描述
description string 函式所執行之用途的描述。 模型會在選取函式並解譯其參數時使用此描述。
NAME 字串 要呼叫之函式的名稱。
parameters 函式所接受的參數，描述為 JSON 架構 物件。

完成延伸模組

聊天完成的延伸模組，例如 Azure OpenAI On Your Data。

重要

下列資訊適用於 API 版本 2023-12-01-preview 。 這不是 API 的目前版本。 若要尋找最新的參考檔，請參閱 Azure OpenAI On Data 參考。

使用聊天完成延伸模組

POST {your-resource-name}/openai/deployments/{deployment-id}/extensions/chat/completions?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
deployment-id string 必要 模型部署的名稱。 您必須先部署模型，才能進行呼叫。
api-version string 必要 用於此作業的 API 版本。 這會遵循 YYYY-MM-DD 格式。

支援的版本

範例要求

您可以使用 Azure AI 搜尋、適用於 MongoDB 的 Azure Cosmos DB 虛擬核心、Pinecone 和 Elasticsearch 提出要求。 如需詳細資訊，請參閱 Azure OpenAI On Your Data。

curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "max_tokens": 1000,
    "top_p": 1.0,
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "YOUR_AZURE_COGNITIVE_SEARCH_ENDPOINT",
                "key": "YOUR_AZURE_COGNITIVE_SEARCH_KEY",
                "indexName": "YOUR_AZURE_COGNITIVE_SEARCH_INDEX_NAME"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the differences between Azure Machine Learning and Azure AI services?"
        }
    ]
}
'
Azure Cosmos DB for MongoDB 虛擬核心
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "top_p": 1.0,
    "max_tokens": 800,
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": "What is the company insurance plan?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCosmosDB",
            "parameters": {
                "authentication": {
                    "type": "ConnectionString",
                    "connectionString": "mongodb+srv://onyourdatatest:{password}$@{cluster-name}.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"
                },
                "databaseName": "vectordb",
                "containerName": "azuredocs",
                "indexName": "azuredocindex",
                "embeddingDependency": {
                    "type": "DeploymentName",
                    "deploymentName": "{embedding deployment name}"
                },
                "fieldsMapping": {
                    "vectorFields": [
                        "contentvector"
                    ]
                }
            }
        }
    ]
}
'
Elasticsearch
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
{
  "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?"
    }
  ],
  "dataSources": [
    {
      "type": "Elasticsearch",
      "parameters": {
        "endpoint": "{search endpoint}",
        "indexName": "{index name}",
        "authentication": {
          "type": "KeyAndKeyId",
          "key": "{key}",
          "keyId": "{key id}"
        }
      }
    }
  ]
}
Azure Machine Learning
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "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?"
    }
  ],
  "dataSources": [
    {
      "type": "AzureMLIndex",
      "parameters": {
        "projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",
        "name": "my-project",
        "version": "5"
      }
    }
  ]
}
'
Pinecone
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "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?"
    }
  ],
  "dataSources": [
    {
      "type": "Pinecone",
      "parameters": {
        "authentication": {
          "type": "APIKey",
          "apiKey": "{api key}"
        },
        "environment": "{environment name}",
        "indexName": "{index name}",
        "embeddingDependency": {
          "type": "DeploymentName",
          "deploymentName": "{embedding deployment name}"
        },
        "fieldsMapping": {
          "titleField": "title",
          "urlField": "url",
          "filepathField": "filepath",
          "contentFields": [
            "content"
          ],
          "contentFieldsSeparator": "\n"
        }
      }
    }
  ]
}
'

範例回應

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "",
    "created": 1684304924,
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "messages": [
                {
                    "role": "tool",
                    "content": "{\"citations\": [{\"content\": \"\\nAzure AI services are cloud-based artificial intelligence (AI) services...\", \"id\": null, \"title\": \"What is Azure AI services\", \"filepath\": null, \"url\": null, \"metadata\": {\"chunking\": \"orignal document size=250. Scores=0.4314117431640625 and 1.72564697265625.Org Highlight count=4.\"}, \"chunk_id\": \"0\"}], \"intent\": \"[\\\"Learn about Azure AI services.\\\"]\"}",
                    "end_turn": false
                },
                {
                    "role": "assistant",
                    "content": " \nAzure AI services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. [doc1]. Azure Machine Learning is a cloud service for accelerating and managing the machine learning project lifecycle. [doc1].",
                    "end_turn": true
                }
            ]
        }
    ]
}
參數 類型 是必要的嗎? 預設 描述
messages 陣列 必要 null 以聊天格式產生聊天完成的訊息。
dataSources 陣列 必要 要用於 Azure OpenAI On Data 功能的數據源。
temperature 數值 選擇性 0 要使用的取樣溫度，介於 0 到 2 之間。 0.8 等較高的值會讓輸出更隨機，而 0.2 等較低值會使輸出更專注且具決定性。 我們通常建議改變這個 或 top_p ，但不是兩者。
top_p 數值 選擇性 1 核取樣是溫度取樣的替代方法，在此方法中，模型會考慮包含 top_p 機率質量的權杖結果。 因此，0.1 表示只考慮組成前 10% 機率質量的權杖。 我們通常建議改變這個或溫度，但不要同時改變這兩者。
stream boolean 選擇性 false 如果設定，則會傳送部分訊息差異，例如 ChatGPT。 令牌會在可用時以僅限數據伺服器傳送的事件傳送，且數據流會由訊息終止 "messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}]
stop 字串或陣列 選擇性 null 最多兩個序列，API 將停止產生進一步的令牌。
max_tokens 整數 選擇性 1000 所產生答案允許的令牌數目上限。 根據預設，模型可以傳回的標記數目為 4096 - prompt_tokens。

下列參數可以在 的dataSources欄位內使用parameters。

參數 類型 是必要的嗎? 預設 描述
type string 必要 null 要用於 Azure OpenAI On Data 功能的數據源。 針對 Azure AI 搜尋，值為 AzureCognitiveSearch。 針對適用於 MongoDB 的 Azure Cosmos DB 虛擬核心，值為 AzureCosmosDB。 針對 Elasticsearch，值為 Elasticsearch。 針對 Azure 機器學習，值為 AzureMLIndex。 對於 Pinecone，值為 Pinecone。
indexName string 必要 null 要使用的搜尋索引。
inScope boolean 選擇性 true 如果設定，此值會限制對地面數據內容的特定回應。
topNDocuments 數值 選擇性 5 指定用來產生回應的數據索引中評分最高的檔數目。 當您有簡短的檔或想要提供更多內容時，您可能會想要增加此值。 這是 Azure OpenAI Studio 中擷取的文件 參數。
semanticConfiguration string 選擇性 null 語意搜尋組態。 只有在 設定為 semantic 或vectorSemanticHybrid時才queryType需要 。
roleInformation string 選擇性 null 提供模型指示，說明其運作方式，以及產生回應時應參考的內容。 對應至 Azure OpenAI Studio 中的「系統訊息」。 如需詳細資訊，請參閱 使用您的數據 。 有 100 個令牌限制，其計入整體令牌限制。
filter string 選擇性 null 用於 限制敏感性檔存取的篩選模式
embeddingEndpoint string 選擇性 null Ada 內嵌模型部署的端點 URL，通常是 格式 https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2023-05-15。 搭配 參數使用 embeddingKey ，在專用網和私人端點之外進行 向量搜尋 。
embeddingKey string 選擇性 null Ada 內嵌模型部署的 API 金鑰。 使用 搭配 embeddingEndpoint ，在專用網和私人端點之外進行 向量搜尋 。
embeddingDeploymentName string 選擇性 null Ada 將模型部署名稱內嵌在相同的 Azure OpenAI 資源中。 使用 而非 embeddingEndpoint 和 embeddingKey 進行 向量搜尋。 只有在定義 和 embeddingKey 參數時embeddingEndpoint，才應該使用。 提供此參數時，Azure OpenAI On Your Data 會使用內部呼叫來評估 Ada 內嵌模型，而不是呼叫 Azure OpenAI 端點。 這可讓您在專用網和私人端點中使用向量搜尋。 不論是否定義此參數，計費都會維持不變。 可從 API 版本和更新版本2023-06-01-preview開始提供內嵌模型的區域。
strictness 數值 選擇性 3 設定臨界值，將文件分類為與您的查詢相關。 提高值表示相關性的臨界值較高，並篩選出較不相關的回應檔。 設定此值太高可能會導致模型因為可用的檔有限而無法產生回應。

Azure AI 搜尋參數

下列參數用於 Azure AI 搜尋。

參數 類型 是必要的嗎? 預設 描述
endpoint string 必要 null 僅限 Azure AI 搜尋服務。 數據源端點。
key string 必要 null 僅限 Azure AI 搜尋服務。 您服務的其中一個 Azure AI 搜尋系統管理金鑰。
queryType string 選擇性 simple 指出 Azure AI 搜尋所使用的查詢選項。 可用的類型：simple、、vectorsemantic、vectorSimpleHybrid、 。 vectorSemanticHybrid
fieldsMapping 字典 Azure AI 搜尋的選用專案。 null 定義您要在新增資料源時對應哪些 欄位 。

欄位內authentication會使用下列參數，可讓您在沒有公用網路存取的情況下使用 Azure OpenAI。

參數 類型 是必要的嗎? 預設 描述
type string 必要 null 驗證類型。
managedIdentityResourceId string 必要 null 要用於驗證的使用者指派受控識別資源標識碼。 
"authentication": {
  "type": "UserAssignedManagedIdentity",
  "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
},

欄位內 fieldsMapping 會使用下列參數。

參數 類型 是必要的嗎? 預設 描述
titleField string 選擇性 null 索引中的欄位，其中包含每個檔的原始標題。
urlField string 選擇性 null 索引中的欄位，其中包含每個檔的原始URL。
filepathField string 選擇性 null 索引中的欄位，其中包含每個檔的源檔名稱。
contentFields 字典 選擇性 null 索引中的欄位，其中包含每個檔案的主要文字內容。
contentFieldsSeparator string 選擇性 null 內容欄位的分隔符。 預設使用 \n 。 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n"
}

下列參數會在選擇性 embeddingDependency 參數內使用，其中包含以相同 Azure OpenAI 資源中內部內嵌模型部署名稱為基礎的向量化來源詳細數據。

參數 類型 是必要的嗎? 預設 描述
deploymentName string 選擇性 null 要使用的向量化來源類型。
type string 選擇性 null 內嵌模型部署名稱，位於相同的 Azure OpenAI 資源內。 這可讓您在沒有 Azure OpenAI API 金鑰和 Azure OpenAI 公用網路存取的情況下使用向量搜尋。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

適用於 MongoDB 的 Azure Cosmos DB 虛擬核心參數

下列參數用於適用於 MongoDB 虛擬核心的 Azure Cosmos DB。

參數 類型 是必要的嗎? 預設 描述
type （在 裡面 authentication發現） string 必要 null 僅限適用於 MongoDB 的 Azure Cosmos DB 虛擬核心。 要使用的驗證。 Azure Cosmos Mongo 虛擬核心，值為 ConnectionString
connectionString string 必要 null 僅限適用於 MongoDB 的 Azure Cosmos DB 虛擬核心。 要用於驗證 Azure Cosmos Mongo 虛擬核心帳戶的 連接字串。
databaseName string 必要 null 僅限適用於 MongoDB 的 Azure Cosmos DB 虛擬核心。 Azure Cosmos Mongo 虛擬核心資料庫名稱。
containerName string 必要 null 僅限適用於 MongoDB 的 Azure Cosmos DB 虛擬核心。 資料庫中的 Azure Cosmos Mongo 虛擬核心容器名稱。
type （在裡面embeddingDependencyType發現） string 必要 null 表示內嵌模型相依性。
deploymentName （在裡面embeddingDependencyType發現） string 必要 null 內嵌模型部署名稱。
fieldsMapping 字典 適用於 MongoDB 虛擬核心的 Azure Cosmos DB 必要專案。 null 索引數據行對應。 當您使用適用於 MongoDB 的 Azure Cosmos DB 虛擬核心時，此值 vectorFields 會指出儲存向量的欄位。

下列參數會在選擇性 embeddingDependency 參數內使用，其中包含以相同 Azure OpenAI 資源中內部內嵌模型部署名稱為基礎的向量化來源詳細數據。

參數 類型 是必要的嗎? 預設 描述
deploymentName string 選擇性 null 要使用的向量化來源類型。
type string 選擇性 null 內嵌模型部署名稱，位於相同的 Azure OpenAI 資源內。 這可讓您在沒有 Azure OpenAI API 金鑰和 Azure OpenAI 公用網路存取的情況下使用向量搜尋。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Elasticsearch 參數

下列參數用於 Elasticsearch。

參數 類型 是必要的嗎? 預設 描述
endpoint string 必要 null 聯機至 Elasticsearch 的端點。
indexName string 必要 null Elasticsearch 索引的名稱。
type （在 裡面 authentication發現） string 必要 null 要使用的驗證。 針對 Elasticsearch，值為 KeyAndKeyId。
key （在 裡面 authentication發現） string 必要 null 用來連線到 Elasticsearch 的金鑰。
keyId （在 裡面 authentication發現） string 必要 null 要使用的金鑰識別碼。 針對 Elasticsearch。

欄位內 fieldsMapping 會使用下列參數。

參數 類型 是必要的嗎? 預設 描述
titleField string 選擇性 null 索引中的欄位，其中包含每個檔的原始標題。
urlField string 選擇性 null 索引中的欄位，其中包含每個檔的原始URL。
filepathField string 選擇性 null 索引中的欄位，其中包含每個檔的源檔名稱。
contentFields 字典 選擇性 null 索引中的欄位，其中包含每個檔案的主要文字內容。
contentFieldsSeparator string 選擇性 null 內容欄位的分隔符。 預設使用 \n 。
vectorFields 字典 選擇性 null 代表向量數據的功能變數名稱 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n",
  "vectorFields": [
    "myVectorField"
  ]
}

下列參數會在選擇性 embeddingDependency 參數內使用，其中包含以相同 Azure OpenAI 資源中內部內嵌模型部署名稱為基礎的向量化來源詳細數據。

參數 類型 是必要的嗎? 預設 描述
deploymentName string 選擇性 null 要使用的向量化來源類型。
type string 選擇性 null 內嵌模型部署名稱，位於相同的 Azure OpenAI 資源內。 這可讓您在沒有 Azure OpenAI API 金鑰和 Azure OpenAI 公用網路存取的情況下使用向量搜尋。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Azure 機器學習 參數

下列參數用於 Azure 機器學習。

參數 類型 是必要的嗎? 預設 描述
projectResourceId string 必要 null 專案資源標識碼。
name string 必要 null Azure 機器學習 項目名稱的名稱。
version （在 裡面 authentication發現） string 必要 null Azure 機器學習 向量索引的版本。

下列參數會在選擇性 embeddingDependency 參數內使用，其中包含以相同 Azure OpenAI 資源中內部內嵌模型部署名稱為基礎的向量化來源詳細數據。

參數 類型 是必要的嗎? 預設 描述
deploymentName string 選擇性 null 要使用的向量化來源類型。
type string 選擇性 null 內嵌模型部署名稱，位於相同的 Azure OpenAI 資源內。 這可讓您在沒有 Azure OpenAI API 金鑰和 Azure OpenAI 公用網路存取的情況下使用向量搜尋。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Pinecone 參數

下列參數用於 Pinecone。

參數 類型 是必要的嗎? 預設 描述
type （在 裡面 authentication發現） string 必要 null 要使用的驗證。 對於 Pinecone，值為 APIKey。
apiKey （在 裡面 authentication發現） string 必要 null Pinecone 的 API 金鑰。
environment string 必要 null Pinecone 環境的名稱。
indexName string 必要 null Pinecone 索引的名稱。
embeddingDependency string 必要 null 向量搜尋的內嵌相依性。
type （在 裡面 embeddingDependency發現） string 必要 null 相依性的類型。 對於 Pinecone，值為 DeploymentName。
deploymentName （在 裡面 embeddingDependency發現） string 必要 null 部署的名稱。
titleField （在 裡面 fieldsMapping發現） string 必要 null 要當做標題使用的索引字段名稱。
urlField （在 裡面 fieldsMapping發現） string 必要 null 要當做 URL 使用的索引欄位名稱。
filepathField （在 裡面 fieldsMapping發現） string 必要 null 要當做檔案路徑使用的索引字段名稱。
contentFields （在 裡面 fieldsMapping發現） string 必要 null 應視為內容的索引欄位名稱。
vectorFields 字典 選擇性 null 代表向量數據的功能變數名稱
contentFieldsSeparator （在 裡面 fieldsMapping發現） string 必要 null 內容欄位的分隔符。 預設使用 \n 。

下列參數會在選擇性 embeddingDependency 參數內使用，其中包含以相同 Azure OpenAI 資源中內部內嵌模型部署名稱為基礎的向量化來源詳細數據。

參數 類型 是必要的嗎? 預設 描述
deploymentName string 選擇性 null 要使用的向量化來源類型。
type string 選擇性 null 內嵌模型部署名稱，位於相同的 Azure OpenAI 資源內。 這可讓您在沒有 Azure OpenAI API 金鑰和 Azure OpenAI 公用網路存取的情況下使用向量搜尋。 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

啟動擷取作業 （預覽）

提示

JOB_NAME您選擇的 將做為索引名稱。 請注意索引名稱的條件約束。

curl -i -X PUT https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/JOB_NAME?api-version=2023-10-01-preview \ 
-H "Content-Type: application/json" \ 
-H "api-key: YOUR_API_KEY" \ 
-H "searchServiceEndpoint: https://YOUR_AZURE_COGNITIVE_SEARCH_NAME.search.windows.net" \ 
-H "searchServiceAdminKey: YOUR_SEARCH_SERVICE_ADMIN_KEY" \ 
-H  "storageConnectionString: YOUR_STORAGE_CONNECTION_STRING" \ 
-H "storageContainer: YOUR_INPUT_CONTAINER" \ 
-d '{ "dataRefreshIntervalInMinutes": 10 }'

範例回應

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "running", 
    "warnings": [], 
    "progress": { 
        "stageProgress": [ 
            { 
                "name": "Preprocessing", 
                "totalItems": 100, 
                "processedItems": 100 
            }, 
            { 
                "name": "Indexing", 
                "totalItems": 350, 
                "processedItems": 40 
            } 
        ] 
    } 
}

標頭參數

參數 類型 是必要的嗎? 預設 描述
searchServiceEndpoint string 必要 null 搜尋資源的端點，其中會內嵌數據。
searchServiceAdminKey string 選擇性 null 如果提供，則會使用金鑰向 進行驗證 searchServiceEndpoint。 如果未提供，則會使用 Azure OpenAI 資源系統指派的身分識別。 在此情況下，系統指派的身分識別在搜尋資源上必須具有「搜尋服務參與者」角色指派。
storageConnectionString string 必要 null 輸入數據所在的記憶體帳戶 連接字串。 必須在 連接字串 中提供帳戶金鑰。 看起來應該像這樣 DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>
storageContainer string 必要 null 輸入數據所在的容器名稱。
embeddingEndpoint string 選擇性 null 如果您使用語意或僅關鍵詞搜尋，則不需要。 如果您使用向量、混合式或混合式 + 語意搜尋，則為必要專案
embeddingKey string 選擇性 null 內嵌端點的金鑰。 如果內嵌端點不是空的，則需要此專案。
url string 選擇性 null 如果 URL 不是 Null，則提供的 URL 會編目至提供的記憶體容器，然後據以內嵌。

主體參數

參數 類型 是必要的嗎? 預設 描述
dataRefreshIntervalInMinutes string 必要 0 以分鐘為單位的數據重新整理間隔。 如果您要在沒有排程的情況下執行單一擷取作業，請將此參數設定為 0。
completionAction string 選擇性 cleanUpAssets 作業完成時，擷取程式期間所建立的資產應該會發生什麼事。 有效值為 cleanUpAssets 或 keepAllAssets。 keepAllAssets 會將所有中繼資產留給有興趣檢閱中繼結果的使用者，這對偵錯資產很有説明。 cleanUpAssets 在作業完成之後移除資產。
chunkSize int 選擇性 1024 此數目會定義擷取流程所產生之每個區塊中的令牌數目上限。

清單擷取作業 （預覽）

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

範例回應

{ 
    "value": [ 
        { 
            "id": "test-1", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "succeeded", 
            "warnings": [] 
        }, 
        { 
            "id": "test-2", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "failed", 
            "error": { 
                "code": "BadRequest", 
                "message": "Could not execute skill because the Web Api request failed." 
            }, 
            "warnings": [] 
        } 
    ] 
}

取得擷取作業的狀態 （預覽）

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/YOUR_JOB_NAME?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

範例回應本文

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "succeeded", 
    "warnings": [] 
}

影像產生

要求產生的映像 （DALL-E 3）

從文字 標題 產生和擷取一批影像。

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
deployment-id string 必要 DALL-E 3 模型部署的名稱，例如 MyDalle3。 您必須先部署 DALL-E 3 模型，才能進行呼叫。
api-version string 必要 用於此作業的 API 版本。 這會遵循 YYYY-MM-DD 格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
prompt string 必要 所需影像的文字描述。 最大長度為 4000 個字元。
n 整數 選擇性 1 要產生的影像數目。 僅 n=1 支援 DALL-E 3。
size string 選擇性 1024x1024 產生的影像大小。 必須是、 1024x1024或 1024x1792的1792x1024其中一個。
quality string 選擇性 standard 產生的影像品質。 必須是 hd 或 standard。
response_format string 選擇性 url 傳回所產生影像的格式必須是 url （指向影像的 URL） 或 b64_json （JSON 格式的基底 64 位元組程式代碼）。
style string 選擇性 vivid 產生的影像樣式。 必須是 natural 或 vivid （對於超現實/戲劇性的影像）。
user string 選擇性 代表使用者的唯一標識符，可協助監視和偵測濫用行為。

範例要求

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

範例回應

此作業會傳 202 回狀態代碼和 GenerateImagesResponse JSON 物件，其中包含作業的標識碼和狀態。

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

要求產生的影像 （DALL-E 2 預覽版）

從文字 標題產生一批影像。

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
api-version string 必要 用於此作業的 API 版本。 這會遵循 YYYY-MM-DD 格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
prompt string 必要 所需影像的文字描述。 最大長度為 1000 個字元。
n 整數 選擇性 1 要產生的影像數目。 必須介於 1 到 5 之間。
size string 選擇性 1024x1024 產生的影像大小。 必須是、 512x512或 1024x1024的256x256其中一個。

範例要求

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

範例回應

此作業會傳 202 回狀態代碼和 GenerateImagesResponse JSON 物件，其中包含作業的標識碼和狀態。

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

取得產生的影像結果 （DALL-E 2 預覽版）

使用此 API 來擷取映像產生作業的結果。 映射產生目前僅適用於 api-version=2023-06-01-preview。

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
operation-id string 必要 識別原始映像產生要求的 GUID。

支援的版本

範例要求

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

範例回應

成功時，作業會 200 傳回狀態代碼和 OperationResponse JSON 物件。 欄位status可以是 （工作已排入佇列，但尚未啟動）、、"running"、 "canceled""succeeded"、（工作已逾時）、"failed"或 "deleted"。"notRunning" 狀態 succeeded 表示產生的映像可在指定的 URL 下載。 如果產生多個影像，則會在 result.data 欄位中傳回其URL。

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

從伺服器移除產生的映像 （DALL-E 2 預覽版）

您可以使用要求傳回的作業標識碼，從 Azure 伺服器刪除對應的映像。 根據預設，產生的映像會在 24 小時後自動刪除，但您可以稍早觸發刪除。

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 Azure OpenAI 資源的名稱。
operation-id string 必要 識別原始映像產生要求的 GUID。

支援的版本

範例要求

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

回應

如果成功，作業會傳 204 回狀態代碼。 只有在作業處於結束狀態時，此 API 才會成功（而非 running）。

語音轉換文字

您可以在 Azure OpenAI 服務中使用 Whisper 模型進行語音轉譯或語音翻譯。 如需使用 Whisper 模型的詳細資訊，請參閱 快速入門 和 Whisper 模型概觀。

要求語音轉譯文字

轉譯音訊檔案。

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 您 Azure OpenAI 資源的名稱。
deployment-id string 必要 您的 Whisper 模型部署名稱，例如 MyWhisperDeployment。 您必須先部署 Whisper 模型，才能撥打電話。
api-version string 必要 用於此作業的 API 版本。 此值遵循YYYY-MM-DD格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
file 檔案 Yes N/A 要以下列其中一種格式flac轉譯的音訊檔案物件（不是檔名）：、mp3、、mp4、m4ampgampegogg、 wav或 。webm

Azure OpenAI 服務中 Whisper 模型的檔案大小限制為 25 MB。 如果您需要轉譯大於 25 MB 的檔案，請將它分成區塊。 或者，您可以使用 Azure AI 語音 批次轉譯 API。

您可以從 GitHub 的 Azure AI 語音 SDK 存放庫取得範例音訊檔案。
language string No Null 輸入音訊的語言，例如 fr。 以 ISO-639-1 格式提供輸入語言可改善精確度和延遲。

如需支援的語言清單，請參閱 OpenAI 檔。
prompt string No Null 用來引導模型樣式或繼續上一個音訊區段的選擇性文字。 提示應該符合音頻語言。

如需提示的詳細資訊，包括範例使用案例，請參閱 OpenAI 檔。
response_format string No json 其中一個選項中的文字記錄輸出格式：json、text、srt、verbose_json 或 vtt。

預設值為 json。
temperature 數值 No 0 取樣溫度，介於 0 到 1 之間。

如 0.8 等較高的值會讓輸出更隨機，而 0.2 等較低的值則更專注且具決定性。 如果設定為 0，模型會使用 對數機率 自動增加溫度，直到達到特定閾值為止。

預設值為 0。

範例要求

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

範例回應

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

要求語音轉換文字翻譯

將另一種語言的音訊檔案翻譯成英文。 如需支援的語言清單，請參閱 OpenAI 檔。

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 您 Azure OpenAI 資源的名稱。
deployment-id string 必要 您的 Whisper 模型部署名稱，例如 MyWhisperDeployment。 您必須先部署 Whisper 模型，才能撥打電話。
api-version string 必要 用於此作業的 API 版本。 此值遵循YYYY-MM-DD格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
file 檔案 Yes N/A 要以下列其中一種格式轉譯的音訊檔案物件（非檔名）：flac、mp3、mp4、mpeg、mpga、m4a、ogg、wav 或 webm。

Azure OpenAI Whisper 模型的檔案大小限制為 25 MB。 如果您需要轉譯大於 25 MB 的檔案，請將它分成區塊。

您可以從 GitHub 的 Azure AI 語音 SDK 存放庫下載範例音訊檔案。
prompt string No Null 用來引導模型樣式或繼續上一個音訊區段的選擇性文字。 提示應該符合音頻語言。

如需提示的詳細資訊，包括範例使用案例，請參閱 OpenAI 檔。
response_format string No json 其中一個選項中的文字記錄輸出格式：json、text、srt、verbose_json 或 vtt。

預設值為 json。
temperature 數值 No 0 取樣溫度，介於 0 到 1 之間。

如 0.8 等較高的值會讓輸出更隨機，而 0.2 等較低的值則更專注且具決定性。 如果設定為 0，模型會使用 對數機率 自動增加溫度，直到達到特定閾值為止。

預設值為 0。

範例要求

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

範例回應

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

文字轉換語音

將文字合成至語音。

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

路徑參數

參數 類型 是必要的嗎？ 描述
your-resource-name string 必要 您 Azure OpenAI 資源的名稱。
deployment-id string 必要 文字到語音轉換模型部署的名稱，例如 MyTextToSpeechDeployment。 您必須先將文字部署到語音模型（例如 tts-1 或 tts-1-hd），才能進行通話。
api-version string 必要 用於此作業的 API 版本。 此值遵循YYYY-MM-DD格式。

支援的版本

要求本文

參數 類型 是必要的嗎? 預設 描述
model string Yes N/A 其中一個可用的 TTS 模型： tts-1 或 tts-1-hd
input string Yes N/A 要為其產生音訊的文字。 最大長度為 4096 個字元。 以您選擇的語言指定輸入文字。1
voice string Yes N/A 產生音訊時要使用的語音。 支援的語音為alloy、、echo、fableonyx、、 nova和 shimmer。 OpenAI 文字至語音指南提供語音預覽。

1 語音轉換模型通常支援與 Whisper 模型相同的語言。 如需支援的語言清單，請參閱 OpenAI 檔。

範例要求

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

範例回應

語音會以先前要求的音訊檔案的形式傳回。

管理 API

Azure OpenAI 會部署為 Azure AI 服務的一部分。 所有 Azure AI 服務都依賴同一組管理 API 來建立、更新和刪除作業。 管理 API 也用於在 Azure OpenAI 資源內部署模型。

管理 API 參考檔

下一步

瞭解 模型，以及使用 REST API 微調。 深入了解驅動 Azure OpenAI 的基礎模型。