Blogue

Guia de uso

Criando vídeos curtos com veo-3.1-lite/text-to-video na API HiAPI

Um fluxo de trabalho prático para desenvolvedores: storyboard de texto para vídeo, áudio nativo e escolha de proporção

Nov 9, 2026
Linhas de gravura em tom de cobre vintage, dispostas sobre um fundo azul-meia-noite em faixas horizontais, formando a capa abstrata de um storyboard de curta-metragem.
Nesta página
Um vídeo curto produzido de ponta a ponta com veo-3.1-lite/text-to-video na API HiAPI — storyboard, áudio nativo e entrega em 16:9, tudo a partir de um único prompt.

Por que vídeos curtos quebram prompts ingênuos de texto para vídeo

No primeiro contato com um modelo de texto para vídeo, o instinto é escrever um prompt cinematográfico longo e esperar receber um vídeo pronto. Para uma peça curta de 30 segundos, essa abordagem quase sempre decepciona, e o motivo está na estrutura, não no grau de refinamento do prompt.

Um único prompt exige que o modelo mantenha a continuidade ao longo de todo o arco narrativo: consistência de personagem, movimento de câmera, ritmo e áudio precisam permanecer coerentes durante toda a duração. No entanto, um vídeo curto não é um plano-sequência contínuo — é uma série de batidas. Gancho, preparação, virada, fechamento. Cada batida exige uma composição diferente, uma energia diferente e, muitas vezes, uma posição diferente do sujeito. Enfiar tudo isso em um único prompt faz o modelo tirar a média de tudo, e a média é exatamente o que destrói a retenção de vídeos curtos.

Outro modo de falha é o custo de iteração. Quando um único prompt gera um vídeo longo e a terceira batida sai errada, você só pode regenerar tudo e torcer para que a parte de que gostou sobreviva. É um ciclo lento e sem controle confiável.

O fluxo de trabalho usado neste guia é baseado em planos: decomponha o roteiro em planos discretos, envie uma solicitação de geração separada para cada plano e coloque a continuidade nos seus próprios metadados, não no prompt. Cada seção a seguir se baseia nessa decomposição — estrutura de requisição, proporção, áudio e iteração pressupõem que você trabalha plano a plano.

É exatamente aí que o veo-3.1-lite/text-to-video se encaixa naturalmente. Um modelo de texto para vídeo mais leve é ideal para gerar muitos clipes curtos e regeneráveis individualmente, e é justamente essa a forma de um pipeline de vídeos curtos.

A mudança de modelo mental

Pare de tratar o modelo como um diretor que devolve um filme pronto. Trate-o como um renderizador de planos: você fornece a descrição de um plano com escopo bem definido, ele devolve um clipe, e o seu pipeline cuida da ordenação, da mixagem de áudio e do ritmo. Uma vez clara essa divisão de trabalho, a maioria das decisões restantes passa a ser de engenharia, não de escrita de prompt.

Planeje a lista de planos antes de chamar a API

A lista de planos é o contrato entre o roteiro e as chamadas de geração. Escreva-a como dados, não como prosa, para que o seu pipeline possa percorrê-la.

Comece pelo roteiro e divida-o em batidas. Para vídeos curtos, uma regra prática é: um plano por frase ou por ideia visual, o que for mais curto. Se uma frase precisa de dois enquadramentos para ficar clara, são dois planos. Se três frases compartilham um visual contínuo, elas podem ser um único plano — mas somente se a duração ainda couber confortavelmente em uma geração.

Para cada plano, registre pelo menos:

  • ID do plano — estável, legível por humanos, usado para cache e novas tentativas.
  • Prompt — descrição visual, autossuficiente o bastante para que o plano funcione isoladamente.
  • Duração — quanto tempo o plano deve durar no corte final.
  • Proporção — definida por canal, decidida antes da geração.
  • Intenção de áudio — som ambiente nativo, silêncio a ser substituído, ou espaço reservado para narração.
  • Notas de continuidade — figurino do personagem, iluminação, locação e direção de tela.

Mova a continuidade para fora do prompt sempre que possível

As notas de continuidade devem ficar nos metadados, não repetidas literalmente em cada prompt. Prompts que carregam descrições longas e reutilizadas tendem a derivar na ênfase — um plano destaca demais o figurino, o seguinte de menos. Um padrão mais limpo é preparar um bloco de descrição curto e estável para cada personagem ou locação, que você (autor do pipeline) monta em cada prompt, de modo que a fraseologia seja idêntica entre os planos, mesmo que os prompts em si sejam diferentes.

