Criar vídeos curtos com flux-3-max/text-to-video na API HiAPI

Por que o vídeo curto é um problema de orquestração de prompts

A maioria das equipes que falham em texto para vídeo falha pelo mesmo motivo: escrevem um único prompt gigantesco descrevendo a cena inteira e esperam que o modelo retorne um vídeo de trinta segundos pronto. A geração não funciona assim. O modelo gera um plano contínuo por chamada, e cada chamada é uma pequena decisão autocontida sobre sujeito, ação, enquadramento e som.

O modelo mental que se sustenta é o de orquestração. Você não está pedindo um vídeo; está dirigindo uma série de planos e depois montando-os. Uma peça de vídeo curto — um teaser de produto, um gancho para redes sociais, uma explicação com narração — normalmente é composta de quatro a oito planos. Cada plano carrega uma única tarefa: estabelecer, demonstrar, fazer a transição, encerrar. Assim que você aceita essa decomposição, a API deixa de ser um caça-níqueis e passa a ser um passo de renderização em um pipeline que você controla.

Isso importa porque os modos de falha de texto para vídeo são majoritariamente falhas de continuidade, não de qualidade. Um plano isolado pode parecer lindo, mas se o personagem do próximo plano é diferente, a direção da luz é diferente ou a câmera flutua de repente, esse plano ainda é inutilizável. Esses problemas se resolvem antes de a requisição sair, por meio de como você planeja e descreve os planos — não adicionando adjetivos a um prompt gigantesco.

O restante deste guia leva você pelo fluxo de trabalho de ponta a ponta, chamando flux-3-max/text-to-video via HiAPI: dividir o roteiro em planos, escrever prompts por plano, tratar o movimento de câmera como uma dimensão controlada, usar áudio nativo para pular a etapa separada de áudio e envolver tudo em um pequeno loop de requisições reproduzível.

Planeje os planos antes de chamar a API

Antes de escrever qualquer código, transforme o roteiro em uma shot list. Uma shot list é uma estrutura de dados pura: um item por chamada de geração, com cada item tendo um propósito claro. Esta estrutura funciona bem como representação intermediária:

[
  {
    "id": "s1",
    "role": "establish",
    "subject": "ceramic pour-over coffee dripper on a wooden counter",
    "framing": "medium close-up, three-quarter angle",
    "durationIntent": "short",
    "camera": "slow push in",
    "audio": "quiet room tone, soft steam"
  },
  {
    "id": "s2",
    "role": "demonstrate",
    "subject": "hot water spiraling over coffee grounds",
    "framing": "tight overhead macro",
    "durationIntent": "short",
    "camera": "locked off",
    "audio": "water pouring, gentle hiss"
  }
]

Algumas regras de planejamento que economizam novas tentativas mais tarde:

• Uma ideia por plano. Se a descrição do seu plano contém “e então”, divida-a. O modelo lida com uma única ação contínua muito melhor do que com uma sequência de beats.
• Expresse intenção de duração, não segundos exatos. Decida se um plano é um corte rápido ou uma permanência mais longa e expresse isso como intenção. Pontos de tempo exatos pertencem à sua etapa de edição/montagem, onde você tem controle com precisão de frame.
• Fixe cedo o vocabulário de enquadramento. Escolha termos como wide, medium, close-up, overhead, low angle e reutilize-os literalmente entre os planos. Um vocabulário consistente produz resultados mais consistentes.
• Planeje âncoras de continuidade. Decida o que permanece constante: descrição do personagem, figurino, paleta de cores, hora do dia, direção da luz. Escreva isso uma vez como prefixo compartilhado e reutilize em cada prompt.
• A ordem importa na revisão. Gere na ordem do roteiro para revisar na ordem em que os clipes serão reproduzidos, em vez de ver os clipes isoladamente.

Depois que a shot list existe, a chamada à API se torna mecânica — que é exatamente o que você quer, pois torna as chamadas retentáveis e reproduzíveis.

Escreva prompts por plano para flux-3-max/text-to-video

