Translator v3.0

2025-05-20

¿Qué hay nuevo?

La versión 3.0 de Translator proporciona una API web moderna basada en JSON. Mejora la facilidad de uso y el rendimiento consolidando las características existentes en menos operaciones y proporciona nuevas características.

Transliteración para convertir texto en un idioma de un script a otro.
Traducción a varios idiomas en una solicitud.
Detección de idioma, traducción y transliteración en una solicitud.
Diccionario para buscar traducciones alternativas de un término, para buscar traducciones inversas y ejemplos que muestran los términos usados en el contexto.
Resultados de detección de idioma más informativos.

Direcciones URL base

Las solicitudes a Translator son, en la mayoría de los casos, controladas por el centro de datos más cercano a donde se originó la solicitud. Si se produce un error en el centro de datos al usar el punto de conexión global, la solicitud se puede enrutar fuera de la geografía.

Para forzar que la solicitud se controle dentro de una geografía específica, use el punto de conexión geográfico deseado. Todas las solicitudes se procesan entre los centros de datos dentro de la geografía.

✔️ Característica: Translator Text

Punto de conexión de servicio	Solicitud del centro de datos de procesamiento
Global (recomendado): `api.cognitive.microsofttranslator.com`	Centro de datos más cercano disponible.
Américas: `api-nam.cognitive.microsofttranslator.com`	Este de EE. UU. 2 • Oeste de EE. UU. 2
Asia Pacífico: `api-apc.cognitive.microsofttranslator.com`	Este de Japón • Sudeste asiático
Europa (excepto Suiza): `api-eur.cognitive.microsofttranslator.com`	Centro de Francia • Oeste de Europa
Suiza: para obtener más información, consultePuntos de conexión de servicio de Suiza.	Norte de Suiza • Oeste de Suiza

Puntos de conexión de servicio de Suiza

Los clientes con un recurso ubicado en las regiones Norte de Suiza u Oeste de Suiza pueden estar seguro de que sus solicitudes de Text API se atienden en Suiza. Para asegurarse de que las solicitudes se controlan en Suiza, cree el recurso de Traductor en la Resource regionSwitzerland North u Switzerland West y, a continuación, use el punto de conexión personalizado del recurso en las solicitudes de API.

Por ejemplo, si crea un recurso de Translator en Azure Portal con una Resource region como Switzerland North y el nombre de recurso es my-swiss-n, después el punto de conexión personalizado será https://my-swiss-n.cognitiveservices.azure.com. Y una solicitud de ejemplo para traducir sería:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

El servicio Traductor personalizado no está disponible actualmente en Suiza.

Autenticación

Suscríbase a Translator o a varios servicios en los servicios de Azure AI y use la clave (disponible en Azure Portal) para autenticarse.

Hay tres encabezados que puede usar para autenticar la suscripción. En esta tabla se describe cómo se usa cada una:

encabezados	Descripción
Ocp-Apim:Subscription-Key	Use con la suscripción de servicios de Azure AI si pasa la clave secreta. El valor es la clave secreta de Azure para la suscripción a Translator.
Autorización	Use con la suscripción de servicios de Azure AI si pasa un token de autenticación. El valor es el token de portador: `Bearer <token>`.
Ocp-Apim:Subscription-Region	Use con varios servicios y recursos de traductor regional. El valor es la región del recurso de traductor regional o multiservicio. Este valor es opcional cuando se usa un recurso de traductor global.

Clave secreta

La primera opción es autenticarse mediante el Ocp-Apim-Subscription-Key encabezado . Agregue el Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> encabezado a la solicitud.

Autenticación con un recurso global

Al usar un recurso de traductor global, debe incluir un encabezado para llamar a Translator.

encabezados	Descripción
Ocp-Apim:Subscription-Key	El valor es la clave secreta de Azure para la suscripción a Translator.

Esta es una solicitud de ejemplo para llamar a Translator mediante el recurso de traductor global.

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticación con un recurso regional

Cuando se usa un recurso de traductor regional, hay dos encabezados que debe llamar a Translator.

encabezados	Descripción
Ocp-Apim:Subscription-Key	El valor es la clave secreta de Azure para la suscripción a Translator.
Ocp-Apim:Subscription-Region	El valor es la región del recurso translator.

Esta es una solicitud de ejemplo para llamar a Translator mediante el recurso de traductor regional.

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Autenticación con un recurso de varios servicios

Un recurso de varios servicios permite usar una sola clave de API para autenticar solicitudes para varios servicios.

Al usar una clave secreta de varios servicios, debe incluir dos encabezados de autenticación con la solicitud. Hay dos encabezados que debe llamar a Translator.

encabezados	Descripción
Ocp-Apim:Subscription-Key	El valor es la clave secreta de Azure para el recurso de varios servicios.
Ocp-Apim:Subscription-Region	El valor es la región del recurso de varios servicios.

