Iteration Operations - Create Iteration

服務:: Azure AI Services

API 版本:: 2025-05-20

建立反覆專案。

PUT {endpoint}/videotranslation/translations/{translationId}/iterations/{iterationId}?api-version=2025-05-20

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string	支援的認知服務端點（通訊協定和主機名，例如：https://eastus.api.cognitive.microsoft.com）。
iterationId	path	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	迭代識別碼
translationId	path	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	翻譯資源標識碼。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。

要求標頭

名稱	必要	類型	Description
Operation-Id	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	作業標識碼。

要求本文

名稱	必要	類型	Description
input	True	IterationInput	反覆項目輸入。
description		string	反覆專案描述

回應

名稱	類型	Description
200 OK	Iteration	要求已成功。標題 Operation-Location: string
201 Created	Iteration	要求已成功，因此已建立新的資源。標題 Operation-Location: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	未預期的錯誤回應。標題 x-ms-error-code: string

名稱

類型

Description

200 OK

Iteration

要求已成功。

標題

Operation-Location: string

201 Created

Iteration

要求已成功，因此已建立新的資源。

標題

Operation-Location: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

未預期的錯誤回應。

標題

x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

在這裡提供您的語音資源金鑰。

類型: apiKey
位於: header

AADToken

這些是 Microsoft身分識別平臺流程。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
https://cognitiveservices.azure.com/.default

範例

Create Iteration

範例要求

HTTP

PUT {endpoint}/videotranslation/translations/TranslateMyZhCNVideo/iterations/TranslateMyZhCNVideo-ContentEditing-2?api-version=2025-05-20


{
  "description": "Fix segment duration issue and update subtitle max char.",
  "input": {
    "enableEmotionalPlatformVoice": "Auto",
    "speakerCount": 3,
    "subtitleMaxCharCountPerSegment": 60,
    "enableVideoSpeedAdjustment": true,
    "exportTargetLocaleAdvancedSubtitleFile": true,
    "enableOcrCorrectionFromSubtitle": true,
    "subtitlePrimaryColor": "ffffff",
    "webvttFile": {
      "url": "https://xxx.blob.core.windows.net/container1/myvtt.vtt?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
      "kind": "MetadataJson"
    }
  }
}

範例回覆

狀態碼:: 200

Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo-ContentEditing-2?api-version=2024-02-01-preview
Operation-Id: TranslateMyZhCNVideo-ContentEditing-1

{
  "id": "TranslateMyZhCNVideo-ContentEditing-2",
  "description": "Fix segment duration issue and update subtitle max char.",
  "status": "NotStarted",
  "createdDateTime": "2023-04-10T05:30:00.000Z",
  "lastActionDateTime": "2023-04-10T05:15:30.000Z",
  "input": {
    "speakerCount": 3,
    "subtitleMaxCharCountPerSegment": 60,
    "enableVideoSpeedAdjustment": true,
    "exportTargetLocaleAdvancedSubtitleFile": true,
    "enableOcrCorrectionFromSubtitle": true,
    "subtitlePrimaryColor": "ffffff",
    "webvttFile": {
      "url": "https://xxx.blob.core.windows.net/container1/myvtt.vtt?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
      "kind": "MetadataJson"
    }
  }
}

狀態碼:: 201

Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo-ContentEditing-2?api-version=2024-02-01-preview
Operation-Id: TranslateMyZhCNVideo-ContentEditing-1

{
  "id": "TranslateMyZhCNVideo-ContentEditing-2",
  "description": "Fix segment duration issue and update subtitle max char.",
  "status": "NotStarted",
  "createdDateTime": "2023-04-10T05:30:00.000Z",
  "lastActionDateTime": "2023-04-10T05:15:30.000Z",
  "input": {
    "speakerCount": 3,
    "subtitleMaxCharCountPerSegment": 60,
    "enableVideoSpeedAdjustment": true,
    "exportTargetLocaleAdvancedSubtitleFile": true,
    "enableOcrCorrectionFromSubtitle": true,
    "subtitlePrimaryColor": "ffffff",
    "webvttFile": {
      "url": "https://xxx.blob.core.windows.net/container1/myvtt.vtt?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
      "kind": "MetadataJson"
    }
  }
}

定義

