Translation Operations - Create Translation

Создаёт перевод.

PUT {endpoint}/videotranslation/translations/{translationId}?api-version=2026-03-01

Параметры URI

Имя В Обязательно Тип Описание
endpoint
path True

string

Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например: https://eastus.api.cognitive.microsoft.com).

translationId
path True

string

minLength: 3
maxLength: 64
pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$

ID переводческого ресурса.

api-version
query True

string

minLength: 1

Версия API, используемая для данной операции.

Заголовок запроса

Имя Обязательно Тип Описание
Operation-Id True

string

minLength: 3
maxLength: 64
pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$

Идентификатор операции.

Текст запроса

Имя Обязательно Тип Описание
input True

TranslationInput

Перевод.

description

string

Описание перевода.

displayName

string

Перевод отображает имя.

firstIterationInput

IterationInput

Вход первой итерации для перевода, это свойство используется только при верности autoCreateFirstIteration.

Ответы

Имя Тип Описание
200 OK

Translation

Запрос выполнен успешно.

Заголовки

Operation-Location: string

201 Created

Translation

Запрос успешно выполнен, и в результате был создан новый ресурс.

Заголовки

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

Области

Имя Описание
https://cognitiveservices.azure.com/.default

Примеры

Create Translation

Образец запроса

PUT {endpoint}/videotranslation/translations/TranslateMyZhCNVideo?api-version=2026-03-01


{
  "displayName": "hello.mp4",
  "description": "Translate video from en-US to zh-CN.",
  "input": {
    "sourceLocale": "en-US",
    "targetLocale": "zh-CN",
    "voiceKind": "PlatformVoice",
    "enableLipSync": true,
    "videoFileUrl": "https://mystorage.blob.core.windows.net/container1/video.mp4?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
    "autoCreateFirstIteration": true
  },
  "firstIterationInput": {
    "speakerCount": 3,
    "subtitleMaxCharCountPerSegment": 80,
    "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"
    }
  }
}

Пример ответа

Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo?api-version=2026-03-01
Operation-Id: Create-TranslateMyZhCNVideo
{
  "id": "TranslateMyZhCNVideo",
  "displayName": "hello.mp4",
  "description": "Translate video from en-US to zh-CN.",
  "input": {
    "sourceLocale": "en-US",
    "targetLocale": "zh-CN",
    "voiceKind": "PlatformVoice",
    "videoFileUrl": "https://mystorage.blob.core.windows.net/container1/video.mp4?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
    "autoCreateFirstIteration": true
  },
  "createdDateTime": "2023-04-01T05:30:00.000Z",
  "expiresDateTime": "2023-04-03T05:30:00.000Z",
  "latestIteration": {
    "id": "Initial",
    "status": "NotStarted",
    "input": {
      "speakerCount": 3,
      "subtitleMaxCharCountPerSegment": 80,
      "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"
      }
    }
  },
  "latestSucceededIteration": {
    "id": "Initial",
    "status": "Succeeded",
    "input": {
      "speakerCount": 3,
      "subtitleMaxCharCountPerSegment": 80,
      "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"
      }
    }
  }
}
Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo?api-version=2026-03-01
Operation-Id: Create-TranslateMyZhCNVideo
{
  "id": "TranslateMyZhCNVideo",
  "description": "Translate video from en-US to zh-CN.",
  "input": {
    "sourceLocale": "en-US",
    "targetLocale": "zh-CN",
    "voiceKind": "PlatformVoice",
    "videoFileUrl": "https://mystorage.blob.core.windows.net/container1/video.mp4?sv=2023-01-03&st=2024-05-20T08%3A27%3A15Z&se=2024-05-21T08%3A27%3A15Z&sr=b&sp=r&sig=xxx",
    "autoCreateFirstIteration": true
  },
  "createdDateTime": "2023-04-01T05:30:00.000Z",
  "expiresDateTime": "2023-04-03T05:30:00.000Z",
  "latestIteration": {
    "id": "Initial",
    "status": "NotStarted",
    "input": {
      "speakerCount": 3,
      "subtitleMaxCharCountPerSegment": 80,
      "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"
      }
    }
  },
  "latestSucceededIteration": {
    "id": "Initial",
    "status": "Succeeded",
    "input": {
      "speakerCount": 3,
      "subtitleMaxCharCountPerSegment": 80,
      "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"
      }
    }
  }
}

Определения

Имя Описание
Azure.Core.Foundations.Error

Объект ошибки.

Azure.Core.Foundations.ErrorResponse

Ответ, содержащий сведения об ошибке.

Azure.Core.Foundations.InnerError

Объект, содержащий более конкретные сведения об ошибке. В соответствии с рекомендациями по Azure REST API — https://aka.ms/AzureRestApiGuidelines#handling-errors.

