Integración de API

API de subtítulos de vídeo para automatización de alto volumen y segura ante QA

Automatiza la generación de subtítulos con estados de job explícitos, controles de idioma y reintentos seguros para producción, pensados para equipos que entregan grandes volúmenes de formato corto.

Problema

A escala, las operaciones de subtitulado suelen fallar en QA y consistencia: las comprobaciones manuales de timing, los desajustes de idioma y las revisiones repetidas se convierten en un cuello de botella oculto de producción.

Resultado con Ssemble

Ssemble permite un procesamiento de subtítulos determinista con contratos claros de status/error para que los equipos de ingeniería automaticen el QA rutinario y solo escalen los verdaderos casos límite.

Aspectos esenciales de la implementación

Base URL: https://aiclipping.ssemble.com/api/v1

Arquitectura de integración (ingesta → procesamiento → poll/webhook → publicación)

1) Ingesta

Almacena source URL/file URL más los campos de configuración de subtítulos (language, captionLanguage, templateId, preferredLength).

2) Procesamiento

Llama a POST /shorts/create con parámetros de subtítulos y persiste requestId + correlation id.

3) Poll / Webhook

Consulta GET /shorts/:id/status (o el endpoint de list) a una cadencia controlada hasta el estado terminal.

4) Publicación

Recupera los assets completados, ejecuta comprobaciones automatizadas de QA de subtítulos y entrégalos a la cola de publicación.

Ejemplos de endpoints

POST /shorts/create— Crear un short subtitulado con opciones de idioma/plantilla
GET /shorts/:id/status— Seguir la etapa de procesamiento y failureReason
GET /shorts— Monitorizar jobs en lote sin el sobrecoste de una llamada por job

Guía de autenticación

Usa X-API-Key solo del lado del servidor. Mantén claves separadas para staging y producción para reducir el riesgo de rotación y el acoplamiento entre entornos.

Rate limits y reintentos

Evita bucles de polling ajustados. Usa comprobaciones de estado en lote, cachea los resultados estables y, ante un 429, sigue reset/retryAfter antes de los reintentos con backoff.

Ejemplo de request

POST /shorts/create
{
  "url": "https://www.youtube.com/watch?v=abc123",
  "start": 0,
  "end": 540,
  "language": "en",
  "captionLanguage": "en",
  "templateId": "660b8531aedb346bbe26eb43",
  "preferredLength": "under60sec",
  "layout": "auto"
}

Ejemplo de response

200 OK
{
  "data": {
    "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "processing",
    "creditsUsed": 1,
    "estimatedCompletionTime": "2026-03-10T06:05:00.000Z"
  }
}

Ejemplo de escenario de error

400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid captionLanguage code",
    "details": { "captionLanguage": "xx" }
  }
}

Versionado

Fija las versiones de los endpoints y valida los esquemas de request en CI para detectar la desviación de integración antes del release de producción.

Soporte

Para los jobs fallidos, conserva el hash del payload del request + requestId + error.details para que los equipos puedan separar las entradas erróneas de los incidentes del pipeline.

Quickstart

Crea SSEMBLE_API_KEY en el dashboard y guárdalo en el runtime del backend.
Envía un payload mínimo de POST /shorts/create con source + timing + idioma.
Haz poll de GET /shorts/:id/status cada 10 segundos hasta completed/failed/cancelled.
Obtén la salida de GET /shorts/:id y ejecuta las assertions de QA de subtítulos.
Añade reintentos acotados para 429/5xx transitorios y enruta los jobs agotados a una DLQ.

Empezar con la documentación del endpoint de subtítulos

Iniciar integración

1) Configuración de auth

Manejo seguro de claves y errores de auth

2) Endpoint de create

Campos del request body y validación

3) Códigos de error

Taxonomía de errores reintentables y terminales

4) Ejemplos

Snippets de integración cURL/JavaScript/Python

Flujo de trabajo en 3 pasos

Captura los medios de origen y la configuración de subtítulos (idioma/plantilla/longitud preferida) en tu modelo de cola.
Envía requests de create, monitoriza las transiciones de estado y enruta los estados terminales automáticamente.
Publica las salidas completadas tras comprobaciones automatizadas de legibilidad y política de subtítulos.

Por qué los equipos eligen Ssemble

Diseñado para equipos donde la consistencia de subtítulos afecta a la calidad de marca y a la retención del espectador.
Da soporte a un enrutamiento de QA basado en estados en lugar de una clasificación manual de bandeja de entrada.
Escala entre múltiples marcas externalizando la política de estilo/idioma en tu capa de integración.

Siguiente paso

Abrir el quickstart de la API de subtítulos Ver precios Documentación para desarrolladores

FAQ

¿Qué suele causar los fallos del pipeline de subtítulos?

Las causas comunes son ventanas de timing inválidas, source URLs no disponibles y valores de idioma/plantilla inválidos. Valídalos antes de encolar.

¿Deberíamos hacer poll de cada job de forma individual a escala?

Solo para volúmenes bajos. A mayor volumen, la monitorización agregada de estados reduce la carga de la API y mejora la fiabilidad.

¿Cómo hacemos que los reintentos sean seguros?

Reintenta solo condiciones transitorias (429/5xx/timeouts) y usa fingerprints de request para evitar el procesamiento duplicado.

¿Los tiempos de finalización son fijos?

No. La finalización puede variar según la duración del origen, las condiciones de la cola y las opciones. Trata la ETA como orientativa.

¿Podemos imponer estilos de subtítulos por cliente?

Sí. Mantén los mapeos de estilo/plantilla en tu capa de configuración e inyéctalos por tenant al crear el request.

¿Qué alertas de producción importan más?

Monitoriza la tasa de fallos por error code, la antigüedad de la cola y el recuento de procesamientos atascados para detectar incidencias a tiempo.