Chamar o modelo wan2.7-video/text-to-video via API HiAPI: um fluxo de trabalho prático para vídeos curtos

Por que a geração de vídeo a partir de texto deve fazer parte de um pipeline, e não de uma chamada única

O erro mais comum ao usar modelos de geração de vídeo a partir de texto é tratá-lo como um gerador de imagens com movimento: insere-se um prompt e sai um vídeo pronto. Vídeos curtos raramente funcionam assim. Um clipe de quinze segundos que funciona bem costuma ser o resultado de vários clipes gerados, uma rodada de seleção e uma montagem, e não de uma renderização sortuda.

Um modelo mental mais útil é tratar o modelo como um gerador de clipes dentro de um pipeline. Esse pipeline é mais ou menos assim:

1. Entrada do prompt — você escreve um prompt descrevendo um momento claro: sujeito, ação, cenário e como a câmera se move.
2. Geração do clipe — o modelo wan2.7-video/text-to-video gera um clipe curto com base nesse prompt.
3. Seleção — você analisa os clipes gerados e mantém aqueles que se sustentam por si só.
4. Montagem — os clipes mantidos são montados, cortados e organizados no vídeo curto final.

Essa perspectiva traz duas consequências. Primeiro, cada clipe gerado precisa funcionar de forma independente: se um trecho só faz sentido como parte de uma sequência maior, fica difícil selecioná-lo e reordená-lo. Segundo, o prompt se torna a principal variável do fluxo de trabalho, e não o código de integração. Você escreve a requisição uma vez e depois troca o texto do prompt várias vezes.

É justamente aí que está o benefício de pensar em pipeline desde o início. Se você projetar a primeira chamada como uma renderização descartável, depois terá de reescrever tudo para encaixar seleção ou montagem. Se projetá-la desde o começo como gerador de clipes, o restante do fluxo de trabalho cresce naturalmente ao redor dela.

O que este artigo aborda

Vamos delimitar o que o modelo pode fazer em uma stack baseada em HiAPI, como organizar o prompt em torno de um único clipe utilizável, como formular a linguagem de câmera e movimento, uma forma de requisição funcional e como transformar uma chamada que funciona em um processo repetível por meio de um ciclo de iteração.

O que o modelo wan2.7-video/text-to-video faz na sua stack

O modelo wan2.7-video/text-to-video recebe um prompt de texto e retorna um clipe de vídeo gerado. Esse é o contrato com o qual seu pipeline deve contar: entrada de texto, saída de clipe.

Em uma stack baseada em HiAPI, o modelo fica atrás de uma única interface de API unificada. Sua aplicação não se comunica diretamente com o modelo — ela envia uma requisição para a HiAPI, que cuida da chamada ao modelo e retorna o recurso do clipe gerado. Isso tem alguns efeitos práticos na delimitação da integração:

• Uma integração, várias iterações. Quando o prompt muda, a interface da API permanece estável. A requisição só precisa ser construída uma vez.
• O modelo é uma unidade reutilizável. O texto do prompt é a variável que você ajusta; a estrutura da chamada é a constante.
• Tudo ao redor da chamada é responsabilidade da sua stack. Upload, armazenamento, lógica de seleção, montagem e publicação são sua responsabilidade — o modelo só gera o clipe.

O que deve ficar fora do escopo

Cuidado para não supor detalhes específicos que o modelo não promete. Não codifique suposições sobre taxa de quadros, presets de resolução, duração máxima de um clipe ou comportamento preciso de temporização na lógica do pipeline com base em achismos. Em vez disso, trate o clipe retornado como um recurso opaco: leia seus metadados a partir da resposta, valide e faça a etapa de montagem se adaptar à duração real de cada clipe.

Essa disciplina é especialmente importante no trabalho com vídeos curtos. A saída de vídeo curto é montada a partir de vários clipes, então um pipeline que se adapta à duração real dos clipes é muito mais robusto do que um que presume duração fixa.

Divisão de responsabilidades

A divisão clara é esta:

