Skip to content

Contratos entre Atpares e atpares-shorts ​

Estado: proposta futura suspensa; rotas e tabelas ainda não implementadas. Nenhuma rota pública do dashboard ou da API Atpares será criada nesta fase. A API Atpares seria a autoridade sobre usuário, publicação, banco e S3. O serviço de navegador só executa jobs autorizados.

Identificadores e autenticação ​

  • O painel usa a autenticação normal da API Atpares; nunca chama o worker.
  • API e worker se comunicam pela rede Docker privada com Authorization: Bearer <SHORTS_SERVICE_TOKEN>. O token vive apenas nos .env dos dois serviços.
  • jobId é UUID gerado pela API. publicationId não é usado sozinho como idempotency key: uma mesma publicação pode ter várias versões.
  • Toda mutação exige jobId, attempt e versão de estado esperada. A API rejeita callbacks antigos, duplicados ou referentes a outro projeto/publicação.
  • Tokens de serviço nunca são aceitos em rotas públicas. O worker não pode escolher o destino S3, o proprietário ou o status de publicação.

Rotas públicas da API Atpares (propostas) ​

RotaEfeito
PUT /api/projects/:projectId/publications/:id/video-engineSalva remotion ou flow_web antes da geração de mídia
POST /api/projects/:projectId/publications/:id/video-jobsCria snapshot e job Flow; aceita Idempotency-Key
GET /api/projects/:projectId/publications/:id/video-jobsLista versões e estado persistido
GET /api/projects/:projectId/publications/:id/video-jobs/:jobIdDetalhe, progresso, crédito observado e URL de prévia temporária
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/approveValida revisão vigente e promove candidato para videoKey
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/cancelSolicita parada cooperativa, sem alterar ativo aprovado
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/resumeRetoma após intervenção do operador, sem repetir gerações ambíguas
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/manual-uploadFallback: cria ticket de upload de MP4 exportado manualmente
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/manual-upload/completeFinaliza upload manual e passa pela mesma validação

POST video-jobs exige publicação social não publicada, texto salvo e videoEngine=flow_web, projeto autorizado e orçamento agregado disponível. Não exige imagem do post se o briefing não usar imagem. O POST :id/video atual segue exclusivo para Remotion e rejeita uma publicação marcada como flow_web, evitando duas produções paralelas. Trocar o motor ou alterar um campo incluído no briefingHash retira a aprovação do vídeo atual antes de qualquer publicação agendada. O arquivo antigo segue disponível no histórico para auditoria, sem ficar em videoKey.

Exemplo de pedido do painel:

json
{
  "targetSeconds": 32,
  "sceneCount": 4,
  "generationLimit": 8,
  "creditBudget": 160,
  "notes": "Narração em português brasileiro; mostrar o produto com a marca correta."
}

generationLimit é o limite de tentativas de gerar clipes, inclusive variações. creditBudget é um teto solicitado, não garantia de cobrança exata: o preço depende do modelo, da duração e do número de saídas que a UI mostrar. Se o preço não estiver legível, o worker pausa antes do gasto. A API também reserva o orçamento do job contra tetos diário/mensal da conta; devolve a reserva não utilizada ao concluir, sem afirmar que esse número é o saldo oficial do Google.

Contrato privado API → worker ​

POST /api/internal/jobs recebe somente { "jobId": "uuid" } e devolve 202 { "accepted": true }. Repetir o mesmo jobId não cria outra execução. O worker obtém os dados em GET /internal/shorts/jobs/:jobId na API:

json
{
  "jobId": "uuid",
  "attempt": 1,
  "publicationId": "uuid",
  "briefingHash": "sha256",
  "format": { "aspectRatio": "9:16", "targetSeconds": 32, "language": "pt-BR" },
  "plan": {
    "title": "Título de trabalho",
    "visualRules": "Direção visual e limites da marca",
    "audioRules": "Voz, ritmo e efeitos",
    "scenes": [
      { "index": 0, "seconds": 8, "prompt": "...", "spokenText": "..." }
    ]
  },
  "references": [
    { "id": "logo", "url": "https://...", "mimeType": "image/png", "sha256": "..." }
  ],
  "limits": { "generationCount": 8, "creditBudget": 160 }
}