Um bom prompt por plano é estruturado, não conversacional. Em vez de escrever uma única string longa em formato livre, componha cada prompt com um pequeno número de parágrafos rotulados. Isso torna os prompts comparáveis (diff), reutilizáveis e fáceis de ajustar quando um único elemento falha.

Estrutura em cinco partes

1. Sujeito — quem ou o quê, incluindo os detalhes de continuidade que você fixou (aparência, figurino, características do produto).
2. Ação — um único movimento ou estado contínuo, descrito no presente.
3. Ambiente — local, hora do dia, textura da luz, paleta de cores.
4. Câmera — enquadramento mais movimento, usando seu vocabulário fixo. A próxima seção aprofunda isso.
5. Áudio — a intenção de ambiência e foley para este plano.

Combine-os em uma ordem fixa, para que sua própria depuração permaneça consistente:

CONTINUITY = (
    "a minimalist ceramic pour-over coffee dripper, matte white, "
    "on a warm oak counter, soft morning window light from the left, "
    "muted natural palette"
)

def shot_prompt(subject, action, setting, camera, audio):
    return (
        f"{subject}. {action}. {setting}. "
        f"Camera: {camera}. Audio: {audio}."
    )

prompt = shot_prompt(
    subject=f"{CONTINUITY}",
    action="steam rising steadily as water slowly blooms the coffee grounds",
    setting="kitchen counter at dawn, shallow depth of field",
    camera="medium close-up, slow push in, no shake",
    audio="quiet room tone, soft water pour, faint steam hiss",
)

Mantenha os planos visualmente consistentes

O hábito único de maior alavancagem é o bloco de continuidade compartilhado. Coloque-o no início de cada segmento de sujeito e mantenha-o idêntico em todos os planos da sequência. Quando um plano apresentar deriva visual, você pode bissectar o problema: é o bloco de continuidade ou a ação específica do plano?

Mais dois hábitos que reduzem a deriva:

• Evite adjetivos contraditórios. “Cinematográfico documental handheld estático” são três instruções conflitantes. Escolha uma.
• Descreva a luz apenas uma vez. Se o bloco de continuidade diz luz da manhã à esquerda, não deixe um plano posterior introduzir uma luz fluorescente vinda de cima — a menos que essa mudança seja intencional.

O que omitir dos prompts

Tire a proporção de tela, o comprimento de saída e outros parâmetros técnicos da descrição textual e passe-os como parâmetros da requisição quando a API os expuser. A descrição textual diz o que é o plano; os parâmetros dizem como ele é entregue. Misturar os dois torna ambos mais difíceis de alterar.

Controle o movimento de câmera

O movimento de câmera é a dimensão mais fácil de deixar ao acaso e a que mais afeta se uma sequência parece dirigida. Se você não especificar, o modelo moverá a câmera de alguma forma; movimento não especificado se manifesta como deriva, e a deriva é o que faz o material gerado parecer filmado por acidente.

Trate o movimento como um pequeno vocabulário fechado

Não improvise a linguagem de câmera para cada plano. Defina um pequeno conjunto de movimentos e reutilize-o:

• Câmera fixa — sem movimento. A opção mais segura para detalhes de produto e primeiros planos.
• Push in / pull out — mover em direção ao sujeito ou para longe dele. Bom para ênfase e revelação.
• Pan à esquerda / pan à direita — rotação horizontal. Útil para estabelecer espaço.
• Tilt up / tilt down — rotação vertical. Use com moderação; lê-se como dramático.
• Tracking — mover junto com o sujeito. Exige um sujeito claramente em movimento como âncora.

Escreva-os no segmento de câmera, seguidos de uma instrução negativa que suprime o resto do movimento: Camera: slow push in, no shake, no handheld drift.

A cláusula negativa importa. Dizer apenas “push in” deixa espaço para o modelo adicionar tremor; dizer “push in, sem tremor” estreita o escopo.

Faça o movimento servir ao papel do plano

O movimento deve servir à edição. Um mapeamento prático:

• Plano de estabelecimento — um movimento claro (push in lento ou pan suave), dando ao olhar um ponto de pouso.
• Plano de detalhe — câmera fixa. O próprio detalhe já é visualmente denso; o movimento competiria com ele.
• Transição — use movimento consistente em planos adjacentes (ambos push in, ambos pan na mesma direção) para que o corte pareça intencional mesmo sem efeitos de transição.
• Plano principal — um movimento deliberado, nunca dois combinados.

Apenas um movimento por plano

Movimentos combinados (“pan à direita enquanto faz push in e tilt up”) produzem resultados turvos. Se um beat exige um movimento de câmera complexo, divida-o em dois planos. Sua etapa de montagem pode uni-los, enquanto você mantém controle de frame sobre o corte.

Consistência de movimento na sequência

Decida com antecedência o movimento dominante da peça inteira — por exemplo, “todos os planos fazem push in lento” — e desvie apenas quando precisar de um efeito. Sequências com direção de movimento consistente parecem ter intenção autoral; sequências com movimento aleatório parecem geradas.

Use áudio nativo no pipeline

A geração de áudio nativo muda a arquitetura do pipeline de vídeo curto. No fluxo tradicional, você primeiro gera vídeo sem som e depois roda uma etapa separada de áudio — seja um modelo de texto para áudio, seja uma biblioteca licenciada de foley e música — e então alinha os dois no editor. Cada etapa é outro serviço, outra credencial, outro modo de falha e outro lugar onde o tempo pode dessincronizar.

Quando o modelo de vídeo gera áudio inline, som e imagem são produzidos no mesmo passo de inferência, então se alinham naturalmente com o que acontece na tela. No momento em que a água é despejada, o som do despejo corresponde à ação de despejar. Isso elimina quase todo o trabalho de alinhamento.

Dois pipelines, uma diferença

Separate audio stage:            Native audio:
  shot -> video (silent)           shot -> video + audio
       -> audio generation              -> assemble
       -> alignment / mixing
       -> assemble

O benefício prático é menos peças móveis. A restrição prática é que você precisa planejar o som no prompt, não depois.

Planeje os planos em torno do som

Como o áudio faz parte da geração, escreva-o como parte do plano, não como um complemento posterior:

• Nomeie o som dominante. Audio: water pouring, gentle hiss é melhor que Audio: pleasant kitchen sounds.
• Mantenha esparso. Um ou dois elementos claros por plano. Descrições de áudio em camadas tendem a se misturar.
• Decida a música conscientemente. Se você planeja colocar uma trilha musical sobre a peça inteira no editor, deixe o áudio dos planos apenas com ambiência, para que não brigue com a trilha.
• Pense na continuidade do som. Assim como a continuidade visual, a continuidade de áudio entre cortes ajuda — o mesmo ruído de ambiente nos planos adjacentes faz uma sequência parecer acontecer no mesmo lugar.

Onde o editor ainda vence

O áudio nativo não substitui o editor. Ele substitui a etapa de alinhamento. Você ainda precisa de normalização final de volume e, se usar música, de uma etapa de mixagem que abaixe o diálogo e o foley sob a trilha. Reserve orçamento para isso no seu pipeline, mas muito menos do que com uma etapa separada de geração.

Uma requisição executável e o fluxo de montagem

Com a shot list e o construtor de prompts em mãos, a camada de requisição fica fina. As decisões-chave são: como chamar o modelo, como lidar com ordem e novas tentativas, e como entregar os resultados à montagem.

O loop de orquestração

import time

SHOTS = [
    # your planned shot list from the earlier step
]

def generate_shot(shot, attempt=0):
    payload = {
        "model": "flux-3-max/text-to-video",
        "prompt": build_prompt(shot),
        # pass delivery parameters here, not in the prose:
        # aspect ratio, length, etc. per the API reference
    }
    try:
        return client.generate(payload)
    except TransientError:
        if attempt >= 3:
            raise
        time.sleep(2 ** attempt)
        return generate_shot(shot, attempt + 1)