• Lado do modelo: interpretação do prompt, movimento e geração do clipe de vídeo.
• Lado da HiAPI: acesso autenticado ao modelo por meio de uma API unificada.
• Seu lado: design de prompt, tratamento de requisições, validação de respostas, armazenamento de clipes, seleção, montagem e entrega.

Uma vez respeitada essa fronteira, o restante do fluxo de trabalho — estrutura do prompt, formulação de câmera, iteração — se encaixa no lugar.

Organizar o prompt para clipes de vídeo curto

Como cada clipe precisa ser utilizável de forma independente, cada prompt deve descrever um único momento autossuficiente. A abordagem confiável é montar o prompt com módulos explícitos, em vez de escrever um parágrafo enorme e torcer para dar certo.

Os quatro módulos

Uma estrutura funcional é sujeito, ação, cenário, estilo:

• Sujeito — quem ou o que aparece na imagem. Seja específico: “um ciclista de capa de chuva vermelha” é melhor que “uma pessoa”.
• Ação — a única coisa que o sujeito faz no clipe. Mantenha como uma ação contínua única.
• Cenário — onde a cena acontece, incluindo luz e clima (se for importante).
• Estilo — o tratamento visual: realista, animação, câmera na mão com granulação, cinematográfico etc.

Por exemplo, um prompt estruturado por módulos: um ciclista de capa de chuva vermelha, pedalando de forma constante por ruas urbanas molhadas ao entardecer, reflexos de neon nas poças, câmera na mão com aparência realista.

Escreva apenas uma ação por clipe

Clipes curtos não têm espaço para um arco narrativo. Se você descrever um sujeito entrando, sentando, pedindo um café e saindo, o modelo terá de comprimir ou descartar parte disso, e o resultado será imprevisível. Divida: um clipe para a entrada, um para sentar, um para o balcão. Cada clipe pode ser selecionado, reordenado e cortado na montagem — e, se um deles falhar, é fácil regenerar cada um separadamente.

Recombinar módulos para gerar variantes

Tratar os módulos como campos independentes é uma forma barata de gerar variantes. Fixe sujeito e cenário e varie a ação. Fixe a ação e mude o estilo. Isso produz grupos de clipes relacionados que se editam bem juntos, exatamente o que a montagem de vídeos curtos precisa. Você pode gerar essas variantes em código a partir de pequenas estruturas de dados, em vez de escrever cada prompt à mão.

Mantenha o prompt enxuto

Cada cláusula extra no prompt disputa influência. Se um detalhe não altera o que aparece na imagem desse único clipe, remova-o. Um prompt focado, com quatro módulos claros, costuma superar um parágrafo longo e atmosférico empilhando cinco ideias.

Escrever formulações de câmera e movimento que realmente sejam legíveis

Verbos de movimento vagos produzem movimento vago. Se o seu prompt diz “movimento dinâmico da cena” ou “uma tomada emocionante”, o modelo não recebe nenhuma instrução espacial e só pode improvisar — e comportamento de câmera improvisado é a causa mais comum de clipes descartados na fase de seleção.

Escreva o comportamento da câmera de forma literal

Descreva a câmera com a mesma especificidade com que você daria instruções a um operador de câmera. Formulações úteis incluem:

• “a câmera avança lentamente em direção ao sujeito”
• “a câmera faz um pan para a esquerda, acompanhando o sujeito”
• “um plano fixo travado”
• “a câmera sobe do nível do chão até a altura dos olhos”
• “um movimento orbital lento ao redor do sujeito”

Essas formulações especificam direção e amplitude (lento, travado, subindo), e é por isso que são legíveis. Em comparação, “câmera dinâmica” não especifica nenhuma das duas coisas.

Separe o movimento do sujeito do movimento da câmera

São duas instruções diferentes e devem ser escritas em duas frases diferentes. O sujeito faz algo; a câmera faz algo; os dois são descritos de forma independente. Misturá-los em uma única oração — “a câmera segue o corredor disparando” — deixa ambíguo qual elemento está gerando o movimento.

Faça o movimento caber na duração do clipe

