Criando vídeos curtos com ltx-2.5-fast/text-to-video no HiAPI

Por que ltx-2.5-fast/text-to-video é adequado para criação de vídeos curtos

Vídeos curtos são um jogo de volume, e o orçamento de atenção do público é curto. Você precisa de muitos clipes, giro rápido e uma forma de descartar tomadas ruins sem hesitar. Isso determina qual modelo de geração vale a pena conectar ao seu pipeline.

ltx-2.5-fast/text-to-video é um modelo de texto para vídeo na API do HiAPI, e tem duas características cruciais aqui: ele produz áudio nativo junto com a imagem e entrega 1080P. Na prática, o clipe retornado por uma chamada já tem formato pronto para publicação — você não precisa juntar uma faixa de vídeo sem som com uma base musical gerada separadamente, nem fazer upscale de um rascunho em baixa resolução antes que o clipe possa ser exibido.

O fast no nome do modelo aponta exatamente para esse mesmo trade-off: priorizar a vazão em vez da fidelidade máxima. Para criação de vídeos curtos — clipes verticais, ganchos, cortes para redes sociais — esse normalmente é o lado certo. Você itera mais vezes, e o número de iterações importa mais do que qualquer frame individual.

Um esquema simples de pipeline:

text prompt ──► ltx-2.5-fast/text-to-video ──► video track (1080P)
                                          └──► audio track (native)

Uma entrada, duas saídas, um ativo para gerenciar. Todo o restante deste guia se baseia nesse formato.

Planeje os clipes antes de escrever os prompts

O erro mais comum no trabalho de prompt para clipe é escrever um prompt para o vídeo inteiro. Peça ao modelo para “fazer um anúncio de 30 segundos” e ele vai tirar a média das batidas, produzindo algo que não parece ser nenhuma delas. Comece pela decomposição.

Divida o vídeo em unidades de plano

Escreva o roteiro e corte em cada mudança visual. Cada ponto de corte é uma unidade de geração. Um vídeo curto típico costuma ficar entre quatro e oito unidades. Para cada unidade, defina:

• um número e uma frase descrevendo o que acontece
• a duração esperada
• a intenção de áudio (fala, leito ambiente, música apenas, silêncio)
• uma observação sobre se ela precisa se conectar visualmente ao plano anterior

Mantenha cada requisição pequena

Unidades pequenas são baratas de regenerar e baratas de reordenar. Se o plano 3 saiu errado, você roda novamente o plano 3, não o vídeo inteiro. Deixe o trabalho de continuidade fora da responsabilidade do modelo: se dois planos precisam se conectar com fluidez, gere-os separadamente e una-os no editor, em vez de pedir um plano longo e contínuo.

Defina o formato-alvo desde o início

Proporção, faixa de duração e finalidade do clipe determinam todo o resto. Defina isso antes da primeira requisição, porque mudar depois significa regenerar tudo. Se você vai produzir para vários canais, planeje listas de planos por canal em vez de recortar um master — as diferenças de enquadramento são grandes o suficiente para que o recorte pareça recorte.

Trate a lista de planos como dados versionados. Um prompt que produziu um bom clipe é um ativo, e você vai querer tê-lo no controle de versão junto com o código que o consome.

Padrões de prompt que produzem clipes utilizáveis

Escreva prompts como descrições estruturadas de plano, não como prosa. Um template estável oferece reprodutibilidade: quando uma nova tentativa funciona, você sabe qual campo mudou.

Cinco campos

[subject]   who or what is on screen, with concrete visual detail
[action]    what happens during the shot — one continuous motion
[camera]    framing, angle, and movement (e.g. slow push-in, static wide)
[lighting]  time of day, source, mood
[audio]     what should be heard: dialogue, ambience, music character

Um exemplo preenchido:

subject: a woman in a canvas work jacket, mid-30s, workshop background
action: she lifts a ceramic mug from a shelf and turns it in her hands
camera: static medium shot, slight shallow depth of field
lighting: warm afternoon window light from camera left
audio: quiet room tone, faint hum of a kettle, no music

Regras que se sustentam

