Translation Operations - Create Translation

Servicio:: Azure AI Services

Versión de la API:: 2025-05-20

Crea una traducción.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
endpoint	path	True	string	Puntos de conexión de Cognitive Services admitidos (protocolo y nombre de host, por ejemplo: 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. de recurso de traducción.
api-version	query	True	string minLength: 1	Versión de la API que se va a usar para esta operación.

Encabezado de la solicitud

Nombre	Requerido	Tipo	Description
Operation-Id	True	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Identificador de la operación.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
input	True	TranslationInput	Entrada de traducción.
description		string	Descripción de la traducción.
displayName		string	Nombre para mostrar de traducción.

Respuestas

Nombre	Tipo	Description
200 OK	Translation	La solicitud se ha realizado correctamente. Encabezados Operation-Location: string
201 Created	Translation	La solicitud se ha realizado correctamente y se ha creado un nuevo recurso como resultado. Encabezados Operation-Location: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	Una respuesta de error inesperada. Encabezados x-ms-error-code: string

Nombre

Tipo

Description

200 OK

Translation

La solicitud se ha realizado correctamente.

Encabezados

Operation-Location: string

201 Created

Translation

La solicitud se ha realizado correctamente y se ha creado un nuevo recurso como resultado.

Encabezados

Operation-Location: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

Una respuesta de error inesperada.

Encabezados

x-ms-error-code: string

Seguridad

Ocp-Apim-Subscription-Key

Proporcione la clave de recurso de voz aquí.

Tipo: apiKey
En: header

AADToken

Estos son los flujos de la plataforma de identidad de Microsoft .

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

Nombre	Description
https://cognitiveservices.azure.com/.default

Ejemplos

Create Translation

Solicitud de ejemplo

HTTP

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


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

Respuesta de muestra

status code:: 200

Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo?api-version=2024-02-01-preview
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"
  },
  "createdDateTime": "2023-04-01T05: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"
      }
    }
  }
}

status code:: 201

Operation-Location: https://eastus.api.cognitive.microsoft.com/videotranslation/operations/Create-TranslateMyZhCNVideo?api-version=2024-02-01-preview
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"
  },
  "createdDateTime": "2023-04-01T05: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"
      }
    }
  }
}

Definiciones

Nombre	Description
Azure.Core.Foundations.Error	Objeto de error.
Azure.Core.Foundations.ErrorResponse	Respuesta que contiene los detalles del error.
Azure.Core.Foundations.InnerError	Objeto que contiene información más específica sobre el error. Según las directrices de la API de Microsoft One: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.
EnableEmotionalPlatformVoice	Habilite el tipo de voz de la plataforma emocional.
Iteration	Realice una iteración para traducir un archivo de vídeo de la configuración regional de origen a la configuración regional de destino, webvtt para la edición de contenido es opcional para solicitar el parámetro.
IterationInput	Entrada de iteración.
IterationResult	Resultado de la iteración.
Status	Estado de la tarea.
Translation	Cree un recurso de traducción para hospedar iteraciones de traducción de un archivo de vídeo de la configuración regional de origen a la configuración regional de destino.
TranslationInput	Entrada de traducción.
VoiceKind	Tipo de voz TTS.
WebvttFile	Archivo webvtt de traducción.
WebvttFileKind	Tipo de archivo Webvtt.

Azure.Core.Foundations.Error

Object

Objeto de error.

Nombre	Tipo	Description
code	string	Uno de un conjunto definido por el servidor de códigos de error.
details	Azure.Core.Foundations.Error[]	Matriz de detalles sobre errores específicos que llevaron a este error notificado.
innererror	Azure.Core.Foundations.InnerError	Objeto que contiene información más específica que el objeto actual sobre el error.
message	string	Representación legible del error.
target	string	Destino del error.

Azure.Core.Foundations.ErrorResponse

Object

Respuesta que contiene los detalles del error.

Nombre	Tipo	Description
error	Azure.Core.Foundations.Error	Objeto de error.

Azure.Core.Foundations.InnerError

Object

Objeto que contiene información más específica sobre el error. Según las directrices de la API de Microsoft One: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.

Nombre	Tipo	Description
code	string	Uno de un conjunto definido por el servidor de códigos de error.
innererror	Azure.Core.Foundations.InnerError	Error interno.

