Traducción de subtítulos
en tu flujo de trabajo.

Inicio rápido

Crea una clave y descarga el ejemplo de Node.js. Calcula el coste estimado, envía una tarea, consulta su estado y guarda el SRT traducido. Requiere Node.js 20 o posterior y no necesita paquetes adicionales.

export AST_BASE_URL='https://your-website-origin'
export AST_API_KEY='ast_YOUR_API_KEY'
node translate-subtitle.mjs input.srt zh plus translated.srt my-job-001
# Añade true como último argumento para obtener subtítulos bilingües:
node translate-subtitle.mjs input.srt zh plus bilingual.srt my-job-001 true

Sustituye la URL base por el origen de este sitio y coloca el script descargado junto al archivo SRT. Elige explícitamente basic o plus. Tras un fallo de red, reutiliza la misma clave de tarea, entrada y opciones. Una nueva descarga con la misma clave reutiliza la traducción existente; elige un nombre de archivo de salida que todavía no exista.

Autenticación

Abre Panel → Seguridad → Claves API. Asigna un nombre a la clave para crearla. Puedes volver a ver y copiar la clave completa en cualquier momento, o revocarla desde la misma página.

Authorization: Bearer ast_YOUR_API_KEY

Usa el origen de este sitio como URL base. Los 6 endpoints requieren una clave válida. Cada cuenta admite 5 claves activas. Las claves API permiten acceder a las traducciones creadas mediante la API y al saldo de créditos de tu cuenta.

Usa la clave de tu propia cuenta. Mantenla en privado y nunca incluyas una clave compartida en un plugin distribuido. No se aceptan cookies ni claves en los parámetros de consulta de la URL.

Seis endpoints

Las respuestas JSON correctas incluyen el resultado en { "data": ... }. Las descargas de resultados correctas siempre devuelven SRT.

Estimar y enviar

Ambos endpoints POST aceptan el mismo cuerpo JSON. Envía Content-Type: application/json.

{
  "fileName": "interview.srt",
  "subtitle": "1\n00:00:01,000 --> 00:00:03,000\nHello!\n",
  "targetLanguage": "zh",
  "modelTier": "plus"
}

subtitle, targetLanguage y modelTier son obligatorios. Elige explícitamente basic o plus; omitir modelTier devuelve 400 INVALID_REQUEST. El idioma de origen se detecta automáticamente. Obtén los códigos de idioma de destino en /api/v1/capabilities.

Las entradas opcionales de glossary contienen source y target. Las entradas opcionales de characters usan esos campos más gender (male o female) y aliases (una lista de nombres). Consulta las estructuras exactas en el esquema OpenAPI. Se rechazan los campos desconocidos.

Primero envía un POST a /api/v1/translations/estimate. Devuelve creditCost, availableCredits, sufficientCredits y el número de entradas de subtítulos. La estimación no crea tareas ni reserva créditos.

Crear una tarea

curl "$AST_BASE_URL/api/v1/translations" \
  -H "Authorization: Bearer $AST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: premiere-sequence-123-zh-v1' \
  --data-binary @request.json

Guarda el cuerpo JSON como request.json. Configura las dos variables de entorno con el origen del sitio y tu clave API.

Una tarea nueva devuelve 202 Accepted con data.id, data.creditCost, data.statusUrl y data.resultUrl. La cabecera Location apunta al endpoint de estado.

{
  "data": {
    "id": "6f476119-c02f-49a9-b61f-2b3327bd318c",
    "status": "pending",
    "fileName": "interview.srt",
    "modelTier": "plus",
    "targetLanguage": "zh",
    "creditCost": "1.00",
    "statusUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c",
    "resultUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c/result"
  }
}

Genera un Idempotency-Key para cada traducción que quieras iniciar y consérvalo al reintentar. Las solicitudes idénticas devuelven la misma tarea con HTTP 200. Un cuerpo diferente con la misma clave devuelve 409. Estas claves pertenecen a la cuenta y siguen siendo válidas al cambiar la clave API.

La cabecera admite 1–128 letras, números, puntos, guiones bajos, dos puntos o guiones. Si la tarea de una solicitud repetida ha caducado o se ha eliminado, se devuelve 410. Usa una clave nueva solo cuando quieras crear otra tarea facturable.

Progreso y resultados

Consulta la URL de estado cada 5 segundos. El estado es pending, processing, completed o failed. progress es un porcentaje o null si no está disponible; errorCode describe el fallo de la tarea.

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID" \
  -H "Authorization: Bearer $AST_API_KEY"

Asigna a TASK_ID el valor data.id de la respuesta de creación. Las respuestas de progreso incluyen los campos de tarea anteriores más progress y errorCode; ambos pueden ser null. Deja de consultar al recibir failed y muestra el error. Usa una nueva clave de tarea solo para iniciar deliberadamente otro intento de traducción.