• Uma ação por plano. Duas ações em um prompt fazem o modelo fazer concessões entre elas. Se o plano precisa de uma segunda batida, então são dois planos.
• Descreva o que é visível, não o que significa. “Ela parece aliviada” não dá nada ao modelo. “Os ombros dela caem e ela solta um suspiro” dá algo renderizável.
• Declare explicitamente o comportamento da câmera. Não declarar o comportamento da câmera é o caminho mais rápido para um clipe inutilizável, porque o modelo escolhe um padrão que você não queria.
• Especifique a intenção de áudio. Áudio nativo significa que o prompt influencia o som. Deixe claro se você quer fala, som ambiente, música ou silêncio — não deixe implícito.
• Evite empilhar negações. “Sem texto, sem marca d'água, sem pessoas extras” muitas vezes atrai justamente o que foi mencionado. Em vez disso, descreva a imagem que você quer.

Mantenha um log de prompts

Para cada prompt que você envia, armazene o texto completo mais os parâmetros. Quando um clipe funciona, o prompt é um ativo reutilizável; quando falha, o log mostra se o que mudou foi o prompt ou os parâmetros.

Faça a requisição pela API do HiAPI

A geração é feita pela API do HiAPI, com o identificador de modelo ltx-2.5-fast/text-to-video. A chamada é uma requisição única: você envia o prompt e os parâmetros de geração e recebe um job, cujo resultado é o ativo do clipe.

Formato mínimo da requisição

Os nomes exatos dos campos e as faixas aceitas vêm da página de referência desse modelo na documentação da API — consulte lá antes de fixar qualquer coisa no código. A estrutura abaixo mostra o formato de uma chamada funcional:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ltx-2.5-fast/text-to-video",
    "prompt": "static medium shot, a woman in a canvas work jacket lifts a ceramic mug from a shelf and turns it in her hands, warm afternoon window light from camera left, quiet room tone with a faint kettle hum",
    "duration": <clip length in seconds>,
    "resolution": "1080p"
  }'

Substitua o placeholder de duration pelo valor aceito pelo modelo. Envie apenas o necessário: prompt, duração, resolução e quaisquer controles de proporção ou áudio listados na página de referência.

O mínimo que você deve enviar

• o identificador do modelo, exatamente como publicado
• o prompt completo montado com o seu template
• a duração, escolhida dentro da faixa suportada pelo modelo
• a resolução de saída, quando o modelo permitir que você a escolha

Trate a resposta como um job, não como um arquivo

Trate cada resposta como um registro de job: um identificador, um estado e — quando concluído — uma referência ao ativo. Persista o identificador do job junto com o seu prompt e os seus parâmetros, para que cada clipe na sua biblioteca possa ser rastreado até a requisição que o produziu.

Mantenha a chave de API no lado do servidor e injete-a a partir do ambiente. Não monte prompts no cliente.

Processe o áudio nativo e a saída em 1080P a jusante

A chamada retorna um clipe em 1080P já com faixa de áudio. O que você faz em seguida determina se isso faz sentido.

Revise antes de montar

Assista a cada clipe em tamanho completo e sem mudo. Verifique especificamente duas coisas:

• Sincronia entre áudio e imagem. O áudio nativo é gerado junto com a imagem, não derivado dela. Confirme que o som corresponde à ação — pegar uma xícara não deveria soar como fechar uma porta.
• Nível e caráter do áudio. O áudio gerado pode estar mais alto ou mais baixo do que você esperava. Verifique os picos antes de colocá-lo na timeline com ganho unitário.

Rejeite rápido. Um clipe que precisa de correção na revisão geralmente sai mais barato regenerar do que corrigir, especialmente quando o ponto de correção está no prompt.

Monte, não regenere

Corte os planos juntos com a ferramenta de edição que sua equipe já usa. Como cada plano volta como um ativo completo em 1080P, a montagem é edição normal: aponte o início e o fim, defina os pontos de transição e abaixe o áudio sob a narração que você adicionar.

Preserve o áudio nativo onde ele agrega valor. Leitos ambientes e ruído de sala gerados junto com a imagem costumam se encaixar melhor do que trilhas de biblioteca sobrepostas, porque foram gerados para aquele frame. Substitua o áudio apenas onde você precisa de uma voz específica ou de música licenciada.