def run_sequence(shots):
    results = {}
    for shot in shots:
        results[shot["id"]] = generate_shot(shot)
    return [results[s["id"]] for s in shots]

Três coisas tornam esse loop seguro para produção, e não apenas uma demonstração:

• Iteração ordenada. Gerar na ordem do roteiro significa que uma falha parcial deixa um prefixo que você pode revisar, e reexecutar apenas os planos ausentes é direto.
• Resultados armazenados por chave. Armazene as saídas pelo id do plano, não pela posição na lista. Se o terceiro plano falhar e for regenerado, você sobrescreve pela chave em vez de acrescentar novamente.
• Novas tentativas limitadas com backoff. Falhas transitórias são normais em qualquer API de geração. Limite o número de tentativas para que um único plano ruim não trave a tarefa inteira.

Entrega para a montagem

Seu loop de geração deve produzir um manifesto — a lista de planos com referências às saídas — e parar por aí. A montagem é uma etapa separada que consome esse manifesto: ela corta cada clipe na duração pretendida, aplica transições, coloca a trilha musical e normaliza o volume.

{
  "sequence": [
    {"id": "s1", "clip": "out/s1.mp4", "trim": "keep_first_portion"},
    {"id": "s2", "clip": "out/s2.mp4", "trim": "keep_first_portion"}
  ],
  "audioStrategy": "native_bed_plus_music"
}

Separar montagem de geração é o que torna todo o pipeline reproduzível: você pode regenerar um plano, colocá-lo no manifesto e renderizar o corte final novamente sem tocar em mais nada.

Checklist de produção e armadilhas comuns

Um pipeline de vídeo curto é confiável quando as partes chatas se tornam chatas. Antes de escalar a produção, passe por estas verificações.

Consistência

• O bloco de continuidade é idêntico em cada plano de uma sequência.
• O vocabulário de câmera é fechado e reutilizado, não improvisado.
• A direção da luz e a paleta de cores são declaradas uma vez e não se contradizem depois.
• Revise os planos em ordem — problemas de continuidade são invisíveis quando os clipes são vistos isoladamente.

Novas tentativas e idempotência

• Os resultados são indexados pelo id do plano, para que a regeneração sobrescreva em vez de duplicar.
• As novas tentativas são limitadas e usam backoff; um plano que falha permanentemente deve falhar de forma ruidosa, não silenciosa.
• O manifesto de planos é a única fonte de verdade do que foi gerado — persista-o junto com as saídas.

Controle de custos

A geração é cobrada pelo trabalho que o modelo realiza, então sua principal alavanca é quantos planos você gera e quantas vezes os regenera. Controles práticos: fixe a shot list antes de gerar, revise um plano representativo de cada sequência antes de renderizar os demais e evite reexecuções especulativas de planos que já passaram na revisão. Ao planejar o volume, consulte os preços atuais no painel de preços do site.

Revisão de saída

• Assista a cada sequência de ponta a ponta na velocidade real de reprodução, não clipe por clipe.
• Verifique o áudio contra a imagem: o som corresponde àquele momento?
• Verifique especialmente os dois primeiros segundos — é ali que a atenção do vídeo curto é ganha ou perdida.
• Mantenha um pequeno conjunto de prompts de referência comprovadamente bons e compare novas saídas com eles quando a qualidade parecer cair.

Armadilhas comuns

• Prompt gigantesco. Um prompt descrevendo a cena inteira produz um plano longo e sem foco. Divida-o.
• Duração escrita no texto descritivo. Expresse pontos de tempo na etapa de edição, não no texto do prompt.
• Movimento de câmera aleatório. Movimento não especificado deriva; especifique o movimento e suprima o resto.
• Tratar áudio como uma decisão de produto separada. Planeje o som nos planos e depois faça a mixagem no editor.

O fluxo de trabalho deste guia — planejar planos, estruturar prompts, controlar movimento de câmera, usar áudio nativo e orquestrar com um manifesto — transforma flux-3-max/text-to-video de um gerador imprevisível em um passo de renderização confiável no pipeline que você possui.