Adicionar texto a vídeos via API: fluxo de trabalho de legendas e sobreposições

Por que o texto em vídeo é um problema de design de API, e não apenas de prompt

Adicionar texto a um vídeo gerado parece uma questão de mudar uma linha no prompt: descreva a legenda, envie a requisição e receba um clipe com texto. Mas, na prática, assim que você precisa que as legendas sejam legíveis, temporizadas, localizáveis ou reutilizáveis entre cenas, o prompt deixa de ser a parte interessante. A arquitetura passa a ser.

Há dois caminhos viáveis, e eles levam a bases de código diferentes:

• Texto nativo na geração. Você pede ao modelo de vídeo que renderize o texto como parte da cena. Uma requisição, um asset, nenhum pós-processamento.
• Asset limpo mais sobreposição. Você gera primeiro o asset sem texto (ou pede uma composição sem texto) e depois compõe legendas e sobreposições em uma segunda etapa de renderização.

Por que isso não é apenas uma questão estética? Porque tudo a jusante depende dessa escolha. Se o texto está nos pixels gerados, você não consegue facilmente restilizar, traduzir, alinhar temporalmente com a fala ou corrigir erros de digitação sem regenerar o clipe. Se o texto está em uma sobreposição separada, você controla o layout, a fonte e a temporização, mas agora precisa manter seu próprio renderizador e ter uma requisição a mais no pipeline.

O restante deste guia trata o texto em vídeo como aquilo em que ele geralmente se transforma em produção: um problema de dados (qual texto, onde, quando) somado a um problema de renderização (quem o desenha). Quando você separa esses dois, as chamadas de API ficam diretas e você pode trocar de backend de geração sem reescrever a lógica de legendas.

Um modelo mental útil é sempre distinguir três coisas: conteúdo (o texto em si), temporização (quando ele aparece) e apresentação (fonte, posição, estilo). A geração nativa comprime os três em uma etapa opaca. A sobreposição mantém os três explícitos e editáveis. Nenhuma das duas é universalmente melhor; o objetivo é saber a qual você está se comprometendo antes de escrever a integração.

Caminho um: texto nativo na tela via prompt na geração

Texto nativo significa que o modelo de geração desenha os caracteres nos quadros do vídeo. Você recebe um único asset de saída com o texto já embutido, e o pipeline permanece curto: montar o prompt, enviar, consultar o status, entregar.

O que colocar no prompt

A tipografia renderizada pelo modelo é mais imprevisível que texto composto, então trate o prompt como uma instrução estreita, e não como o lugar de descrever um sistema de design inteiro. Recomendações práticas:

• Mantenha o texto curto. Algumas palavras por tomada. Frases longas tendem a causar deriva de ortografia e layout apertado.
• Coloque strings literais entre aspas. Se o texto precisa aparecer exatamente, coloque-o entre aspas e exija aquele texto exato. Descrições vagas produzem resultados vagos.
• Declare posição e estilo explicitamente. “Texto branco grande centralizado no terço inferior” é acionável. “Um título bonito” não é.
• Um elemento de texto por tomada. Pedir título, subtítulo e marca d'água no mesmo clipe multiplica os modos de falha.
• Declare o idioma. Se o texto não for em inglês, diga isso, porque a cobertura de glifos varia.

O que esperar de volta

Trate a saída como rascunho, não como especificação. Mesmo bons resultados podem apresentar glifos deformados, espaçamento inconsistente ou oclusão parcial pelo movimento. Sempre inspecione os quadros renderizados antes de entregar; uma verificação programática barata somada a uma olhada humana nos quadros com texto do início e do fim pega a maioria dos problemas.

Quando este caminho vence

Texto nativo é a escolha padrão correta quando o texto é incidental e atmosférico: letreiros em uma rua de fundo, um logotipo estilizado em um produto, um cartão de título curto que você aceita regenerar se sair errado. Também vence quando você realmente não pode arcar com uma segunda etapa de renderização, como em fluxos com prazo apertado em que uma requisição por clipe é o orçamento.

O custo é o controle. Qualquer mudança de redação, estilo ou temporização significa uma nova requisição de geração, e os resultados não são determinísticos entre tentativas. Projete seus prompts e seu armazenamento para que clipes regenerados substituam os antigos de forma limpa.

Caminho dois: gerar asset limpo e compor o texto você mesmo

O caminho de sobreposição divide o trabalho em dois. Primeiro você gera um asset deliberadamente sem texto. Depois compõe legendas e sobreposições por cima, usando um serviço de renderização ou seu próprio pipeline de mídia.

Primeiro, gere o asset limpo