Cuando termine, envía un GET a la URL del resultado y guarda el texto de la respuesta como archivo SRT. El tipo de respuesta es application/x-subrip; charset=utf-8. Omite includeOriginal o usa false para obtener solo la traducción. Añade ?includeOriginal=true para obtener subtítulos bilingües, con el original seguido de su traducción.

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID/result?includeOriginal=true" \
  -H "Authorization: Bearer $AST_API_KEY" \
  --output translated-bilingual.srt

El parámetro format no está admitido y devuelve 400 INVALID_REQUEST. Los errores se devuelven como JSON. Pedir el resultado antes de tiempo devuelve 409 TRANSLATION_NOT_READY con Retry-After: 5. Las traducciones fallidas devuelven 409 TRANSLATION_FAILED.

Descarga pronto los resultados terminados. Las reglas de eliminación y conservación del sitio también se aplican a las tareas de la API. Las tareas inexistentes o inaccesibles devuelven 404. Las tareas de la API aparecen en tu historial de subtítulos.

Créditos y límites

Las traducciones de la API usan tus créditos existentes y las tarifas por nivel de modelo y el cargo mínimo del sitio. No hay recargo adicional por usar la API. Estima el coste de cada archivo; la estimación no fija el precio. El creditCost de la tarea aceptada es la cantidad reservada.

Los créditos se reservan mientras la tarea espera o se procesa y se cobran una sola vez al completarse correctamente. Los créditos reservados siguen siendo válidos para esa tarea aunque su fecha de caducidad original pase mientras está en cola. Un fallo o una eliminación libera la reserva: los créditos no caducados vuelven al saldo disponible y los caducados siguen caducados. Una tarea fallida no tiene cargo de traducción. El endpoint de saldo devuelve cadenas decimales: availableCredits, reservedCredits y totalCredits (disponibles más reservados).

{ "data": { "availableCredits": "9.00", "reservedCredits": "1.00", "totalCredits": "10.00" } }

• 60 solicitudes por ventana de 60 segundos y cuenta, compartidas entre todas las claves.
• 10 solicitudes POST por ventana, compartidas entre estimaciones y envíos.
• Un máximo de 3 tareas de API pendientes o en procesamiento a la vez.
• Un archivo y un idioma de destino por tarea.
• 1 MiB de texto de subtítulos UTF-8; 2 MiB de JSON en total; 5000 entradas de subtítulos.
• La longitud del texto de cada entrada sigue la configuración del sitio (500 caracteres por defecto).
• 200 entradas de glosario; 100 personajes con hasta 20 alias cada uno. Los términos y nombres admiten un máximo de 200 caracteres.

Consulta los límites actuales en /api/v1/capabilities. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (tiempo Unix en segundos). Respeta Retry-After en las respuestas 429. El tiempo de traducción depende de la cola y del contenido enviado.

Errores y reintentos

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough available credits."
  },
  "requestId": "..."
}

400: entrada no válida. 401: clave no válida o revocada. 402: créditos insuficientes. 404: tarea inexistente o inaccesible. 409: conflicto de clave, traducción pendiente o fallida. 410: ha caducado la tarea de una solicitud repetida. 413: entrada demasiado grande. 415: se esperaba JSON. 422: subtítulos rechazados. 429: límite de solicitudes o tareas activas. 502: resultado incompleto. 503: servicio, modelo o cola no disponible.

Reintenta los errores de red y los fallos temporales del servidor con el mismo Idempotency-Key y cuerpo. Espera el tiempo indicado por Retry-After cuando esté presente. Tras un fallo definitivo de traducción, un nuevo intento deliberado requiere una clave nueva. Incluye X-Request-Id y el ID de la tarea al contactar con soporte.

Flujo de trabajo en Premiere Pro

1. Selecciona o exporta un archivo SRT.
2. Estima el coste y envíalo con el idioma de destino elegido.
3. Muestra el progreso de la tarea y guarda el SRT traducido.
4. Impórtalo en Premiere y colócalo en una pista de subtítulos.

Declara este origen en los permisos de red del manifiesto UXP y solicita acceso a archivos para leer y escribir SRT. Los endpoints públicos admiten CORS con autenticación Bearer sin cookies.

Usa entradas SRT numeradas, con marcas de tiempo HH:MM:SS,mmm, texto no vacío y líneas en blanco entre entradas. Se aplica la limpieza habitual de subtítulos: se eliminan las etiquetas de formato, se renumeran las entradas y puede filtrarse el texto secundario superpuesto. Se conservan las marcas de tiempo de las entradas retenidas. SRT no incluye los estilos de Premiere.

El acceso automático a una pista de subtítulos existente debe verificarse para tu versión de Premiere. La API acepta texto de subtítulos; transcribe el audio a subtítulos antes de enviarlo.