Azure OpenAI image and audio REST API reference （2024-10-21）

本文記錄了 Azure OpenAI 2024-10-21 在 GA 版本中影像生成與音訊（語音）資料平面推論 REST API 操作。 關於聊天完成、嵌入、完成及所有其他操作，請參閱官方 Azure OpenAI REST API 參考資料。

API 規格

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

  • 控制平面
  • 資料平面 - 著述
  • 資料平面 - 推論

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

Important

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

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

驗證

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

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

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

REST API 版本管理

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

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

資料平面推論

本文其餘部分將介紹 Azure OpenAI 資料平面推論規範 2024-10-21GA 版本中的影像與音訊操作。

關於預覽影像與音訊操作，請參閱 預覽影像與音訊 REST API 參考資料。

轉錄 - 建立

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

將音訊轉錄成輸入語言。

URI 參數

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

有關支援模型的資訊，請參見 [/azure/ai-foundry/openai/concepts/models#audio-models]。
API版本 查詢 Yes 字串 API 版本

請求標頭

Name Required 類型 Description
API金鑰 沒錯 字串 在此輸入 Azure OpenAI API 金鑰

請求主體

Content-Type：multipart/form-data

Name 類型 Description Required 預設值
檔案 字串 要轉錄的音訊檔案物件。 Yes
提示 字串 可選文字用來引導模型風格或延續先前的音訊片段。 提示詞應該與音頻語言相符。 No
回應格式 audioResponseFormat 定義輸出格式。 No
溫度 number 取樣溫度介於0到1之間。 像 0.8 這樣的較高值會讓輸出更隨機，而像 0.2 這樣的低值則會讓輸出更聚焦且確定性強。 若設為 0，模型會利用對數機率自動升溫，直到達到特定閾值。 No 0
語言 字串 輸入音訊的語言。 以 ISO-639-1 格式提供輸入語言將提升準確度與延遲。 No

回應

狀態代碼： 200

描述：確定

內容類型 Type 說明
application/json audioResponse 或 audioVerboseResponse
文字/平文 字串 以輸出格式轉錄文字（當response_format為文字、vtt 或 srt 時）。

Examples

範例

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

回應：狀態代碼：200

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

範例

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-10-21

"---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=2024-10-21

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

URI 參數

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

有關支援模型的資訊，請參見 [/azure/ai-foundry/openai/concepts/models#audio-models]。
API版本 查詢 Yes 字串 API 版本

請求標頭

Name Required 類型 Description
API金鑰 沒錯 字串 在此輸入 Azure OpenAI API 金鑰

請求主體

Content-Type：multipart/form-data

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

回應

狀態代碼： 200

描述：確定

內容類型 Type 說明
application/json audioResponse 或 audioVerboseResponse
文字/平文 字串 以輸出格式轉錄文字（當response_format為文字、vtt 或 srt 時）。

Examples

範例

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-10-21

"---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"
  }
}

範例

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

POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-10-21

"---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}/images/generations?api-version=2024-10-21

在特定 dall-e 模型部署時，從文字說明產生一批圖片

URI 參數

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

請求標頭

Name Required 類型 Description
API金鑰 沒錯 字串 在此輸入 Azure OpenAI API 金鑰

請求主體

Content-Type：application/json

Name 類型 Description Required 預設值
提示 字串 這是想要圖片的文字描述。 最大長度為4,000字元。 Yes
n 整數 要產生的影像數量。 No 1
size imageSize 產生的影像大小。 No 1024x1024
回應格式 imagesResponseFormat 產生影像回傳的格式。 No 網址
使用者 字串 一個代表終端使用者的獨特識別碼，有助於監控和偵測濫用行為。 No
品質 imageQuality 所產生的影像品質。 No 標準
樣式 imageStyle 產生的圖片風格。 No vivid

回應

狀態代碼： 200

描述：確定

內容類型 Type 說明
application/json generateImagesResponse

狀態代碼： 預設

說明：發生錯誤。

內容類型 Type 說明
application/json dalleErrorResponse

Examples

範例

在提示下創作圖片。

POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2024-10-21

{
 "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
          }
        },
        "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
          }
        }
      }
    ]
  }
}

組成部分

關於聊天、補全、嵌入及其他文字操作所使用的結構定義，請參見 Azure OpenAI REST API 參考文獻。 以下結構支援本頁的影像與音訊操作。

innerErrorCode

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

說明：內部錯誤物件的錯誤代碼。

類型：字串

預設：

列舉名稱：InnerErrorCode

枚舉價值：

價值 Description
ResponsibleAIPolicyViolation 這個提示違反了其中一條內容過濾規則。

dalleErrorResponse

Name 類型 Description Required 預設值
錯誤 dalleError No

dalleError

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

dalleInnerError

內部錯誤加上額外細節。

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

contentFilterSeverityResult

Name 類型 Description Required 預設值
過濾 boolean Yes
嚴重程度 字串 No

contentFilterDetectedResult

Name 類型 Description Required 預設值
過濾 boolean Yes
detected boolean No

dalleFilterResults

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

Name 類型 Description Required 預設值
性方面 內容過濾嚴重程度結果 No
暴力 內容過濾嚴重程度結果 No
仇恨 內容過濾嚴重程度結果 No
self_harm 內容過濾嚴重程度結果 No
髒話 內容過濾檢測結果 No
越獄 內容過濾檢測結果 No

音頻回應

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

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

audioVerboseResponse

翻譯或轉錄反應response_format verbose_json

Name 類型 Description Required 預設值
收發簡訊 字串 翻譯或轉錄文本。 Yes
工作 字串 音訊任務類型。 No
語言 字串 Language. No
duration number 持續時間。 No
單元 陣列 No

audioResponseFormat

定義輸出格式。

說明：定義輸出格式。

類型：字串

預設：

枚舉價值：

  • JSON
  • 收發簡訊
  • srt
  • verbose_json
  • vtt

imageQuality

所產生的影像品質。

描述：將產生的影像品質。

類型：字串

預設：標準

枚舉名稱：品質

枚舉價值：

價值 Description
標準 標準品質會產生標準品質的影像。
hd 高清畫質能創造出細節更細緻且整體一致性更高的影像。

imagesResponseFormat

產生影像回傳的格式。

說明：產生影像回傳的格式。

類型：字串

預設：URL

列舉名稱：ImagesResponseFormat

枚舉價值：

價值 Description
網址 提供暫時下載生成影像的網址。
b64_json 產生的影像以 base64 編碼字串回傳。

imageSize

產生的影像大小。

描述：產生影像的大小。

類型：字串

預設：1024x1024

列舉名稱：大小

枚舉價值：

價值 Description
1792x1024 產生影像的期望尺寸為 1792x1024 像素。
1024x1792 產生影像的期望尺寸為 1024x1792 像素。
1024x1024 產生影像的期望尺寸為 1024x1024 像素。

imageStyle

產生的圖片風格。

說明：生成圖片的風格。

類型：字串

預設：鮮明

枚舉名稱：風格

枚舉價值：

價值 Description
vivid Vivid 創造出超寫實且戲劇化的影像。
natural 自然的影像更自然，且不那麼過寫實。

generateImagesResponse

Name 類型 Description Required 預設值
創造 整數 Unix 的時間戳記是該操作建立的時刻。 Yes
資料 陣列 操作成功時，該操作的結果資料 Yes

下一步

學習 模型與 REST API 的微調。 深入了解驅動 OpenAI 的底層模型Azure。

  • Last updated on