名稱	Description
Azure.Core.Foundations.Error	error 物件。
Azure.Core.Foundations.ErrorResponse	包含錯誤詳細數據的回應。
Azure.Core.Foundations.InnerError	物件，包含有關錯誤的更特定資訊。根據Microsoft一個 API 指導方針 - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors。
EnableEmotionalPlatformVoice	啟用情感平台語音類型。
Iteration	執行一個反覆專案，將一個影片檔案從來源地區設定轉譯為目標地區設定，Webvtt 進行內容編輯是選擇性的，用於要求參數。
IterationInput	反覆項目輸入。
IterationResult	反覆項目結果。
Status	工作狀態。
WebvttFile	翻譯 Webvtt 檔案。
WebvttFileKind	Webvtt 檔案種類。

Azure.Core.Foundations.Error

Object

error 物件。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
details	Azure.Core.Foundations.Error[]	導致此錯誤之特定錯誤的詳細數據陣列。
innererror	Azure.Core.Foundations.InnerError	物件，包含與目前對象有關錯誤更具體的資訊。
message	string	錯誤的人類可讀取表示法。
target	string	錯誤的目標。

Azure.Core.Foundations.ErrorResponse

Object

包含錯誤詳細數據的回應。

名稱	類型	Description
error	Azure.Core.Foundations.Error	error 物件。

Azure.Core.Foundations.InnerError

Object

物件，包含有關錯誤的更特定資訊。根據Microsoft一個 API 指導方針 - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
innererror	Azure.Core.Foundations.InnerError	內部錯誤。

EnableEmotionalPlatformVoice

列舉型別

啟用情感平台語音類型。

值	Description
Auto	讓 API 決定是否為目標區域設置啟用情感語音。
Disable	禁用目標區域設置的平台語音情感。
Enable	如果目標區域設置存在語音支援的情感，則強制啟用情感語音。

Iteration

Object

執行一個反覆專案，將一個影片檔案從來源地區設定轉譯為目標地區設定，Webvtt 進行內容編輯是選擇性的，用於要求參數。

名稱	類型	Description
createdDateTime	string (date-time)	物件建立時的時間戳。時間戳會編碼為 ISO 8601 日期和時間格式（“YYYY-MM-DDThh：mm：ssZ”，請參閱 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations）。
description	string	反覆專案描述
failureReason	string	反覆項目失敗原因
id	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	迭代識別碼
input	IterationInput	反覆項目輸入。
lastActionDateTime	string (date-time)	輸入目前狀態時的時間戳。時間戳會編碼為 ISO 8601 日期和時間格式（“YYYY-MM-DDThh：mm：ssZ”，請參閱 https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations）。
result	IterationResult	反覆項目結果。
status	Status	迭代狀態

IterationInput

Object

反覆項目輸入。