Peça uma composição sem texto: descreva a cena, o sujeito, o movimento de câmera e a iluminação, e evite explicitamente pedir texto na tela. Se o modelo tende a inventar letreiros ou texto de UI, mencione que o quadro deve conter texto ilegível. A saída aqui é um asset base — uma entrada estável que você pode reutilizar em muitas variantes de texto.

Composição posterior

A etapa de sobreposição consome duas entradas: o asset base e uma carga estruturada de legendas/sobreposições. Como você controla o renderizador, você obtém propriedades que o prompt não pode garantir:

• Fontes e tamanhos determinísticos. A mesma carga renderiza de forma idêntica toda vez, o que importa para consistência de marca.
• Temporização precisa. As legendas podem se alinhar com precisão de quadro à fala, à batida da música ou aos cortes de cena.
• Áreas seguras e regras de layout. Você pode impor margens, evitar rostos e sujeitos principais e manter o texto dentro de áreas seguras específicas de cada plataforma.
• Iteração barata. Corrigir um erro de digitação ou traduzir uma legenda é re-renderizar a sobreposição, não regenerar o vídeo.
• Composibilidade. Marcas d'água, faixas de terço inferior e legendas podem ser estratificadas de forma independente e alternadas por saída.

Trade-offs

O caminho de sobreposição troca dependência do modelo por complexidade de pipeline. Você adiciona uma segunda requisição, precisa de algum lugar para armazenar os assets intermediários e passa a manter a configuração de renderização. Em troca, o texto se torna dados que você pode versionar, testar e substituir. Para qualquer coisa com necessidade real de legenda — legendas de acessibilidade, variantes multilíngues, formatos sociais baseados em template — essa troca quase sempre vale a pena.

Um padrão prático é renderizar as sobreposições de forma não destrutiva: mantenha o asset base e a carga de legendas como fonte única de verdade, e trate o vídeo composto como um artefato derivado que você sempre pode regenerar.

Projete uma carga de legendas que sobreviva aos dois caminhos

Se você projetar bem os dados de legenda, a escolha entre geração nativa e sobreposição se torna um detalhe de renderização, não uma reescrita. O objetivo é uma carga única que possa tanto ser serializada em um prompt para texto nativo quanto alimentar um renderizador para sobreposições.

Campos principais

Modele cada elemento de texto como um objeto, mantendo conteúdo, temporização e apresentação separados:

{
  "track": "captions",
  "items": [
    {
      "text": "Everything you need to know",
      "start": 0.0,
      "end": 2.4,
      "style": { "role": "title", "align": "center", "position": "lower_third" },
      "lang": "en"
    }
  ]
}

Decisões de design essenciais:

• Tempo em segundos, como ponto flutuante. Use uma única base de tempo no projeto inteiro e converta para quadros apenas na renderização.
• Estilo por papel, não por valores absolutos. Nomeie papéis como title, caption e lower_third, e resolva-os para fontes e tamanhos no renderizador. Isso torna a carga portátil entre formatos.
• Nomes de trilha. Separe as trilhas captions, titles e watermark, para poder habilitar ou desabilitar trilhas por saída.
• Tag de idioma por item. Necessária tanto para seleção de fonte quanto para canais de tradução posteriores.
• Nenhuma informação de apresentação embutida no campo de texto. Nunca coloque dicas de estilo no texto; para isso existe o objeto de estilo.

Alimente os dois caminhos a partir de um único schema

Para geração nativa, escreva um pequeno adaptador que selecione os itens mais importantes e os converta em instruções de prompt: o texto literal, sua posição e um descritor de estilo. Faça esse adaptador com perdas de propósito — a renderização nativa não consegue seguir uma trilha de legendas completa de qualquer forma.

Para sobreposições, passe a carga ao renderizador, que resolve papéis e posições e desenha cada item dentro da sua janela de tempo.

O retorno é: seu código de aplicação constrói um objeto de legenda, e alternar de nativo para sobreposição (ou voltar para um clipe específico) é uma mudança de configuração, não uma migração de dados.

Uma requisição de sobreposição funcional, passo a passo

A seguir está a sequência do caminho de sobreposição, expressa como passos de API. Os nomes exatos de endpoints e parâmetros dependem do provedor, mas a forma é estável, e uma abstração fina a mantém estável entre backends.

Passo 1: enviar a geração do asset limpo

POST /video/generations
{
  "prompt": "A slow dolly shot through a modern office, no on-screen text, natural light",
  "duration_seconds": 6,
  "aspect_ratio": "16:9"
}

Mantenha o prompt sem texto e armazene o identificador de tarefa retornado.

Passo 2: consultar até o asset estar pronto

GET /video/generations/{job_id}

