Trabajos de transcripción y traducción

Sustituye SERVICE a continuación por speech_to_text o translate, y JOB_ID por el UUID recibido. Todas las operaciones requieren credenciales de tu cuenta, tal como se describe en Autenticación, y se limitan a la cuenta propietaria. Puedes consultar un trabajo desde cualquiera de los dos hosts de la API, pero cada uno usa su propia estructura de respuesta; utiliza siempre el mismo host.

En api.multitel.net, los errores de autenticación (401) se devuelven antes de aplicar esta estructura y pueden tener un cuerpo diferente. Comprueba el estado HTTP antes de analizar la respuesta.

Autenticación

Cada solicitud debe incluir credenciales de tu cuenta. Los trabajos, claves de idempotencia, límites, datos de uso y cargos pertenecen a la cuenta propietaria de las credenciales. Se comparten entre todas las credenciales de esa cuenta en ambos hosts, independientemente de cuáles envíen la solicitud.

• HTTP Basic (Authorization: Basic, o curl --user). Se aceptan una cuenta de API de tipo contraseña, una subcuenta o las credenciales de acceso de tu cuenta. Recomendamos una cuenta de API dedicada. El nombre de usuario no puede contener dos puntos, y ni el nombre de usuario ni la contraseña pueden estar vacíos.
• Token Bearer (Authorization: Bearer YOUR_TOKEN). Se acepta para una cuenta de API de tipo token. Estas cuentas deben tener una restricción de IP y las solicitudes deben proceder de una dirección permitida. Ambos hosts de la API aceptan las direcciones IPv4 y los rangos CIDR configurados para la cuenta. No se puede enviar un token como contraseña Basic. Comprueba que tu token funcione en el host que utilices.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Si una cuenta de API tiene restricciones por dirección IP, envía las solicitudes desde una dirección permitida. Las credenciales ausentes o no válidas devuelven 401. En api.multitel.net, las credenciales válidas que no pueden utilizar estos servicios, como las de una cuenta de tipo token enviadas mediante Basic, devuelven 403 unsupported_transcription_principal o unsupported_translation_principal. Los intentos de autenticación fallidos repetidos desde una misma dirección en api.multitel.net pueden provocar el bloqueo de esa dirección. Corrige las credenciales antes de volver a intentarlo.

Consultar hasta que termine el trabajo

Envía una solicitud GET /v3/SERVICE/JOB_ID. Recomendamos no consultar con más frecuencia que una vez cada 3 segundos. La estructura exterior describe la solicitud; consulta el campo status del trabajo para determinar si ha terminado el procesamiento.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

En api.multitel.net, establece HOST en https://api.multitel.net y lee .response.id en lugar de .data.id.

Reintentar solicitudes inciertas de forma segura

Si un envío agota el tiempo de espera o devuelve 429 o un estado 5xx, reenvía los mismos datos con la misma clave de idempotencia. La respuesta de cualquiera de los hosts puede perderse o sustituirse por un error después de que se acepte el trabajo; reenviar la misma clave devuelve el trabajo si existe. Reutilizar una clave con datos diferentes devuelve 409 idempotency_conflict. Algunos errores se repiten en cada intento, como 503 mientras un servicio de pago está desactivado o 500 para un archivo de audio que no se puede leer. Detente después de unos pocos intentos.

Cambiar la clave tiene efectos diferentes en cada servicio.

• Para la transcripción de audio, una clave nueva crea un trabajo nuevo, con un cargo independiente si el procesamiento finaliza correctamente. La clave original sigue devolviendo el trabajo original, incluso después de una actualización del procesamiento.
• Para la traducción, una clave nueva con contenido idéntico devuelve sin cargos nuevos un trabajo coincidente en espera, en procesamiento, completado o pendiente de pago. Crea trabajo nuevo si el anterior falló o cambió la versión de procesamiento. Un reintento de traducción con la clave original devuelve 409 después de un cambio de versión de procesamiento; conserva el ID del trabajo original y consulta el trabajo directamente.

Obtener un resultado después de añadir saldo