A API gera URLs GET curtas para referências. O worker baixa e confere checksum antes de enviar à interface. Prompts são snapshot, para não mudar no meio do job. URLs assinadas não entram em logs nem no banco. O worker não aceita instruções arbitrárias de shell, URLs de destino ou credenciais no briefing.

Eventos worker → API ​

POST /internal/shorts/jobs/:jobId/events com attempt, sequence, state, stage, progress, detail, flowProjectRef opcional e creditUsageObserved opcional. A API só avança sequence; evento repetido recebe 200 sem efeito. detail é texto curto seguro para mostrar ao usuário. Estados e estágios internos completos ficam no banco. O painel acompanha via notificação existente e também pode consultar o job após reconectar.

Estágios visíveis sugeridos: session, assets, generating, assembling, downloading, uploading, validating, review. Cada um pode ser waiting, running, ready ou failed sem alterar o contrato de status da publicação. Evitar mapear diretamente todos eles em VIDEO_STAGES, que são estágios do pipeline Remotion.

Máquina de estados ​

mermaid
stateDiagram-v2
  [*] --> queued
  queued --> running
  running --> needs_operator
  needs_operator --> queued: retomada explícita
  running --> uploading
  uploading --> validating
  validating --> needs_review
  needs_review --> approved: aprovação humana
  queued --> cancelled
  running --> cancelled: parada cooperativa
  needs_operator --> cancelled
  running --> failed
  uploading --> failed
  validating --> failed
  needs_review --> stale: publicação mudou
  queued --> stale: publicação mudou

approved, failed, cancelled e stale são terminais para aquele job. Uma nova tentativa após falha cria outro jobId ligado ao anterior, para preservar custo e histórico. Na retomada de needs_operator, o worker primeiro reconcilia os clipes existentes no projeto Flow; caso não consiga determinar se uma geração anterior terminou, mantém o job parado para decisão humana.

Entrega de mídia ​

  1. Worker pede POST /internal/shorts/jobs/:jobId/upload-ticket com tamanho, sha256 e contentType=video/mp4.
  2. API emite URL PUT assinada para chave de candidato derivada de ownerId, projectId, publicationId e jobId, com vencimento curto. Nunca aceitar chave enviada pelo worker.
  3. Worker faz upload do MP4 diretamente ao S3 e chama POST /internal/shorts/jobs/:jobId/upload-complete.
  4. API lê metadados e faz validação com ffprobe/decoder: contêiner MP4, stream de vídeo H.264, áudio AAC quando previsto, orientação 9:16, duração aprovada para as redes de destino, tamanho máximo configurado e checksum. Critérios de rede devem ser centralizados e atualizados quando as plataformas mudarem.
  5. Se válido, o job vira needs_review. A aprovação confere novamente owner, status não publicado, briefingHash atual e objeto existente; então grava videoKey, video e videoOrigin em uma transação. A prévia serve por URL assinada ou endpoint autenticado.

Ao aprovar, guardar a chave imutável do candidato como ativo final ou copiá-la para outra chave versionada. Nunca sobrescrever o objeto de um job anterior. O videoKey atual já é lido pelo publicador, então o envio social não recebe um segundo caminho de mídia. Registrar cada ativo em video_assets; o upload manual usa a mesma chave de candidato, validação e aprovação do job.

Erros esperados ​

CódigoAção
SESSION_EXPIRED, MFA_REQUIRED, CHALLENGE_REQUIREDneeds_operator; renovar sessão manualmente
UI_CHANGEDPausar, guardar evidência sem segredos e atualizar adaptador
CREDITS_UNAVAILABLE, BUDGET_EXCEEDEDParar antes de nova geração; revisar orçamento
GENERATION_REJECTEDMostrar razão da UI, preservar clipes anteriores
DOWNLOAD_FAILEDTentar baixar novamente sem gerar outro clipe
INVALID_MEDIA, STALE_BRIEFINGNão promover; corrigir/exportar novo candidato
WORKER_UNAVAILABLEJob permanece em fila e dispatcher tenta novamente

Tempo esgotado não implica repetição automática de geração. A API distingue pedido não entregue, execução incerta e resultado pronto sem upload.