API de traducción de texto

Esta API traduce texto mediante trabajos en cola, con un idioma de destino por trabajo. Envía el texto, conserva el ID del trabajo devuelto y consulta el trabajo hasta que termine el procesamiento. Envía todas las solicitudes por HTTPS con las credenciales de tu cuenta, ya sean credenciales HTTP Basic como en los ejemplos o un token de API, según se describe en Autenticación. Mantén las credenciales en tu servidor.

Puntos de acceso

Los dos servidores de API, https://api.multi.tel y el servidor de compatibilidad https://api.multitel.net, comparten los mismos trabajos, claves de idempotencia, límites y facturación, todo dentro del ámbito de la cuenta. Se diferencian en la estructura externa de las respuestas, por lo que debes usar siempre el mismo servidor con un analizador adecuado.

En api.multi.tel, todas las rutas también están disponibles con el prefijo /v1/translate en lugar de /v3/translate. En api.multitel.net, usa las rutas /v3/translate.

La respuesta de información del servicio incluye enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages y ratesNanosPerCharacter. cpuLanguages enumera los códigos de idioma base aceptados para la traducción estándar. ratesNanosPerCharacter indica el precio configurado por punto de código de origen para cada motor, en milmillonésimas de dólar estadounidense: un valor de 5000 equivale a $5 por millón de puntos de código. La respuesta no indica si la traducción mejorada está disponible en ese momento; una estimación mejorada devuelve 503 cuando no lo está. Consultarla es gratis.

Traducir texto

Envía JSON con Content-Type: application/json a POST https://api.multi.tel/v3/translate. Cada trabajo tiene un idioma de destino, por lo que debes enviar un trabajo separado para cada destino.

Los códigos regionales son etiquetas BCP 47 de 2 a 63 letras, dígitos y guiones. Se convierten a su forma canónica, de modo que en-us se registra como en-US. Las etiquetas no válidas y und, mul o zxx devuelven 400 y invalid_translation_language. La disponibilidad estándar se comprueba por idioma base, y nb y nn cuentan como no. Se acepta y registra un destino regional como fr-CA, pero el resultado estándar sigue el idioma base y no se garantiza que refleje la región.

En este servidor, limita el cuerpo de la solicitud a 128 KiB. Envía el texto como UTF-8 en lugar de representar cada carácter no ASCII mediante una secuencia \u, lo que puede hacer que una solicitud de 20,000 caracteres supere el límite.

El cuerpo solo acepta estos cuatro campos. Cualquier otra propiedad se rechaza con 400 y invalid_translation_request, como idempotency_key, los ID de propietario, los indicadores de procesamiento gratuito y los arrays de segmentos.

Idempotencia y reutilización

Cada envío requiere un encabezado Idempotency-Key de 1 a 190 caracteres. Usa letras ASCII, dígitos, -, _, . y :, sin espacios al principio ni al final; una clave ausente o de 191 caracteres o más se rechaza con 400. Las claves están limitadas a tu cuenta y al servicio de traducción, y se comparten entre ambos servidores y todas las credenciales de tu cuenta.

• La misma clave con el mismo texto, idiomas canónicos y motor devuelve el trabajo existente con HTTP 200 y duplicate: true, sin otro cargo.
• La misma clave con otro texto, idiomas o motor devuelve 409 y idempotency_conflict. La misma clave también devuelve 409 si la versión del procesamiento ha cambiado desde que se creó su trabajo. En ese caso, consulta el trabajo original por su ID en lugar de volver a enviarlo.
• Una clave nueva con el mismo texto, idiomas canónicos y motor devuelve el trabajo existente con HTTP 200 y duplicate: true, sin un nuevo cargo de procesamiento, si existe un trabajo con ese contenido y la versión actual del procesamiento en cola, procesándose, completado o pendiente de pago. Un trabajo reutilizado que esté pendiente de pago aún necesita liquidarse. Los trabajos fallidos no se reutilizan: se crea un trabajo nuevo y se cobra cuando termina.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Un trabajo nuevo devuelve HTTP 202. El texto de ejemplo tiene 57 puntos de código, por lo que, a $5 por millón de puntos de código, cuesta $0.000285. Una respuesta abreviada (el identificador es un ejemplo):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Un envío también puede devolver 402 y insufficient_balance si el saldo de prepago no alcanza para el trabajo junto con tus otros trabajos pendientes, y 429 y translation_queue_full si tu cuenta o el servicio tienen demasiados trabajos pendientes. Devuelve 503 en estos casos:

• paid_translation_not_enabled mientras la traducción de pago está deshabilitada.
• translation_unavailable para una solicitud mejorada mientras la traducción mejorada no está disponible.
• translation_pricing_unavailable mientras el motor elegido no tiene una tarifa configurada.

Reintenta las respuestas 429 y 503 más tarde con la misma clave.

Elegir la calidad

El texto largo se procesa en fragmentos más pequeños que después se unen. Los saltos de línea y los espacios pueden cambiar, y una frase puede perder contexto al cruzar un límite de procesamiento. Conserva el texto original y revisa el resultado completo. La traducción estándar utiliza el idioma base de una etiqueta regional; aceptar y registrar una etiqueta no garantiza una redacción regional.

