Integração de API

API de legendas de vídeo para automação de legendas em alto volume e com QA seguro

Automatize a geração de legendas com estados de job explícitos, controles de idioma e retries seguros para produção, voltados a equipes que entregam grandes volumes em formato curto.

Problema

Em escala, as operações de legenda costumam falhar em QA e consistência: verificações manuais de sincronização, incompatibilidade de idioma e revisões repetidas tornam-se um gargalo de produção oculto.

Resultado com a Ssemble

A Ssemble permite o processamento determinístico de legendas com contratos claros de status/erro, para que as equipes de engenharia possam automatizar o QA de rotina e escalar apenas os casos limítrofes reais.

Fundamentos de implementação

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

Arquitetura de integração (ingestão → processamento → polling/webhook → publicação)

1) Ingestão

Armazene a source URL/file URL mais os campos de configuração de legenda (language, captionLanguage, templateId, preferredLength).

2) Processamento

Chame POST /shorts/create com os parâmetros de legenda e persista o requestId + correlation id.

3) Poll / Webhook

Consulte GET /shorts/:id/status (ou o endpoint de list) em uma cadência controlada até o estado terminal.

4) Publicação

Recupere os ativos concluídos, execute verificações automatizadas de QA de legendas e encaminhe para a fila de publicação.

Exemplos de endpoint

POST /shorts/create— Criar um short legendado com opções de idioma/template
GET /shorts/:id/status— Acompanhar a etapa de processamento e o failureReason
GET /shorts— Monitorar jobs em lote sem a sobrecarga de uma chamada por job

Orientações de autenticação

Use apenas a X-API-Key no lado do servidor. Mantenha chaves separadas para staging e produção, a fim de reduzir o risco de rotação e o acoplamento entre ambientes.

Rate limits e retries

Evite loops de polling muito frequentes. Use verificações de status em lote, faça cache de resultados estáveis e, em caso de 429, siga reset/retryAfter antes dos retries com backoff.

Exemplo de requisição

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"
}

Exemplo de resposta

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

Exemplo de cenário de erro

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

Versionamento

Fixe as versões de endpoint e valide os schemas de requisição no CI para detectar desvios de integração antes do lançamento em produção.

Suporte

Para jobs com falha, guarde o hash do payload da requisição + requestId + error.details, para que as equipes possam separar entradas inválidas de incidentes do pipeline.

Início rápido

Crie a SSEMBLE_API_KEY no dashboard e armazene-a no runtime do backend.
Envie um payload mínimo de POST /shorts/create com source + timing + language.
Faça polling em GET /shorts/:id/status a cada 10 segundos até completed/failed/cancelled.
Busque a saída em GET /shorts/:id e execute as asserções de QA das legendas.
Adicione retries limitados para 429/5xx transitórios e roteie os jobs esgotados para a DLQ.

Começar pela documentação do endpoint de legendas

Iniciar integração

1) Configuração de autenticação

Manuseio seguro de chaves e erros de autenticação

2) Endpoint de criação

Campos do corpo da requisição e validação

3) Códigos de erro

Taxonomia de erros retryable e terminal

4) Exemplos

Trechos de integração em cURL/JavaScript/Python

Fluxo de trabalho em 3 etapas

Capture a mídia de origem e as configurações de legenda (idioma/template/comprimento preferido) no seu modelo de fila.
Envie as requisições de criação, monitore as transições de status e roteie os estados terminais automaticamente.
Publique as saídas concluídas após verificações automatizadas de legibilidade e conformidade das legendas.

Por que as equipes escolhem a Ssemble

Projetada para equipes em que a consistência das legendas afeta a qualidade da marca e a retenção do espectador.
Oferece suporte a roteamento de QA orientado por estados, em vez de triagem manual na caixa de entrada.
Escala entre várias marcas ao externalizar a política de estilo/idioma na sua camada de integração.

Próximo passo

Abrir o início rápido da API de legendas Ver preços Documentação para desenvolvedores

FAQ

O que costuma causar falhas no pipeline de legendas?

Causas comuns são janelas de timing inválidas, source URLs indisponíveis e valores de idioma/template inválidos. Valide isso antes de enfileirar.

Devemos fazer polling de cada job individualmente em escala?

Apenas para baixo volume. Em volumes maiores, o monitoramento agregado de status reduz a carga na API e melhora a confiabilidade.

Como tornamos os retries seguros?

Faça retry apenas de condições transitórias (429/5xx/timeouts) e use fingerprints de requisição para evitar processamento duplicado.

Os tempos de conclusão são fixos?

Não. A conclusão pode variar conforme o comprimento da origem, as condições da fila e as opções. Trate o ETA como orientativo.

Podemos impor estilos de legenda por cliente?

Sim. Mantenha os mapeamentos de estilo/template na sua camada de configuração e injete-os por tenant na criação da requisição.

Quais alertas de produção são mais importantes?

Monitore a taxa de falhas por error code, a idade da fila e as contagens de jobs travados em processamento para detectar incidentes cedo.