Consulte com backoff em vez de um loop apertado. Trate estados como queued, running, succeeded e failed como cidadãos de primeira classe no código, e persista a URL ou o ID do asset resultante, para que uma queda não perca o resultado da geração.

Passo 3: enviar a renderização da sobreposição

POST /video/overlays
{
  "source_asset": "asset_abc123",
  "captions": {
    "track": "captions",
    "items": [
      { "text": "Shipping today", "start": 0.4, "end": 2.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" },
      { "text": "No rebuild required", "start": 2.2, "end": 4.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" }
    ]
  }
}

Observe que a requisição de sobreposição carrega apenas o asset de origem e os dados de texto. Ela não regenera o asset, e é exatamente isso que torna a iteração barata.

Passo 4: recuperar o resultado composto

Consulte a tarefa de sobreposição da mesma forma que a tarefa de geração, e depois busque o asset final. Armazene o asset base, a carga de legendas e a saída juntos, para que a composição seja reproduzível.

No código, envolva os passos 1–4 em uma função que recebe um prompt e uma carga de legendas e retorna o asset final. Essa função é a sua interface real; os endpoints individuais são detalhes de implementação substituíveis.

Verificações de confiabilidade antes de publicar

Pipelines de texto em vídeo falham de formas silenciosas: legendas cortadas, linhas mal traduzidas, regenerações que nunca são limpas. Adicione verificações antes que os usuários as vejam.

Valide o texto renderizado

• Caminho nativo: amostre quadros no início e no fim de cada janela de texto e inspecione-os. Automatize verificações básicas de legibilidade quando possível, mas mantenha uma etapa de revisão humana para textos voltados ao cliente, porque a tipografia do modelo pode degradar de forma imprevisível.
• Caminho de sobreposição: valide a carga antes de renderizar — temporizações não sobrepostas para cada item, dentro da duração do clipe, usando idiomas e papéis suportados. Após a renderização, faça amostragem de quadros nos limites dos itens para confirmar que nada foi cortado.

Torne as retentativas seguras

• Chaves de idempotência nas requisições de envio, para que chamadas de rede repetidas não criem tarefas de geração duplicadas.
• Uma máquina de estados por tarefa: queued → running → succeeded/failed, persistida, para que um reinício retome em vez de recomeçar.
• Consulta limitada, com backoff e timeout, apresentando uma falha clara em vez de um loop infinito.
• Armazene os assets intermediários. Se a etapa de sobreposição falhar, você não deve gastar dinheiro regenerando um asset que já tem.

Controle o custo da cadeia inteira

O caminho de sobreposição tem duas etapas cobradas — geração e renderização — então monitore ambas. Acompanhe com que frequência você regenera assets versus apenas re-renderizar sobreposições; se a regeneração de assets domina, sua divisão entre nativo e sobreposição pode estar errada para essa carga de trabalho. Faça cache do asset final por (asset base, carga de legendas), para que requisições repetidas para a mesma saída sejam gratuitas.

Observabilidade

Registre o prompt, o hash da carga de legendas, o ID da tarefa e o ID do asset final juntos. Quando um usuário relatar um erro de legenda, você vai querer identificar em segundos se o problema está na geração, nos dados ou na renderização. Mantenha a carga de legendas como fonte única de verdade versionada, para que você sempre possa explicar o que o renderizador foi instruído a desenhar.

Escolha seu fluxo de trabalho padrão

Use isto como regra inicial e revise conforme o produto crescer.

Escolha texto nativo quando o texto for decorativo ou incidental, a redação for curta, você aceitar regenerar como forma de corrigir erros e adicionar uma segunda etapa de renderização não valer o esforço de engenharia para aquele clipe.

Escolha o caminho de sobreposição quando o texto precisar ser exato, temporizado, traduzido, restilizado ou reutilizado em várias saídas. Legendas, subtítulos, faixas de terço inferior e formatos de marketing baseados em template quase sempre caem aqui. A requisição extra é o preço do determinismo.

Híbrido é razoável. Muitas equipes geram assets limpos por padrão, dependem de sobreposições para qualquer coisa que importe e reservam o texto nativo para tomadas atmosféricas e descartáveis. Como os dois caminhos consomem a mesma carga de legendas, você pode tomar essa decisão por clipe sem tratamento especial nos seus dados.

Independentemente da escolha, mantenha a integração atrás de uma abstração fina: uma função que recebe um prompt e uma carga de legendas e retorna o asset final. Essa fronteira é o que permite trocar o backend de geração, adicionar opções de renderização ou mover um clipe individual entre fluxos de trabalho sem tocar na lógica de legendas que você levou tempo para acertar.