Faça cada plano corresponder a uma requisição

Cada plano deve poder ser gerado em uma única chamada. Se um plano precisar de mais tempo do que uma geração consegue cobrir confortavelmente, divida-o em um ponto de corte natural — uma reação, um movimento de câmera, uma pausa silenciosa — em vez de esticar a requisição. Planos mais curtos também custam menos para regenerar quando um dá errado, e é exatamente aí que está o valor da decomposição.

Mantenha a lista de planos no controle de versão junto com o roteiro. Quando o roteiro mudar, o diff mostrará exatamente quais planos precisam ser renderizados novamente.

Construa as requisições de geração no pipeline

Com a lista de planos em mãos como dados, a camada de requisição vira um wrapper fino: lê um plano, monta a requisição para o veo-3.1-lite/text-to-video, chama a API HiAPI e armazena o resultado pelo ID do plano.

Em alto nível, uma chamada de geração carrega as mesmas informações do registro do plano: texto do prompt, duração pretendida e proporção. Os nomes exatos dos parâmetros e os valores aceitos são definidos pela referência da API do modelo na HiAPI, então trate a documentação do endpoint como fonte da verdade e faça os padrões do wrapper coincidirem com ela, em vez de codificar suposições em vários lugares.

Um wrapper reutilizável

A forma abaixo é deliberadamente pseudocódigo agnóstico de linguagem — o valor está na estrutura, não na sintaxe:

function renderShot(shot, attempt):
    request = {
        model: "veo-3.1-lite/text-to-video",
        prompt: buildPrompt(shot),
        duration: shot.duration,
        aspect_ratio: shot.aspectRatio
    }
    response = hiapi.generate(request)
    save(shot.id, attempt, response)
    return response

Três características tornam esse wrapper valioso:

  1. Cada chamada é indexada pelo ID do plano e pelo número da tentativa. Quando o 4º plano dá errado, você sabe exatamente qual artefato substituir e quais tentativas falharam.
  2. O prompt é construído, não colado. buildPrompt mescla a descrição do próprio plano com os blocos estáveis de descrição de personagem e locação dos metadados, mantendo a fraseologia de continuidade consistente entre os planos.
  3. O downstream não depende do sucesso da primeira chamada. O wrapper retorna uma referência de artefato; o concatenador lê o que está atualmente aprovado para cada plano.

Na prática, a geração é assíncrona

Trate a geração como uma tarefa de longa duração, não como uma chamada síncrona dentro do handler de requisição. Envie, persista a referência da tarefa e faça polling ou aguarde a conclusão em um worker. Assim, novas tentativas, limites de concorrência e falhas parciais ficam sob o seu controle, sem se enredar no ciclo de vida da requisição da aplicação.

A concatenação é uma etapa separada

Não gere e concatene no mesmo passo. Renderize todos os planos aprovados, armazene-os e depois execute um processo de montagem separado: ordenar por ID do plano, concatenar, aplicar transições (se houver) e mixar o áudio. Manter a montagem independente significa que re-renderizar um plano exige apenas reexecutar a montagem, sem regenerar nada.

Escolha a proporção e a duração do clipe por canal

A proporção e a duração devem ser decididas de fora para dentro a partir do canal de distribuição, antes de qualquer geração acontecer — não ajustadas depois. Recortar clipes prontos para enquadramentos diferentes é a forma mais comum de desperdiçar renderização.

Proporção

Escolha um enquadramento principal por canal e mantenha-o em toda a peça. Misturar proporções em um único vídeo curto prejudica a experiência de visualização em todas as plataformas.

  • Retrato — o padrão para interfaces de vídeos curtos com rolagem no feed. Componha para o enquadramento alto: sujeito centralizado ou um pouco acima, com margens seguras no topo e na base para as sobreposições de UI.
  • Paisagem — para players embutidos, vídeos de destaque do site e apresentações em que o público está parado.
  • Quadrado — ocasionalmente usado em layouts de grade; trate-o como uma escolha deliberada, não como um recurso de última instância.