La región es necesaria para la suscripción de Text API de varios servicios. La región que seleccione es la única región que puede usar para la traducción de texto al usar la clave de varios servicios. Debe ser la misma región que seleccionó al suscribirse a la suscripción de varios servicios a través de Azure Portal.

Si pasa la clave secreta en la cadena de consulta con el parámetro Subscription-Key, debe especificar la región con el parámetro Subscription-Regionde consulta .

Autenticación con token de acceso

Como alternativa, puede intercambiar la clave secreta para un token de acceso. Este token se incluye con cada solicitud como Authorization encabezado. Para obtener un token de autorización, realice una POST solicitud a la siguiente dirección URL:

Tipo de recurso	Dirección URL del servicio de autenticación
Global	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regional o multiservicio	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Estas son las solicitudes de ejemplo para obtener un token dado una clave secreta para un recurso global:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Y estas son solicitudes de ejemplo para obtener un token dado una clave secreta para un recurso regional ubicado en Centro de EE. UU.

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Una solicitud correcta devuelve el token de acceso codificado como texto sin formato en el cuerpo de la respuesta. El token válido se pasa al servicio Translator como token de portador en la autorización.

Authorization: Bearer <Base64-access_token>

Un token de autenticación es válido durante 10 minutos. El token se debe reutilizar al realizar varias llamadas a Translator. Sin embargo, si el programa realiza solicitudes a Translator durante un período de tiempo prolongado, el programa debe solicitar un nuevo token de acceso a intervalos regulares (por ejemplo, cada 8 minutos).

Autenticación con Microsoft Entra ID

Translator v3.0 admite la autenticación de Microsoft Entra, la solución de administración de identidades y acceso basada en la nube de Microsoft. Los encabezados de autorización permiten al servicio Translator validar que el cliente solicitante está autorizado para usar el recurso y para completar la solicitud.

Requisitos previos

Una breve comprensión de cómo autenticarse con microsoft Entra ID.
Una breve comprensión de cómo autorizar el acceso a identidades administradas.

Encabezados

Cabecera	Importancia
Autorización	El valor es un token de portador de acceso generado por Azure AD. El token de portador proporciona una prueba de autenticación y valida la autorización del cliente para usar el recurso. Un token de autenticación es válido durante 10 minutos y se debe reutilizar al realizar varias llamadas a Translator. ConsulteSolicitud de ejemplo: 2. Obtención de un token
Ocp-Apim:Subscription-Region	El valor es la región del recurso translator. Este valor es opcional si el recurso es global.
Ocp-Apim-ResourceId	El valor es el identificador de recurso de la instancia de recurso de Translator. Encontrará el identificador de recurso en Azure Portal en Propiedades de Translator Resource →. Formato de identificador de recurso: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Página de propiedades de Translator: Azure Portal

Captura de pantalla: página de propiedades de Translator en Azure Portal.

Importante

Asigne el rol de usuario de Cognitive Services a la entidad de servicio. Al asignar este rol, va a conceder acceso a la entidad de servicio al recurso translator.

Ejemplos

Uso del punto de conexión global

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Uso del punto de conexión personalizado

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Ejemplos de uso de identidades administradas

Translator v3.0 también admite la autorización del acceso a identidades administradas. Si una identidad administrada está habilitada para un recurso de traductor, puede pasar el token de portador generado por la identidad administrada en el encabezado de solicitud.

Con el punto de conexión global

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Con el punto de conexión personalizado

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Compatibilidad con redes virtuales

El servicio Translator ya está disponible con funcionalidades de Virtual Network (VNET) en todas las regiones de la nube pública de Azure. Para habilitar Virtual Network, consulteConfiguración de redes virtuales de servicios de Azure AI.

Una vez activada esta funcionalidad, debe usar el punto de conexión personalizado para llamar a Translator. No puede usar el punto de conexión de traductor global ("api.cognitive.microsofttranslator.com") y no se puede autenticar con un token de acceso.

Puede encontrar el punto de conexión personalizado después de crear un recurso de traductor y permitir el acceso desde redes seleccionadas y puntos de conexión privados.

Vaya hasta la página del recurso de Translator en Azure Portal.
Seleccione Redes en la sección Administración de recursos.
En la pestaña Firewalls y redes virtuales, seleccione Redes y puntos de conexión privados seleccionados.
Seleccione Guardar para aplicar los cambios.
Seleccione Claves y punto de conexión en la sección Administración de recursos .
Seleccione la pestaña Red virtual .
En la lista se muestran los puntos de conexión para la traducción de texto y la traducción de documentos.

encabezados	Descripción
Ocp-Apim:Subscription-Key	El valor es la clave secreta de Azure para la suscripción a Translator.
Ocp-Apim:Subscription-Region	El valor es la región del recurso translator. Este valor es opcional si el recurso es `global`