EnableEmotionalPlatformVoice

Включите эмоциональную платформу голоса.

InputFileSourceKind

Тип входного источника для входных видео, аудио или webvtt файлов.

Iteration

Сделайте одну итерацию, чтобы перевести один видеофайл из исходного места в целевой локал, webvtt для редактирования контента опцион для запроса параметра.

IterationInput

Ввод итерации.

IterationResult

Результат итерации.

Status

Статус задачи.

Translation

Создайте ресурс перевода для размещения итераций перевода одного видеофайла из исходного места в целевой локал.

TranslationInput

Перевод.

VoiceKind

Голос TTS доброжелательный.

WebvttFile

Перевод webvtt файла.

WebvttFileKind

Вид файла Webvtt.

Azure.Core.Foundations.Error

Объект ошибки.

Имя Тип Описание
code

string

Один из определяемых сервером кодов ошибок.

details

Azure.Core.Foundations.Error[]

Массив сведений об определенных ошибках, которые привели к этой сообщаемой ошибке.

innererror

Azure.Core.Foundations.InnerError

Объект, содержащий более конкретные сведения, чем текущий объект об ошибке.

message

string

Читаемое пользователем представление ошибки.

target

string

Целевой объект ошибки.

Azure.Core.Foundations.ErrorResponse

Ответ, содержащий сведения об ошибке.

Имя Тип Описание
error

Azure.Core.Foundations.Error

Объект ошибки.

Azure.Core.Foundations.InnerError

Объект, содержащий более конкретные сведения об ошибке. В соответствии с рекомендациями по Azure REST API — https://aka.ms/AzureRestApiGuidelines#handling-errors.

Имя Тип Описание
code

string

Один из определяемых сервером кодов ошибок.

innererror

Azure.Core.Foundations.InnerError

Внутренняя ошибка.

EnableEmotionalPlatformVoice

Включите эмоциональную платформу голоса.

Значение Описание
Auto

Пусть API решает, включать ли эмоциональный голос для целевой локации.

Enable

Форс, чтобы включить эмоциональный голос, если в целевом месте есть эмоции, поддерживаемые голосом.

Disable

Отключите голосовые эмоции на платформе для целевого места.

InputFileSourceKind

Тип входного источника для входных видео, аудио или webvtt файлов.

Значение Описание
AzureStorageBlobManagedIdentity

Azure Storage blob с управляемой аутентификацией идентичности.

Iteration

Сделайте одну итерацию, чтобы перевести один видеофайл из исходного места в целевой локал, webvtt для редактирования контента опцион для запроса параметра.

Имя Тип Описание
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

Ввод итерации.

Имя Тип Описание
adjustBackgroundVolumeMultiplier

number (double)

maximum: 1

Рекомендую: не устанавливайте этот параметр, если у вас нет конкретных требований. Стандартное поведение оптимизировано для большинства клиентов. Регулируйте фоновую громкость в зависимости от максимальной громкости с помощью этого множителя. Диапазон значений — (0, 1), рекомендуемое значение — 0.6, если вы хотите регулировать фоновую громкость. Если это не указано, исходная звуковая громкость фонового звука останется без изменений.

adjustWebvttAlignment

boolean

Рекомендую: не устанавливайте этот параметр, если у вас нет конкретных требований. Стандартное поведение оптимизировано для большинства клиентов. Укажите, нужно ли корректировать выравнивание webvtt в соответствии с синтезированным аудио для переведённого текста. Если true (по умолчанию), выравнивание будет скорректировано. Если ошибка, выравнивание не будет корректировано. Если не указано, значение по умолчанию является истинным (предоставлено как null в API).

enableEmotionalPlatformVoice

EnableEmotionalPlatformVoice

Рекомендую: не устанавливайте этот параметр, если у вас нет конкретных требований. Стандартное поведение оптимизировано для большинства клиентов. Этот параметр указывает, включать ли эмоции для голоса платформы. По умолчанию сервер решает, применять ли эмоции, исходя из целевого места для оптимизации качества. Если это не указано, API автоматически решит, включать ли эмоциональное выражение на стороне сервера.

enableOcrCorrectionFromSubtitle

boolean

Укажите, разрешать ли API корректировать результаты распознавания речи (SR) с помощью субтитров из оригинального видеофайла. Используя существующие субтитры, API может повысить точность транскрибированного текста, обеспечивая более точную и надёжную конечную версию; если не указано, перевод не будет корректировать из OCR-субтитра.

enableVideoSpeedAdjustment

boolean

Этот параметр позволяет регулировать скорость воспроизведения видео для лучшего согласования с переводом аудио. При включении API может замедлить или ускорить видео в соответствии с временем перевода аудио, обеспечивая более синхронизированный и бесшовный просмотр; если это не указано, скорость видео не будет регулироваться.