La traducción estándar se ejecuta en procesos de trabajo en CPU. La traducción mejorada envía el texto al servicio externo de IA configurado. Su resultado también requiere revisión; el servicio no garantiza que un motor sea más preciso para todas las combinaciones de idiomas o tipos de texto.

La traducción estándar es un borrador cuya calidad y tiempo de procesamiento varían según la combinación de idiomas. La traducción mejorada está pensada para texto en el que importa el contexto, pero también requiere revisar nombres, números, negaciones y compromisos importantes. Ninguna opción corrige los errores que ya existan en una transcripción original, así que conserva el original para comparar.

Usa GET /v3/translate en el mismo servidor de API para comprobar la disponibilidad actual, los idiomas estándar compatibles y las tarifas configuradas. Una solicitud estándar cuyo idioma base de origen o destino no figure en cpuLanguages devuelve 422 y translation_language_pair_unavailable. Cuando se proporciona source_language y tiene el mismo idioma base que el destino, la solicitud devuelve 409 y translation_same_language en lugar de crear un trabajo. La traducción mejorada se habilita por separado: mientras no esté disponible, los envíos y estimaciones mejorados devuelven 503.

Obtener primero una estimación

En api.multi.tel, envía el mismo cuerpo JSON a POST /v3/translate/estimate. No se necesita una clave de idempotencia. La estimación aplica las mismas validaciones, incluidas las comprobaciones 422 y 409, pero no crea un trabajo, no traduce texto, no reserva fondos, no comprueba tu saldo ni cobra a tu cuenta. Devuelve HTTP 200 con estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd y costUsd dentro de data. Para el ejemplo anterior, costUsd es 0.000285000 con la tarifa estándar. Mientras la traducción mejorada no esté disponible, una estimación mejorada devuelve 503 y service_unavailable. Las estimaciones utilizan la tarifa configurada en ese momento. La tarifa de un trabajo queda fijada al crearlo y su cargo utiliza esa tarifa.

Obtener la traducción

Un envío nuevo devuelve HTTP 202 y un trabajo existente o reutilizado devuelve HTTP 200. Conserva data.id y utiliza el flujo de trabajo compartido. El objeto del trabajo contiene estos campos:

• id, status, engine, sourceLocale y targetLocale.
• sourceCharacters, costUsd, costIsEstimate y pricePerMillionCharactersUsd.
• progress y createdAt.
• modelVersion, una cadena opaca que identifica la versión del procesamiento.
• duplicate en las respuestas reutilizadas.
• failureCode para trabajos fallidos: translation_failed, translation_timeout, input_failed o worker_lease_lost.

Un trabajo fallido muestra un costUsd de cero.

Un trabajo completado tiene data.result con sourceLocale (vacío si no se indicó el idioma de origen), targetLocale, el text traducido (textos de los segmentos unidos con saltos de línea) y segments. Para el texto enviado a través de esta API, segments contiene una entrada con el text traducido y el language de destino. Los resultados de trabajos pendientes de pago se retienen hasta su liquidación.

Usar api.multitel.net

El punto de acceso de compatibilidad POST https://api.multitel.net/v3/translate acepta los mismos campos JSON y el mismo encabezado Idempotency-Key. Si falta el encabezado, también acepta una cadena idempotency_key en el cuerpo JSON. Cualquier otro campo adicional se rechaza con 400 y unsupported_translation_option. En este servidor, el cuerpo sin procesar puede ocupar hasta 256,000 bytes, y un texto de más de 20,000 puntos de código devuelve 413 y translation_too_large en lugar de 400. Un source_language vacío se trata como omitido. Una respuesta 429 incluye Retry-After: 15. Este servidor también devuelve estos errores:

• 400 json_body_required si falta el cuerpo, no es JSON válido o es un escalar JSON. Envía un objeto JSON.
• 400 invalid_translation_options si text, target_language o engine falta, está vacío o no es una cadena, o si source_language no es una cadena.
• 400 invalid_translation_text si el texto solo contiene espacios en blanco.
• 400 invalid_translation_engine si el motor es desconocido.
• 400 idempotency_key_required si la clave falta, está vacía o es demasiado larga, o si no es una cadena el campo idempotency_key.
• 400 invalid_job si el ID del trabajo tiene un formato incorrecto.

Las respuestas del servicio de traducción de este servidor usan la estructura externa {"status":{"code":HTTP_STATUS},"response":{...}}, donde status es un objeto. Lee el ID del trabajo en response.id y el resultado completado en response.result. En caso de error, el código se incluye en response.code, sin mensaje ni ID de solicitud. Los fallos de autenticación (401) los devuelve la comprobación general de inicio de sesión del servidor y pueden tener un cuerpo distinto, por lo que debes revisar el estado HTTP antes de analizar la respuesta. Los trabajos se comparten con el servidor principal, pero usa el mismo servidor para las consultas de estado, la liquidación y el uso para que tu analizador coincida con la estructura externa. Este servidor también acepta los mismos campos JSON en /v3/translate/estimate sin clave de idempotencia, y su estimación está dentro de response.