Exporte para o canal de destino

Exporte no codec, na proporção e na duração que a plataforma de destino espera, e valide com uma exportação de amostra contra os requisitos dessa plataforma antes da produção em lote. A fonte em 1080P dá margem para reenquadrar em outras proporções, mas recheque o enquadramento depois de reenquadrar — o quadro que você aprovou pode não resistir ao corte.

Mantenha o custo de iteração e a qualidade sob controle

A geração é cobrada pelo trabalho solicitado — a duração e a resolução do clipe influenciam o custo de uma chamada. Isso significa que sua disciplina de iteração é o seu controle de custos. Três práticas deliberadas:

Regenere primeiro, reescreva depois

Se o clipe está perto, mas errado, rode o mesmo prompt mais uma vez. A geração não é totalmente determinística, e uma segunda amostra às vezes elimina pequenos defeitos. Se o mesmo prompt falhar duas vezes da mesma forma, o problema está no prompt — mude-o.

Mude uma coisa por vez

Quando você edita o prompt, edite apenas um campo. Se você mudar sujeito, câmera e iluminação ao mesmo tempo e o resultado melhorar, você não aprendeu nada reutilizável. A iteração de variável única converge; edições dispersas produzem clipes que você não consegue reproduzir.

Distinga problema de prompt de problema de parâmetro

Pergunte em qual eixo a falha aconteceu. Composição, ação e clima são problemas de prompt. Duração, resolução e formato são problemas de parâmetro. Consertar um problema de composição encurtando o clipe desperdiça uma chamada; consertar um problema de duração reescrevendo o prompt, idem.

Escale em ordem

1. Rode o mesmo prompt novamente.
2. Ajuste um campo do prompt.
3. Mude um parâmetro (duração, resolução).
4. Redesenhe o plano.

A maioria dos clipes corrigíveis se resolve no passo 1 ou no passo 2. Pular para o passo 4 é a forma de transformar iterações baratas em caras.

Por fim, limite o número de tentativas. Defina um teto de novas tentativas por plano na sua camada de jobs e pare ao atingi-lo — esse plano precisa ser repensado, não de outra amostra.

Padrões comuns de falha e como depurar

A maioria dos problemas de prompt para clipe cai em poucas categorias. Veja a seguir onde olhar primeiro em cada uma.

O clipe não corresponde ao prompt

Primeiro verifique a especificidade do prompt. Sujeitos vagos e comportamento de câmera não declarado são as causas comuns. Reescreva o plano com o template de cinco campos e declare o comportamento da câmera explicitamente.

Ação confusa ou fragmentada

Provavelmente você pediu mais de uma coisa acontecendo. Divida o plano em duas unidades de geração, cada uma com apenas uma ação contínua.

Áudio não combina com a imagem

Verifique o campo de áudio do prompt. Se você deixou implícito, o modelo escolheu um padrão. Declare diretamente a intenção de áudio — som ambiente, fala, caráter musical ou silêncio.

Duração ou formato do clipe errado

É um problema de parâmetro, não de prompt. Verifique se os valores enviados estão na faixa listada na página de referência do modelo e confirme se o seu cliente os está serializando como esperado, em vez de descartá-los.

Requisição falha ou dá timeout

Verifique, em ordem: a grafia do identificador do modelo exatamente como publicado; se a chave de API existe e é válida; se o corpo da requisição é JSON válido; se você não estourou limites de taxa. A geração é trabalho assíncrono, então uma resposta lenta não é necessariamente falha — faça polling do job em vez de reenviar, senão você paga duas vezes pelo mesmo clipe.

Resultados inconsistentes entre execuções

Esperado até certo ponto. Registre cada prompt e conjunto de parâmetros, para que você consiga distinguir uma regressão real de uma flutuação normal, e mantenha o seu teto de novas tentativas.

O ciclo de depuração mais rápido é sempre o mesmo: puxe o registro do job, leia o prompt e os parâmetros exatos que foram enviados, mude um campo por vez até o clipe corresponder ao plano que você desenhou.