Esta es una solicitud de ejemplo para llamar a Translator mediante el punto de conexión personalizado.

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Errores

Una respuesta de error estándar es un objeto JSON con el par nombre-valor denominado error. El valor también es un objeto JSON con propiedades:

code: código de error definido por el servidor.
message: cadena que proporciona una representación legible del error.

Por ejemplo, un cliente con una suscripción de evaluación gratuita recibiría el siguiente error una vez agotada la cuota gratuita:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

El código de error es un número de 6 dígitos que combina el código de estado HTTP de 3 dígitos y otro número de 3 dígitos que ayuda a categorizar aún más el error. Los códigos de error comunes son:

Código	Descripción
400000	Una de las entradas de la solicitud no es válida.
400001	El parámetro "scope" no es válido.
400002	El parámetro "category" no es válido.
400003	Falta un especificador de lenguaje o no es válido.
400004	Falta un especificador de script de destino ("To script") o no es válido.
400005	Falta un texto de entrada o no es válido.
400006	La combinación de lenguaje y script no es válida.
400018	Falta un especificador de script de origen ("From script") o no es válido.
400019	No se admite uno de los lenguajes especificados.
400020	Uno de los elementos de la matriz de texto de entrada no es válido.
400021	Falta un parámetro de la versión de API o no es válido.
400023	Uno de los pares de lenguaje especificados no es válido.
400035	El lenguaje fuente (campo "From") no es válido.
400036	Falta el lenguaje de destino (campo "To") o no es válido.
400042	Una de las opciones especificadas (campo "Options") no es válida.
400043	El identificador de seguimiento de cliente (campo ClientTraceId o encabezado X-ClientTraceId) falta o no es válido.
400050	El texto de entrada es demasiado largo. Consulte los límites de solicitud.
400064	Falta un parámetro "translation" o no es válido.
400070	El número de scripts de destino (parámetro ToScript) no coincide con el número de lenguajes de destino (parámetro To).
400071	Valor no válido para TextType.
400072	La matriz de texto de entrada tiene demasiados elementos.
400073	El parámetro de script no es válido.
400074	El cuerpo de la solicitud no es un JSON válido.
400075	La combinación de categoría y par de lenguaje no es válida.
400077	Se supera el tamaño máximo de la solicitud. Consulte los límites de solicitud.
400079	El sistema personalizado solicitado para la traducción entre, desde y hacia el lenguaje no existe.
400080	La transliteración no se admite para el idioma o el script.
401000	La solicitud no está autorizada porque faltan credenciales o no son válidas.
401015	"Las credenciales proporcionadas son para Speech API. Esta solicitud requiere credenciales para Text API. Use una suscripción a Translator".
403000	No se permite la operación.
403001	No se permite la operación porque la suscripción superó su cuota gratuita.
405000	El método de solicitud no se admite para el recurso solicitado.
408001	Se está preparando el sistema de traducción solicitado. Vuelva a intentarlo en unos minutos.
408002	La solicitud superó el tiempo de espera mientras se esperaba la secuencia entrante. El cliente no presentó una solicitud en el tiempo que el servidor estaba preparado para esperar. El cliente puede repetir la solicitud sin modificaciones en cualquier momento posterior.
415000	Falta el encabezado Content-Type o no es válido.
429000, 429001, 429002	El servidor rechazó la solicitud porque el cliente superó los límites de solicitud.
500000	Error inesperado. Si el error persiste, notifique la fecha y hora del error, el identificador de solicitud del encabezado de respuesta X-RequestId y el identificador de cliente del encabezado de solicitud X-ClientTraceId.
503000	El servicio no está disponible temporalmente. Vuelva a intentarlo. Si el error persiste, notifique la fecha y hora del error, el identificador de solicitud del encabezado de respuesta X-RequestId y el identificador de cliente del encabezado de solicitud X-ClientTraceId.

Métricas

Las métricas le permiten ver la información de disponibilidad y uso del traductor en Azure Portal. Para obtener más información, consulte Métricas de datos y plataformas.

Métricas de Translator

En esta tabla se enumeran las métricas disponibles con una descripción de cómo se usan para supervisar las llamadas api de traducción.

Métricas	Descripción
TotalCalls	Número total de llamadas API.
TotalTokenCalls	Número total de llamadas API a través del servicio de token mediante el token de autenticación.
Llamadas correctas	Número de llamadas exitosas.
TotalErrors	Número de llamadas con respuesta de error.
BlockedCalls	Número de llamadas que han superado la tasa o el límite de cuota.
ServerErrors	Número de llamadas con error interno del servidor(5XX).
ClientErrors	Número de llamadas con error del lado cliente(4XX).
Latencia	Duración para completar la solicitud en milisegundos.
CharactersTranslated	Número total de caracteres de la solicitud entrante de texto.