Clipes curtos não comportam movimentos complexos de câmera. Avançar, fazer pan e orbitar ao mesmo tempo em um mesmo clipe de dois segundos resulta ou em uma confusão borrada, ou no descarte completo. Escolha um único comportamento de câmera por clipe e mantenha a amplitude moderada. Se você precisa de um movimento longo e evolutivo de câmera, isso é trabalho da etapa de montagem: gere vários clipes com posições progressivas de câmera e edite-os juntos.

Use âncoras espaciais

O modelo entende bem posições relativas. Frases como “em primeiro plano”, “atrás do sujeito”, “a partir da esquerda”, “em direção ao canto superior direito do quadro” dão pontos de referência. Uma âncora para o sujeito e uma âncora para a câmera costumam estabilizar mais o plano do que empilhar adjetivos.

Releia depois de escrever

Antes de enviar a requisição, faça uma verificação simples: leia a frase de movimento como se estivesse dando instruções a alguém segurando uma câmera. Se a pessoa faria uma pergunta, o prompt precisa de uma resposta mais específica.

Uma requisição funcional de clipe de vídeo a partir de texto na HiAPI

Esta seção percorre a forma de requisição de ponta a ponta. O objetivo é obter um template que você mantém e reutiliza, mudando apenas o texto do prompt a cada execução.

Passo 1: autenticação

Todas as chamadas passam pela HiAPI usando suas credenciais de API. Coloque a chave em uma variável de ambiente, não no código-fonte:

export HIAPI_API_KEY="your_key_here"

Passo 2: enviar a requisição de geração

Na requisição, especifique o modelo e envie o prompt. A forma mínima com curl é esta:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "um ciclista de capa de chuva vermelha pedalando de forma constante por ruas urbanas molhadas ao entardecer, reflexos de neon nas poças, câmera avançando lentamente, aparência realista de câmera na mão"
  }'

Observe como o prompt carrega os quatro módulos mais uma instrução explícita de câmera. Essa é a estrutura descrita antes, apenas serializada.

Passo 3: tratar a resposta

A resposta retorna uma referência ao recurso do clipe gerado. Antes de confiar na resposta, trate-a como dados que precisam ser validados:

• Analise o corpo da resposta como JSON e verifique se há campos de erro antes de ler qualquer resultado.
• Confirme que existe uma referência de clipe; se não existir, registre a resposta completa e pare, em vez de continuar com um valor vazio.
• Leia os metadados do clipe a partir da resposta e registre-os junto com o prompt que o gerou — essa é a base do ciclo de iteração posterior.
• Baixe ou faça streaming do clipe para o seu próprio armazenamento, pois a persistência é responsabilidade do seu pipeline.

Passo 4: encapsular em uma função

Para qualquer fluxo de trabalho real, mova a requisição para uma pequena função que recebe a string do prompt e retorna a referência do clipe com os metadados. Deixe o nome do modelo, os cabeçalhos e o tratamento de erros dentro da função. A partir daí, cada experimento é só mudar uma linha de prompt, e não uma tarefa de integração.

import os, requests

def generate_clip(prompt: str) -> dict:
    resp = requests.post(
        "https://api.hiapi.ai/v1/video/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": "wan2.7-video/text-to-video", "prompt": prompt},
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()
    if not data.get("clip"):
        raise ValueError(f"No clip in response: {data}")
    return data

Essa função é a unidade reutilizável do seu pipeline. Tudo o que vem depois é construído sobre ela.

Passo 5: validar antes de montar

Antes que o clipe entre na etapa de montagem, verifique se o arquivo pode ser baixado sem problemas e se a duração está dentro do que o passo de montagem espera conseguir tratar. Rejeite cedo, em vez de descobrir um clipe corrompido na hora da publicação.

Iteração: de um bom clipe a um fluxo de trabalho repetível de vídeos curtos

Depois que a requisição funciona, começa o trabalho interessante: transformar um único bom clipe em um processo que produza saídas de vídeo curto de forma confiável.

O ciclo de iteração

O ciclo tem três fases e se repete continuamente:

1. Variar o prompt. Mude um módulo por vez — ação, frase de câmera, estilo. Mudando vários ao mesmo tempo, fica impossível saber qual mudança fez efeito.
2. Selecionar clipes. Analise o grupo de clipes gerados e mantenha os que servem. Registre suas decisões de seleção; notas como “o avanço funciona, a órbita está rápida demais” valem mais que o próprio clipe.
3. Montar. Junte os clipes mantidos, corte na duração que você precisa e verifique se os trechos se editam bem juntos.