Impacto real na sua lista de planos: a composição em retrato muda o que cabe no quadro. Um plano geral de estabelecimento que funciona bem em paisagem pode ficar irreconhecível quando comprimido em um enquadramento alto. Decida a proporção primeiro e depois escreva planos compostos para ela.

Duração do clipe

A duração do clipe é guiada pelo ritmo, não por quanto o modelo consegue gerar no máximo. Algumas diretrizes:

  • O gancho deve ser curto. O primeiro plano geralmente decide se você ganha ou perde a atenção; mantenha-o compacto e visualmente inequívoco.
  • Uma ideia por clipe. Se um plano contém dois eventos visuais distintos, separe-os. Clipes mais curtos também dão controle mais fino sobre o ritmo final na edição.
  • Deixe folga para o corte. Gere um pouco mais do que o ponto de corte pretendido e corte na montagem. Cortar é gratuito; regenerar não é.
  • Confira o total da plataforma. A duração total é a soma dos planos. Some as durações planejadas antes de gerar e verifique se a sequência se encaixa na janela típica de consumo do canal — reequilibrar a lista de planos é muito mais fácil do que re-renderizar.

Gere uma vez por proporção

Se você realmente precisa da mesma peça em dois enquadramentos, trate-os como duas entregas separadas, cada uma com sua própria lista de planos. Compartilhar prompts tudo bem; compartilhar renderizações não, porque a composição é diferente. Codificar a proporção nos metadados do plano deixa isso explícito e evita reutilização acidental entre canais.

Combine áudio nativo com narração

O veo-3.1-lite/text-to-video pode gerar áudio nativo junto com a imagem, e esse áudio é genuinamente útil — som ambiente, textura atmosférica e sons diegéticos simples dão ao clipe uma presença que o silêncio não tem. O erro é deixar tanto o áudio nativo quanto a sua narração tentarem assumir o mesmo papel.

A divisão eficaz é: o áudio nativo fornece o mundo, e a narração fornece a informação. Se a trilha nativa já contém algo parecido com fala ou uma base musical forte, você vai brigar com ela na mixagem. Decida plano a plano qual trilha domina.

Ordem da mixagem

  1. Coloque a narração primeiro. O tempo da narração é fixado pelo roteiro; todo o resto se adapta a ele.
  2. Coloque o áudio nativo por baixo. Quando a trilha nativa é ambiente ou textura, mantenha-a audível, mas em papel secundário.
  3. Abaixe, não apague. Reduza a trilha nativa sob a narração em vez de cortá-la completamente — silêncio súbito entre falas soa antinatural. Faça transições suaves de ganho em cada limite de plano.
  4. Normalize por último. A mixagem plano a plano seguida de concatenação gera saltos de nível. Execute um processamento final uma vez sobre a peça montada.

Quando silenciar a trilha nativa

Silencie-a — ou regenere o plano com uma intenção de áudio mais clara — quando:

  • O áudio nativo contém fala compreensível que compete com a sua narração.
  • A textura não combina com a cena (por exemplo, som ambiente interno em um plano externo).
  • Você usa uma base musical contínua para toda a peça e o ritmo da trilha nativa conflita com ela.

Esses casos geralmente podem ser detectados plano a plano, o que é mais um motivo para manter os planos independentes: você pode regenerar o áudio de um plano sem tocar no resto.

Escreva a intenção de áudio na lista de planos

Adicione um campo explícito de áudio a cada plano: native_ambience, silent ou voiceover_covered. Isso força você a tomar a decisão antes de gerar e informa à etapa de montagem quais planos precisam de redução de volume e quais só precisam descartar a trilha nativa.

Controle qualidade e custo ao longo de várias tentativas

A disciplina de iteração é o que diferencia um pipeline que converge de um que queima renderizações. A boa notícia é que a geração baseada em planos torna os bons hábitos naturais.

Regenere apenas o plano individual, nunca a sequência

Quando uma batida dá errado, substitua aquele plano. O seu wrapper indexa os resultados por ID do plano e número da tentativa, então a correção é iniciar uma nova tentativa para um ID e reexecutar a montagem. Se você se pegar re-renderizando vários planos para corrigir um, a lista de planos pode estar muito grossa — divida-a mais.

Faça cache agressivo dos clipes aprovados

