Integração de API

API de tradução de vídeo para operações de lançamento multirregião

Localize um vídeo de origem em várias saídas prontas para o mercado com automação orientada por status, isolamento de falhas por locale e fluxos de rollout controlado.

Problema

Os lançamentos globais costumam falhar na sincronização, não na qualidade da tradução: o idioma principal é publicado primeiro enquanto as variantes regionais atrasam e o timing da campanha se quebra.

Resultado com a Ssemble

A Ssemble permite operações de traduzir-uma-vez, localizar-muitas, com rastreamento de estado específico por locale, para que as equipes lancem em ondas controladas e recuperem falhas parciais rapidamente.

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

Crie o manifesto de tradução: source, lista de locales, política de rollout e comportamento de fallback.

2) Processamento

Envie requisições de criação específicas por locale e persista um parent release id para rastreabilidade de ponta a ponta.

3) Poll / Webhook

Acompanhe o estado de cada locale de forma independente para identificar rapidamente cenários de sucesso parcial e falha parcial.

4) Publicação

Publique os locales que passam nos gates de QA/conformidade e reenfileire os locales com falha usando uma estratégia de retry limitado.

Exemplos de endpoint

POST /shorts/create— Criar jobs de processamento específicos por locale
GET /shorts/:id/status— Acompanhar o estado do ciclo de vida de cada locale
GET /shorts/:id— Buscar a saída localizada concluída para o lançamento

Orientações de autenticação

Mantenha as API keys e os controles de rollout apenas em serviços de backend. Segmente as chaves por ambiente e restrinja rigorosamente o acesso ao rollout de produção.

Rate limits e retries

Enfileire os envios por locale em lotes controlados, não em picos de fan-out completo. Use backoff exponencial em 429/5xx e limite os retries.

Exemplo de requisição

POST /shorts/create
{
  "fileUrl": "https://cdn.example.com/master-campaign.mp4",
  "start": 30,
  "end": 420,
  "language": "ko",
  "captionLanguage": "ja",
  "preferredLength": "under60sec",
  "layout": "auto"
}

Exemplo de resposta

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

Exemplo de cenário de erro

500 Internal Server Error
{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred. Please try again.",
    "details": null
  }
}

Versionamento

Registre os metadados de schema/versão de cada requisição por locale, para que as regressões entre locales sejam diagnosticáveis após mudanças na API.

Suporte

Persista parent release id + locale + requestId em cada transição de status para uma recuperação rápida de incidentes em lançamentos parciais.

Início rápido

Defina a matriz de locales e a estratégia de rollout na configuração do backend.
Crie uma requisição de processamento por locale usando os campos language/captionLanguage.
Faça polling do status e atualize o quadro de lançamento até que cada locale esteja terminal.
Busque as saídas concluídas e execute verificações de QA específicas por locale.
Publique imediatamente os locales aprovados e roteie os locales com falha para uma fila de retry limitado.

Abrir a documentação do fluxo de tradução

Iniciar integração

1) Autenticação

Padrões de API key apenas no servidor

2) Ciclo de vida do status

Modelo queued/processing/completed/failed

3) Estratégia de rate limit

Headers, janelas de reset e disciplina de polling

4) Taxonomia de erros

Tratamento programático por error.code

Fluxo de trabalho em 3 etapas

Ingira um único ativo de origem com a matriz de locales de destino e a política de rollout.
Processe os jobs por locale de forma assíncrona, com rastreamento de status independente para cada locale.
Publique os locales concluídos por filas regionais, enquanto os locales com falha são roteados para retries controlados.

Por que as equipes escolhem a Ssemble

Projetada para equipes de canais regionais em que a coordenação de lançamento é tão crítica quanto a qualidade do conteúdo.
Isola as falhas por locale, de modo que um problema não bloqueie o lançamento inteiro de uma campanha.
Funciona com a automação de publicação para fluxos de distribuição follow-the-sun.

Próximo passo

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

FAQ

Como evitamos que um locale bloqueie todas as regiões?

Use máquinas de estado por locale e gates de lançamento para que cada locale possa ser publicado de forma independente, a menos que a política exija a sincronização de todos os locales.

Devemos enviar todos os locales de uma vez?

Geralmente não. O batching controlado protege os orçamentos de rate limit e simplifica a triagem de incidentes quando o caminho de um locale se degrada.

Qual é o payload mínimo de observabilidade?

Rastreie parent release id, código de locale, requestId, transições de status, error code e retry count para cada job.

Quais erros devem gerar retry automático?

Faça retry de erros de transporte transitórios, 429 e 5xx com backoff. Falhe rapidamente em erros de validação e roteie para correção de configuração/dados.

A tradução e a publicação podem ser separadas?

Sim. Muitas equipes mantêm a conclusão da tradução e a publicação em canais em filas separadas para melhor controle e segurança de rollback.

Isso garante resultados iguais em todos os locales?

Nenhuma garantia deve ser presumida. Meça o tempo de conclusão, a taxa de falhas e a taxa de aprovação em QA por locale e ajuste a política de rollout conforme necessário.