EnableEmotionalPlatformVoice

Enumeración

Habilite el tipo de voz de la plataforma emocional.

Valor	Description
Auto	Deje que la API decida si habilitar la voz emocional para la configuración regional de destino.
Disable	Deshabilite la emoción de voz de la plataforma para la configuración regional de destino.
Enable	Forzar la habilitación de la voz emocional si hay una emoción admitida por voz para la configuración regional de destino.

Iteration

Object

Realice una iteración para traducir un archivo de vídeo de la configuración regional de origen a la configuración regional de destino, webvtt para la edición de contenido es opcional para solicitar el parámetro.

Nombre	Tipo	Description
createdDateTime	string (date-time)	Marca de tiempo cuando se creó el objeto. La marca de tiempo se codifica como formato de fecha y hora ISO 8601 ("AAAA-MM-DDThh:mm:ssZ", vea https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
description	string	Descripción de la iteración
failureReason	string	Motivo del error de iteración
id	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Id. de iteración
input	IterationInput	Entrada de iteración.
lastActionDateTime	string (date-time)	Marca de tiempo cuando se especificó el estado actual. La marca de tiempo se codifica como formato de fecha y hora ISO 8601 ("AAAA-MM-DDThh:mm:ssZ", vea https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
result	IterationResult	Resultado de la iteración.
status	Status	Estado de iteración

IterationInput

Object

Entrada de iteración.

Nombre	Tipo	Description
enableEmotionalPlatformVoice	EnableEmotionalPlatformVoice	Este parámetro especifica si se habilita la emoción para la voz de la plataforma. De forma predeterminada, el servidor determina si se aplica la emoción en función de la configuración regional de destino para optimizar la calidad. Si no se especifica, la API decidirá automáticamente si habilitar la expresión emocional en el lado del servidor.
enableOcrCorrectionFromSubtitle	boolean	Indique si desea permitir que la API corrija los resultados del reconocimiento de voz (SR) mediante los subtítulos del archivo de vídeo original. Al aprovechar los subtítulos existentes, la API puede mejorar la precisión del texto transcrito, lo que garantiza que el resultado final sea más preciso y confiable, si no se especifica, la traducción no corregirá los subtítulos OCR.
enableVideoSpeedAdjustment	boolean	Este parámetro permite ajustar la velocidad de reproducción de vídeo para garantizar una mejor alineación con el audio traducido. Cuando está habilitada, la API puede ralentizar o acelerar el video para que coincida con el tiempo del audio traducido, lo que proporciona una experiencia de visualización más sincronizada y fluida, si no se especifica, la velocidad del video no se ajustará.
exportSubtitleInVideo	boolean	Exportar subtítulo en video, si no se especifica, heredará el valor definido en la entrada de la creación de la traducción.
exportTargetLocaleAdvancedSubtitleFile	boolean	Este parámetro, cuando está habilitado, permite a la API exportar subtítulos en el formato Advanced SubStation Alpha. El archivo de subtítulos puede especificar estilos y colores de fuente, lo que ayuda a abordar los problemas de visualización de caracteres en ciertas configuraciones regionales de destino, como árabe (Ar), japonés (Ja), coreano (Ko) y chino (Ch). Mediante el uso de este parámetro, puede asegurarse de que los subtítulos sean visualmente atractivos y se representen correctamente en diferentes idiomas y regiones, si no se especifica, la respuesta de iteración no incluirá subtítulos avanzados.
speakerCount	integer (int32)	Número de hablantes en el vídeo, si no se especifica, heredará el valor definido en la entrada de creación de la traducción.
subtitleFontSize	integer (int32)	Este parámetro especifica el tamaño de fuente de los subtítulos en la salida de traducción de video entre 5 y 30, si no se especifica, utilizará el valor predeterminado dependiente del idioma.
subtitleMaxCharCountPerSegment	integer (int32)	Recuento máximo de caracteres de visualización de subtítulos por segmento, si no se especifica, heredará el valor definido en la entrada de la creación de la traducción.
subtitleOutlineColor	string minLength: 6 maxLength: 9 pattern: ^#?(?:[0-9A-Fa-f]{6}\|[0-9A-Fa-f]{8})$	Este parámetro especifica el color del contorno de los subtítulos en la salida de traducción del vídeo. El valor debe proporcionarse en el formato , # o #, donde representa el componente rojo del color, representa el componente verde, representa el componente azul y representa el componente alfa. Por ejemplo, EBA205 o #EBA205 establecería el color de los subtítulos en un tono específico de amarillo. Este parámetro permite personalizar la apariencia de los subtítulos para mejorar la legibilidad y el atractivo visual, si no se especifica, utilizará el color negro predeterminado.
subtitlePrimaryColor	string minLength: 6 maxLength: 9 pattern: ^#?(?:[0-9A-Fa-f]{6}\|[0-9A-Fa-f]{8})$	Este parámetro especifica el color primario de los subtítulos en la salida de traducción del vídeo. El valor debe proporcionarse en el formato , # o #, donde representa el componente rojo del color, representa el componente verde, representa el componente azul y representa el componente alfa. Por ejemplo, EBA205 o #EBA205 establecería el color de los subtítulos en un tono específico de amarillo. Este parámetro permite personalizar la apariencia de los subtítulos para mejorar la legibilidad y el atractivo visual, si no se especifica, utilizará el color blanco predeterminado.
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}$	Traduzca con léxico personalizado TTS para la síntesis de voz. Proporcione el archivo de léxico personalizado mediante ttsCustomLexiconFileUrl o ttsCustomLexiconFileIdInAudioContentCreation. Estos parámetros son mutuamente excluyentes, solo se requiere uno de ellos. Si se proporcionan ambos, la solicitud se considerará inválida.
ttsCustomLexiconFileUrl	string (uri)	Traduzca con léxico personalizado TTS para la síntesis de voz. Proporcione el archivo de léxico personalizado mediante ttsCustomLexiconFileUrl o ttsCustomLexiconFileIdInAudioContentCreation. Estos parámetros son mutuamente excluyentes, solo se requiere uno de ellos. Si se proporcionan ambos, la solicitud se considerará inválida.
webvttFile	WebvttFile	Archivo webvtt para la edición de contenido, este parámetro es necesario a partir de la segunda solicitud de creación de iteración de la traducción.

IterationResult

Object

Resultado de la iteración.

Nombre	Tipo	Description
metadataJsonWebvttFileUrl	string (uri)	Dirección URL del archivo webvtt json de metadatos.
reportFileUrl	string (uri)	Dirección URL del archivo de informe.
sourceLocaleSubtitleWebvttFileUrl	string (uri)	Dirección URL del archivo de subtítulos de configuración regional de origen.
targetLocaleAdvancedSubtitleFileUrl	string (uri)	Esta propiedad proporciona la dirección URL del archivo de subtítulos Advanced SubStation Alpha (ASS) de la configuración regional de destino. Solo se rellena cuando exportTargetLocaleAdvancedSubtitleFile se establece en true durante la creación de la iteración; de lo contrario, esta propiedad no se incluirá en la respuesta.
targetLocaleSubtitleWebvttFileUrl	string (uri)	Dirección URL del archivo de subtítulos de configuración regional de destino.
translatedAudioFileUrl	string (uri)	URL del archivo de audio traducido.
translatedVideoFileUrl	string (uri)	Dirección URL del archivo de vídeo traducido.

Status

Enumeración

Estado de la tarea.

Valor	Description
Canceled	Estado cancelado
Failed	Estado de error de ejecución
NotStarted	Estado no iniciado
Running	Estado de ejecución
Succeeded	Ejecutar el estado correcto

Translation

Object

Cree un recurso de traducción para hospedar iteraciones de traducción de un archivo de vídeo de la configuración regional de origen a la configuración regional de destino.

Nombre	Tipo	Description
createdDateTime	string (date-time)	Marca de tiempo cuando se creó el objeto. La marca de tiempo se codifica como formato de fecha y hora ISO 8601 ("AAAA-MM-DDThh:mm:ssZ", vea https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).
description	string	Descripción de la traducción.
displayName	string	Nombre para mostrar de traducción.
failureReason	string	Motivo del error de traducción
id	string minLength: 3 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{1,62}[a-zA-Z0-9]$	Id. de recurso de traducción.
input	TranslationInput	Entrada de traducción.
latestIteration	Iteration	Iteración más reciente de la traducción.
latestSucceededIteration	Iteration	Iteración completada más reciente de la traducción.

TranslationInput

Object

Entrada de traducción.

Nombre	Tipo	Description
audioFileUrl	string (uri)	Traducción de archivo de audio URL de blob Azure, formato de archivo .mp3 o .wav, tamaño de archivo máximo de 5 GB y duración del video de 4 horas. Proporcione el archivo multimedia de entrada mediante videoFileUrl o audioFileUrl, estos parámetros son mutuamente excluyentes, solo se requiere uno de ellos. Si se proporcionan ambos, la solicitud se considerará inválida.
enableLipSync	boolean	Indique si desea habilitar la sincronización de labios, si no se proporciona, el valor predeterminado es false para deshabilitar la sincronización de labios.
exportSubtitleInVideo	boolean	Exportar subtítulos en video, si no se especifica, el valor predeterminado es falso, no grabará subtítulos en el archivo de video traducido.
sourceLocale	string minLength: 5 maxLength: 16 pattern: ^[A-Za-z]{2,4}([_-][A-Za-z]{4})?([_-]([A-Za-z]{2}\|[0-9]{3}))?$	Configuración regional de origen del archivo de vídeo. El código de configuración regional sigue A BCP-47. Puede encontrar la lista de configuraciones regionales de texto a voz aquí https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts , si no se especifica, la configuración regional de origen se detectará automáticamente desde el archivo de video, la detección automática solo se admite después de la versión 2025-05-20.
speakerCount	integer (int32)	Número de altavoces en el video, si no se proporciona, se detectará automáticamente desde el archivo de video.
subtitleMaxCharCountPerSegment	integer (int32)	Recuento máximo de caracteres de visualización de subtítulos por segmento, si no se proporciona, utilizará el valor predeterminado dependiente del idioma.
targetLocale	string minLength: 5 maxLength: 16 pattern: ^[A-Za-z]{2,4}([_-][A-Za-z]{4})?([_-]([A-Za-z]{2}\|[0-9]{3}))?$	Configuración regional de destino de la traducción. El código de configuración regional sigue A BCP-47. Puede encontrar el texto en la lista de configuración regional de voz aquí https://learn.microsoft.com/azure/ai-services/speech-service/language-support?tabs=tts.
videoFileUrl	string (uri)	Traducción de archivo de vídeo: URL de blob de Azure, formato de archivo .mp4, tamaño de archivo máximo de 5 GB y duración del vídeo de 4 horas. Proporcione el archivo multimedia de entrada mediante videoFileUrl o audioFileUrl, estos parámetros son mutuamente excluyentes, solo se requiere uno de ellos. Si se proporcionan ambos, la solicitud se considerará inválida.
voiceKind	VoiceKind	Tipo de voz de traducción.

VoiceKind

Enumeración

Tipo de voz TTS.

Valor	Description
PersonalVoice	Voz personal de TTS
PlatformVoice	Voz de la plataforma TTS

WebvttFile

Object

Archivo webvtt de traducción.

Nombre	Tipo	Description
kind	WebvttFileKind	Tipo de archivo webvtt de traducción.
url	string (uri)	Dirección URL del archivo webvtt de traducción.

WebvttFileKind

Enumeración

Tipo de archivo Webvtt.

Valor	Description
MetadataJson	Archivo webvtt JSON de metadatos de configuración regional de destino
SourceLocaleSubtitle	Archivo webvtt de subtítulo de texto sin formato de configuración regional de origen
TargetLocaleSubtitle	Archivo webvtt de subtítulo de texto sin formato de destino

Compartir a través de

Translation Operations - Create Translation

Parámetros de identificador URI

Encabezado de la solicitud

Cuerpo de la solicitud

Respuestas

Seguridad

Ocp-Apim-Subscription-Key

AADToken

Ámbitos

Ejemplos

Create Translation

Solicitud de ejemplo

Respuesta de muestra

Definiciones

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

EnableEmotionalPlatformVoice

Iteration

IterationInput

IterationResult

Status

Translation

TranslationInput

VoiceKind

WebvttFile

WebvttFileKind