Assim que um plano é aprovado, trate-o como imutável, armazene-o de forma persistente e indexe-o pelo ID do plano mais o hash do seu prompt e parâmetros. Ao reexecutar o pipeline, tudo que não mudou é ignorado. Isso é mais importante durante o trabalho de áudio e ritmo, quando você itera a mixagem com a imagem fixa.

Mude apenas uma variável por tentativa

Quando um plano não atende às expectativas, ajuste uma coisa — a especificidade do prompt, a duração ou a composição — e gere novamente. Mudar três variáveis ao mesmo tempo não revela qual correção funcionou, e você reaprende a mesma lição no plano seguinte.

Defina a receita antes de escalar as tentativas

Leve uma sequência completa a um estado que o satisfaça e depois use-a como modelo para variações: ganchos alternativos, CTAs diferentes. Como a lista de planos é dados, uma variação é apenas um diff pequeno, não um novo projeto.

Orçamente por número de planos, não por minutos de vídeo final

A unidade de trabalho é o plano, então a unidade de iteração também é o plano. Antes de gerar um lote, calcule o número de planos e a quantidade esperada de tentativas por plano. Esse número, combinado com a base de cobrança do modelo, é o seu número de planejamento — consulte as tarifas atuais no painel de preços da HiAPI em vez de repetir suposições desatualizadas.

Revise no tamanho final

Verifique cada plano na proporção real e na tela em que o público vai assistir. Problemas invisíveis no tamanho de desktop em paisagem ficam óbvios em um feed em retrato. Encontrá-los na revisão custa muito menos do que encontrá-los após a publicação.

Solucione problemas comuns de geração

Quando um plano retorna inutilizável, execute estas verificações em ordem. Elas cobrem a grande maioria das falhas, e as duas primeiras resolvem a maior parte dos problemas.

1. Especificidade do prompt

O prompt é autossuficiente? Ele descreve sujeito, ação, composição e iluminação, ou depende do contexto de planos vizinhos? O prompt de um plano precisa funcionar sozinho — o modelo só vê o que você envia. Descrições vagas de sujeito causam deriva; prompts sobrecarregados causam confusão visual. Mire em um sujeito claro e uma ação clara por plano.

2. Duração do plano

O plano está tentando fazer coisas demais para a sua duração? Se um prompt sugere vários eventos visuais em um clipe curto, o modelo os comprime. Divida o plano ou aumente a duração. Por outro lado, planos com conteúdo de menos para a sua duração tendem a vagar sem propósito — corte-os.

3. Incompatibilidade de proporção

Você escreveu o prompt para o enquadramento que realmente solicitou? Escrever descrições amplas e horizontais para um enquadramento em retrato produz recortes estranhos e espaço morto. Verifique se a descrição visual do plano corresponde à sua proporção e se alguma outra etapa do pipeline está recortando novamente sem que você perceba.

4. Conflito de áudio

Se a imagem estiver boa mas o resultado parecer errado, ouça a trilha nativa isoladamente. Fala concorrente, som ambiente incorreto ou um ritmo forte sob a narração geralmente são problemas de áudio, não de imagem. Corrija silenciando a trilha nativa ou ajustando a intenção de áudio do plano, e depois remixe — não é preciso regenerar a imagem.

5. Erros de pipeline e de parâmetros

Se a geração falhar diretamente ou retornar algo incompatível com a requisição, valide os parâmetros contra a documentação do endpoint na HiAPI: identificador do modelo escrito corretamente, valores de duração e proporção dentro das faixas aceitas, prompt não vazio. Esses erros são entediantes, mas comuns em wrappers que codificam padrões em vários lugares — é por isso que a construção da requisição deve ficar em uma única função.

6. Deriva de continuidade entre planos

Se cada plano parecer bom individualmente mas a sequência não se manter coerente, o problema está nos metadados, não na geração. Compare o texto do prompt montado de cada plano: se os descritores de personagem ou locação estiverem redigidos de forma diferente, alinhe-os no bloco de descritores compartilhado e regenere apenas os planos que divergiram.

Percorra a lista em ordem e registre qual verificação resolveu cada falha. Depois de algumas sequências, você saberá quais verificações dominam para o seu conteúdo, e a solução de problemas vira uma varredura rápida em vez de uma reconstrução. Você pode começar a renderizar planos com veo-3.1-lite/text-to-video pela API HiAPI, deixar o painel de preços cuidar dos números e focar na sequência.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API