Para un trabajo en estado awaiting_payment, añade fondos hasta que el saldo sea al menos igual al valor costUsd del trabajo, redondeado hacia arriba al siguiente múltiplo de $0.00001, y envía POST /v3/SERVICE/JOB_ID/settle. Los débitos se realizan en pasos enteros de $0.00001 e incluyen cualquier resto acumulado de trabajos anteriores del mismo servicio. Por ello, el importe debitado puede superar costUsd en menos de $0.00001. En api.multi.tel, envía el JSON {} o un cuerpo vacío; cualquier propiedad en el cuerpo se rechaza con 400. api.multitel.net ignora el cuerpo. La liquidación libera el resultado guardado sin ejecutar de nuevo la transcripción o la traducción. La respuesta contiene el trabajo; comprueba que su estado sea completed. Si el saldo sigue siendo insuficiente, el trabajo permanece en estado awaiting_payment y la respuesta sigue siendo HTTP 200.

Para la transcripción de audio, liquidar un trabajo ya completado lo devuelve con duplicate: true, y liquidar un trabajo en espera, en procesamiento o fallido devuelve 409 transcription_not_awaiting_payment. Para la traducción, liquidar un trabajo en cualquier otro estado lo devuelve sin cambios. La liquidación solo está disponible mientras el procesamiento de pago esté activado (en caso contrario, 503). Los trabajos pendientes de pago cuentan como coste reservado, de modo que, en las cuentas de prepago, pueden bloquear nuevos envíos de pago con 402 hasta que se liquiden.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Consultar el uso

Utiliza GET /v3/SERVICE/usage. Los parámetros opcionales from y to son fechas UTC con formato YYYY-MM-DD, y se incluyen ambas fechas límite. Si se omiten, from toma por defecto la fecha de hace 30 días y to la fecha de hoy (UTC). to no debe ser anterior a from, y las fechas pueden estar separadas como máximo por 366 días (hasta 367 fechas incluidas). Las fechas no válidas y los intervalos invertidos o más largos devuelven 400, al igual que otros parámetros de consulta en api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

La respuesta contiene mode, currency (USD), from, to y days, una lista ordenada de más reciente a más antiguo.

• Las entradas de transcripción de audio se agrupan por fecha y fuente. Contienen date, source (api, o hpbx para grabaciones de Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd y debitedUsd.
• Las entradas de traducción se agrupan por fecha, fuente y motor. Contienen date, source, engine, jobs, sourceCharacters, accruedUsd y debitedUsd.

accruedUsd es el coste exacto con nueve decimales, y debitedUsd es el importe debitado, con cinco. El uso se registra en la fecha UTC en la que se liquida el cargo de cada trabajo, por lo que no aparecen los trabajos en espera, en procesamiento, fallidos o pendientes de pago.

Límites

Cada cuenta puede tener como máximo 50 trabajos pendientes de transcripción de audio y traducción en total: en espera, en procesamiento o pendientes de pago, incluidos los trabajos con grabaciones de Hosted PBX. Cuando se alcanza este límite o la capacidad total del servicio, los envíos devuelven 429 transcription_queue_full o translation_queue_full. api.multi.tel también limita cada dirección IP de cliente a 300 solicitudes por minuto entre todas las solicitudes a ese host. Al alcanzar ese límite, devuelve 429 con cabeceras de limitación de frecuencia y un cuerpo de texto sin formato, en lugar de la estructura JSON de error.

Gestionar los errores de las solicitudes

En el host principal, los fallos devuelven un estado de error HTTP y JSON con status: "error", code, message y requestId. Cada respuesta incluye también una cabecera X-Request-ID. Puedes proporcionar tu propio valor; los valores de más de 128 caracteres se truncan. El host de compatibilidad solo devuelve el código de error en response.code. Registra el ID de solicitud, cuando esté disponible, y el código de error, pero no incluyas audio, texto ni credenciales en los registros.

Estados habituales:

Guíate por el código de error devuelto, en lugar de suponer que todos los fallos de validación tienen el mismo estado.

Para 429 o 503, espera y reintenta con intervalos crecientes y la misma clave de envío; respeta Retry-After cuando esté presente. Si los datos de entrada o las credenciales no son válidos, corrige primero la causa. No envíes claves nuevas repetidamente mientras los trabajos anteriores sigan en espera.