名稱	類型	Description
enableEmotionalPlatformVoice	EnableEmotionalPlatformVoice	此參數指定是否為平台語音啟用 emotion。默認情況下，伺服器根據目標區域設置確定是否應用情感以優化品質。如果不指定，API 會自動決定是否在服務端開啟情感表達。
enableOcrCorrectionFromSubtitle	boolean	指示是否允許 API 使用原始影片檔中的字幕更正語音辨識（SR）結果。通過利用現有的字幕，API 可以提高轉錄文本的準確性，確保最終輸出更加精確可靠，如果未指定，翻譯不會對 OCR 字幕進行更正。
enableVideoSpeedAdjustment	boolean	此參數允許調整視頻播放速度，以確保更好地與翻譯后的音訊保持一致。啟用后，API 可以減慢或加快視頻速度以匹配翻譯音訊的時間，從而提供更同步和無縫的觀看體驗，如果未指定，則不會調整視頻速度。
exportSubtitleInVideo	boolean	匯出視頻中的字幕，如果未指定，它將繼承在翻譯創建的輸入中定義的值。
exportTargetLocaleAdvancedSubtitleFile	boolean	啟用此參數后，允許 API 以 Advanced SubStation Alpha 格式導出字幕。字幕檔可以指定字體樣式和顏色，這有助於解決某些目標區域設置（如阿拉伯文（Ar）、日語（Ja）、朝鮮語（Ko）和中文（Ch））中的字元顯示問題。通過使用此參數，您可以確保字幕在視覺上具有吸引力，並在不同的語言和區域之間正確呈現，如果未指定，則反覆運算回應將不包含高級字幕。
speakerCount	integer (int32)	視頻中的說話人數量（如果未指定），它將繼承在翻譯創建的輸入中定義的值。
subtitleFontSize	integer (int32)	此參數指定視頻翻譯輸出中字幕的字體大小，介於 5 到 30 之間，如果未指定，它將使用與語言相關的預設值。
subtitleMaxCharCountPerSegment	integer (int32)	每個句段的字幕最大顯示字元數，如果未指定，它將繼承在翻譯創建的輸入中定義的值。
subtitleOutlineColor	string minLength: 6 maxLength: 9 pattern: ^#?(?:[0-9A-Fa-f]{6}\|[0-9A-Fa-f]{8})$	此參數指定視頻翻譯輸出中字幕的輪廓顏色。該值應以、 # 或 # 格式提供，其中表示顏色的紅色分量，表示綠色分量，表示藍色分量，表示 alpha 分量。例如，EBA205 或 #EBA205 會將字幕顏色設置為特定的黃色陰影。此參數允許自定義字幕外觀以增強可讀性和視覺吸引力，如果未指定，它將使用預設的黑色。
subtitlePrimaryColor	string minLength: 6 maxLength: 9 pattern: ^#?(?:[0-9A-Fa-f]{6}\|[0-9A-Fa-f]{8})$	此參數指定視頻翻譯輸出中字幕的主色。該值應以、 # 或 # 格式提供，其中表示顏色的紅色分量，表示綠色分量，表示藍色分量，表示 alpha 分量。例如，EBA205 或 #EBA205 會將字幕顏色設置為特定的黃色陰影。此參數允許自定義字幕外觀以增強可讀性和視覺吸引力，如果未指定，它將使用預設的白色。
ttsCustomLexiconFileIdInAudioContentCreation	string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$	使用 TTS 自定義詞典進行語音合成翻譯。使用 ttsCustomLexiconFileUrl 或 ttsCustomLexiconFileIdInAudioContentCreation 提供自定義詞典檔。這些參數是互斥的，只需要其中一個參數。如果同時提供兩者，則請求將被視為無效。
ttsCustomLexiconFileUrl	string (uri)	使用 TTS 自定義詞典進行語音合成翻譯。使用 ttsCustomLexiconFileUrl 或 ttsCustomLexiconFileIdInAudioContentCreation 提供自定義詞典檔。這些參數是互斥的，只需要其中一個參數。如果同時提供兩者，則請求將被視為無效。
webvttFile	WebvttFile	Webvtt 檔案進行內容編輯，這是翻譯的第二個反覆專案建立要求所需的參數。

IterationResult

Object

反覆項目結果。

名稱	類型	Description
metadataJsonWebvttFileUrl	string (uri)	元數據 json webvtt 檔案 URL。
reportFileUrl	string (uri)	報告檔案 URL。
sourceLocaleSubtitleWebvttFileUrl	string (uri)	來源地區設定字幕檔案 URL。
targetLocaleAdvancedSubtitleFileUrl	string (uri)	此屬性提供目標區域設置 Advanced SubStation Alpha （ASS）字幕檔的 URL。只有在反覆運算創建期間將 exportTargetLocaleAdvancedSubtitleFile 設置為 true 時，才會填充它;否則，此屬性將不會包含在回應中。
targetLocaleSubtitleWebvttFileUrl	string (uri)	目標地區設定字幕檔案 URL。
translatedAudioFileUrl	string (uri)	已翻譯的音訊檔 URL。
translatedVideoFileUrl	string (uri)	翻譯的視訊檔案 URL。

Status

列舉型別

工作狀態。

值	Description
Canceled	已取消狀態
Failed	執行失敗狀態
NotStarted	未啟動狀態
Running	執行狀態
Succeeded	執行成功狀態

WebvttFile

Object

翻譯 Webvtt 檔案。

名稱	類型	Description
kind	WebvttFileKind	翻譯 Webvtt 檔案類型。
url	string (uri)	翻譯 Webvtt 檔案 URL。

WebvttFileKind

列舉型別

Webvtt 檔案種類。

值	Description
MetadataJson	目標地區設定元數據 JSON webvtt 檔案
SourceLocaleSubtitle	來源地區設定純文本字幕 webvtt 檔案
TargetLocaleSubtitle	目標地區設定純文本字幕 webvtt 檔案

共用方式為

Iteration Operations - Create Iteration

URI 參數

要求標頭

要求本文

回應

安全性

Ocp-Apim-Subscription-Key

AADToken

範圍

範例

Create Iteration

範例要求

範例回覆

定義

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

EnableEmotionalPlatformVoice

Iteration

IterationInput

IterationResult

Status

WebvttFile

WebvttFileKind