A saída da montagem alimenta a próxima rodada de variação de prompt. Se dois clipes não se editam bem juntos, isso já é informação e indica em que aspectos seus prompts devem ser consistentes — enquadramento do sujeito, luz ou direção do movimento.

Criar uma biblioteca de prompts

Guarde cada prompt que gerou um clipe mantido, junto com a referência do clipe e suas notas. Depois de algumas rodadas, isso vira uma pequena biblioteca de padrões recombináveis: descrições de sujeito validadas, frases de câmera validadas, módulos de estilo validados. Assim, novos vídeos são montados a partir de peças já conhecidas como boas, em vez de começar de um prompt em branco.

Gerar em lote a partir de estruturas de dados

Como sua função de requisição recebe uma string de prompt, gerar variantes é só iterar sobre uma lista ou um pequeno objeto de configuração. Defina sujeito e cenário uma vez, depois percorra a lista de ações e a lista de frases de câmera para gerar um conjunto de candidatos. É aqui que a perspectiva de pipeline compensa: o modelo é constante, o prompt é variável, e seu código só precisa enumerar as variações.

Manter a seleção barata

Nem todo clipe gerado precisa ser assistido por completo. Defina critérios simples de rejeição antecipadamente — sujeito errado, falta de movimento, enquadramento inutilizável — e descarte rapidamente. Gaste seu tempo de análise nos casos limítrofes, aqueles que talvez possam ser usados após um corte.

Versionar o fluxo de trabalho

Para cada clipe que você mantém, armazene o prompt, o nome do modelo e os metadados da resposta juntos. Quando o estilo visual do seu canal mudar, você pode rastrear com precisão quais padrões de prompt produziram o estilo atual e ajustar a partir de uma base conhecida, em vez de adivinhar.

Armadilhas comuns e como evitá-las

Alguns modos de falha se repetem em pipelines de geração de vídeo a partir de texto. Cada um tem uma correção direta.

Verbos de movimento vagos

Sintoma: os clipes retornados parecem ter movimentos de câmera aleatórios, ou o sujeito quase não se move. Correção: substitua cada palavra abstrata de movimento por uma instrução literal e direcional. Especifique por clipe um comportamento de câmera e uma ação do sujeito, cada um com uma amplitude — lento, constante, travado.

Prompt sobrecarregado

Sintoma: parte da descrição desaparece da saída, ou o resultado parece um meio-termo entre várias ideias. Correção: force uma única ação por clipe e remova detalhes que não alteram o que aparece na imagem. Divida ideias com várias tomadas em clipes separados e deixe a etapa de montagem cuidar da ordenação.

Pular a validação de resposta

Sintoma: respostas com falha ou malformadas chegam ao armazenamento e à etapa de montagem, e só se descobre isso na publicação. Correção: verifique erros e a existência da referência de clipe imediatamente após cada chamada, registre a resposta completa em caso de falha e valide antes que o recurso baixado entre na seleção.

Presumir atributos fixos de clipe

Sintoma: a lógica de montagem quebra quando a duração ou o formato do clipe retornado difere do esperado. Correção: leia os metadados da resposta e adapte-se na montagem. Não codifique a duração do clipe no pipeline.

Mudar variáveis demais de uma vez

Sintoma: você não consegue saber qual mudança de prompt melhorou ou piorou a saída. Correção: mude um módulo por iteração e mantenha notas. Engenharia de prompt, aqui, é um ciclo de experimentos, não uma reescrita.

Tratar a chamada de API como o produto inteiro

Sintoma: a requisição funciona, mas não há saída confiável, porque seleção e montagem nunca foram construídas. Correção: lembre-se de que a geração é só uma etapa. Reserve esforço real para revisão, armazenamento e montagem dos clipes — é aí que a qualidade do vídeo curto realmente se decide.

Se você mantiver a requisição em uma função reutilizável e iterar sobre o texto do prompt, a maioria das armadilhas acima desaparece sozinha.