exportAdjustedPromptAudioInWebvtt

boolean

Укажите, экспортировать ли скорректированное аудио запроса в webvtt; если не указано, значение по умолчанию ложно.

exportSubtitleInVideo

boolean

Экспорт субтитра в видео, если это не указано, оно унаследует значение, определённое при создании перевода.

exportTargetLocaleAdvancedSubtitleFile

boolean

Этот параметр, когда он включён, позволяет API экспортировать субтитры в формате Advanced SubStation Alpha. Файл субтитров может указывать стили и цвета шрифтов, что помогает решать проблемы с отображением символов в некоторых целевых локациях, таких как арабский (Ar), японский (Ja), корейский (Ko) и китайский (Ch). Используя этот параметр, вы можете убедиться, что субтитры визуально привлекательны и корректно отображаются на разных языках и в разных регионах, если это не указано, ответ на итерацию не будет включать продвинутые субтитры.

pushResultToAzureStorageBlobDirUrl

string (uri)

Azure storage blob directory URL to push iteration results. При указании API отправляет результаты перевода в указанный каталог blob хранилища Azure.

pushResultToAzureStorageBlobManagedIdentityClientId

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

Управляемый идентификатор клиента для управляемой идентичности для отправки результатов в Azure storage blob, если API не указано, будет использовать системно назначенную управляемую идентичность. Это свойство используется только при указании pushResultToAzureStorageBlobDirURL.

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})$

Этот параметр задаёт цвет контура субтитров на выходе видеоперевода. Значение должно быть приведено в формате rr gg bb, #<rr><gg><bb>, <rr><gg><bb><aa> или #<rr><gg><bb><aa,> где <rr> — красная компонента цвета, <gg> — зелёная компонента, <bb> — синяя компонента, <aa> — альфа-компонент.>><><< Например, EBA205 или #EBA205 устанавливали цвет субтитров на определённый оттенок жёлтого. Этот параметр позволяет настраивать внешний вид субтитров для улучшения читаемости и визуальной привлекательности; если это не указано, будет использоваться чёрный цвет по умолчанию.

subtitlePrimaryColor

string

minLength: 6
maxLength: 9
pattern: ^#?(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Этот параметр определяет основной цвет субтитров в выходе видеоперевода. Значение должно быть приведено в формате rr gg bb, #<rr><gg><bb>, <rr><gg><bb><aa> или #<rr><gg><bb><aa,> где <rr> — красная компонента цвета, <gg> — зелёная компонента, <bb> — синяя компонента, <aa> — альфа-компонент.>><><< Например, EBA205 или #EBA205 устанавливали цвет субтитров на определённый оттенок жёлтого. Этот параметр позволяет настраивать внешний вид субтитра для улучшения читаемости и визуальной привлекательности; если это не указано, будет использоваться белый цвет по умолчанию.

subtitleVerticalMargin

integer (int32)

minimum: 0
maximum: 200

Укажите вертикальное поле субтитра, диапазон значений — от 0 до 200, если не указано, значение по умолчанию — 10.

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. Эти параметры взаимоисключаются — требуется только один из них. Если оба предоставлены, запрос будет признан недействительным.

use24kPromptAudio

boolean

Рекомендую: не устанавливайте этот параметр, если у вас нет конкретных требований. Стандартное поведение оптимизировано для большинства клиентов. Когда этот параметр установлен в true, сервис использует аудио с более высокой частотой дискретизации (24 кГц) для голосовой подсказки. Если этот параметр не указан или установлен как false, сервис по умолчанию продолжает использовать 16 кГц prompt audio, что обычно обеспечивает лучшее качество синтеза.

webvttFile

WebvttFile

Webvtt для редактирования контента, этот параметр требуется при втором запросе на создание итерации перевода.

IterationResult

Результат итерации.

Имя Тип Описание
metadataJsonWebvttFileUrl

string (uri)

Metadata json webvtt file URL.

reportFileUrl

string (uri)

URL файла отчёта.

sourceLocaleSubtitleWebvttFileUrl

string (uri)

URL файла субтитров, локализация источника.

targetLocaleAdvancedSubtitleFileUrl

string (uri)

Это свойство предоставляет URL целевой локации — файла субтитов Advanced SubStation Alpha (ASS). Он заполняется только тогда, когда exportTargetLocaleAdvancedSubtitleFile установлен в true во время создания итераций; в противном случае это свойство не будет включено в ответ.

targetLocaleSubtitleWebvttFileUrl

string (uri)

URL файла субтитра для целевой локации.

translatedAudioFileUrl

string (uri)

URL переведённого аудиофайла.

translatedVideoFileUrl

string (uri)

