Appearance
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.envdos dois serviços. jobIdé UUID gerado pela API.publicationIdnão é usado sozinho como idempotency key: uma mesma publicação pode ter várias versões.- Toda mutação exige
jobId,attempte 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)
| Rota | Efeito |
|---|---|
PUT /api/projects/:projectId/publications/:id/video-engine | Salva remotion ou flow_web antes da geração de mídia |
POST /api/projects/:projectId/publications/:id/video-jobs | Cria snapshot e job Flow; aceita Idempotency-Key |
GET /api/projects/:projectId/publications/:id/video-jobs | Lista versões e estado persistido |
GET /api/projects/:projectId/publications/:id/video-jobs/:jobId | Detalhe, progresso, crédito observado e URL de prévia temporária |
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/approve | Valida revisão vigente e promove candidato para videoKey |
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/cancel | Solicita parada cooperativa, sem alterar ativo aprovado |
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/resume | Retoma após intervenção do operador, sem repetir gerações ambíguas |
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/manual-upload | Fallback: cria ticket de upload de MP4 exportado manualmente |
POST /api/projects/:projectId/publications/:id/video-jobs/:jobId/manual-upload/complete | Finaliza 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 mudouapproved, 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
- Worker pede
POST /internal/shorts/jobs/:jobId/upload-ticketcom tamanho,sha256econtentType=video/mp4. - API emite URL PUT assinada para chave de candidato derivada de
ownerId,projectId,publicationIdejobId, com vencimento curto. Nunca aceitar chave enviada pelo worker. - Worker faz upload do MP4 diretamente ao S3 e chama
POST /internal/shorts/jobs/:jobId/upload-complete. - 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. - Se válido, o job vira
needs_review. A aprovação confere novamente owner, status não publicado,briefingHashatual e objeto existente; então gravavideoKey,videoevideoOriginem 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ódigo | Ação |
|---|---|
SESSION_EXPIRED, MFA_REQUIRED, CHALLENGE_REQUIRED | needs_operator; renovar sessão manualmente |
UI_CHANGED | Pausar, guardar evidência sem segredos e atualizar adaptador |
CREDITS_UNAVAILABLE, BUDGET_EXCEEDED | Parar antes de nova geração; revisar orçamento |
GENERATION_REJECTED | Mostrar razão da UI, preservar clipes anteriores |
DOWNLOAD_FAILED | Tentar baixar novamente sem gerar outro clipe |
INVALID_MEDIA, STALE_BRIEFING | Não promover; corrigir/exportar novo candidato |
WORKER_UNAVAILABLE | Job 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.