URL переведённого видео.

Status

Статус задачи.

Значение Описание
NotStarted

Состояние "Не запущено"

Running

Состояние выполнения

Succeeded

Статус «Забег преуспен»

Failed

Статус провала пробега

Canceled

Состояние отменено

Translation

Создайте ресурс перевода для размещения итераций перевода одного видеофайла из исходного места в целевой локал.

Имя Тип Описание
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

Описание перевода.

displayName

string

Перевод отображает имя.

expiresDateTime

string (date-time)

Отметка времени перевода будет автоматически удалена. Метка времени кодируется в формате даты и времени ISO 8601 («YYYY-MM-DDThh:mm:ssZ», см. https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).

failureReason

string

Причина неудачи перевода

firstIterationInput

IterationInput

Вход первой итерации для перевода, это свойство используется только при верности autoCreateFirstIteration.

id

string

minLength: 3
maxLength: 64
pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$

ID переводческого ресурса.

input

TranslationInput

Перевод.

latestIteration

Iteration

Последняя версия перевода.

latestSucceededIteration

Iteration

Последняя завершённая версия перевода.

TranslationInput

Перевод.

Имя Тип Описание
audioFileUrl

string (uri)

Аудиофайл перевода: URL Azure blob, формат файла .mp3 или .wav, максимальный размер файла 5 ГБ и продолжительность видео 4 часа. Введите вводный медиафайл с помощью videoFileUrl или audioFileUrl — эти параметры взаимоисключаются — требуется только один из них. Если оба предоставлены, запрос будет признан недействительным.

autoCreateFirstIteration

boolean

Укажите, нужно ли автоматически создавать первую итерацию при создании перевода, если не указано, значение по умолчанию ложно без автоматического создания первой итерации.

enableLipSync

boolean

Укажите, включать ли синхронизацию губ, если нет указано, значение по умолчанию ложно для отключения синхронизации губ.

exportSubtitleInVideo

boolean

Экспортировать субтитры в видео, если не указано, значение по умолчанию ложное, субтитры не будут записываться в переведённый видеофайл.

inputFileAzureStorageBlobManagedIdentityClientId

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

Идентификатор управляемого идентификатора клиента для управляемой идентичности для доступа к входному файлу из blob хранилища Azure, если API не указано, будет использовать управляемую идентичность, назначенную системой. Это свойство используется только тогда, когда inputFileSourceKind — AzureStorageBlobManagedIdentity.

inputFileSourceKind

InputFileSourceKind

Исходный тип входного файла, если не указано, значение по умолчанию — доступ к входному файлу с анонимным доступом.

sourceLocale

string

minLength: 5
maxLength: 16
pattern: ^[A-Za-z]{2,4}([_-][A-Za-z]{4})?([_-]([A-Za-z]{2}|[0-9]{3}))?$

Исходное местоположение видеофайла. Код локации соответствует BCP-47. Вы можете найти список локализации текста в речь здесь https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts , если не указано, исходный код будет автоматически определяться из видеофайла, авто-распознавание поддерживается только после версии 2025-05-20.

speakerCount

integer (int32)

Количество колонок в видео, если не указано, оно автоматически определяется из видеофайла.

subtitleMaxCharCountPerSegment

integer (int32)

Субтитры — максимальное количество символов на сегмент, если не предусмотрено, будет использоваться значение по умолчанию, зависящее от языка.

targetLocale

string

minLength: 5
maxLength: 16
pattern: ^[A-Za-z]{2,4}([_-][A-Za-z]{4})?([_-]([A-Za-z]{2}|[0-9]{3}))?$

Целевая локация перевода. Код локации соответствует BCP-47. Вы можете найти список местоположения для превращения текста в речь здесь https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.

videoFileUrl

string (uri)

Translation video file Azure blob url, .mp4 формат файла, максимальный размер файла 5GB и продолжительность видео 4 часа. Введите вводный медиафайл с помощью videoFileUrl или audioFileUrl — эти параметры взаимоисключаются — требуется только один из них. Если оба предоставлены, запрос будет признан недействительным.

voiceKind

VoiceKind

Голос перевода.

VoiceKind

Голос TTS доброжелательный.

Значение Описание
PlatformVoice

Голос платформы TTS

PersonalVoice

Личный голос TTS

WebvttFile

Перевод webvtt файла.

Имя Тип Описание
kind

WebvttFileKind

Перевод webvtt файла.

url

string (uri)

URL файла перевода webvtt.

WebvttFileKind

Вид файла Webvtt.

Значение Описание
SourceLocaleSubtitle

Исходный локал простого текста субтитры webvtt file

TargetLocaleSubtitle

Target locale plain text subtitle webvtt file

MetadataJson

Target locale metadata JSON webvtt file