Como chamar flux-3-video através da API HiAPI: curl, Python e exemplos de requisição que realmente funcionam

O que flux-3-video oferece através da API

Antes de escrever a primeira linha de código, é útil entender o que o modelo flux-3-video realmente faz através da API HiAPI. A família de endpoints cobre dois modos de chamada, que compartilham a mesma estrutura de requisição, além de uma capacidade opcional de áudio que você pode ativar ou ignorar conforme o caso de uso.

Dois modos de chamada

• Text-to-video — você envia um prompt de texto e recebe um novo clipe de vídeo gerado. Use este modo quando tiver apenas uma ideia e quiser que o modelo gere movimento, composição e ritmo.
• Continuação de vídeo — você envia um clipe existente (ou uma referência a ele) junto com uma instrução, e o modelo o estende adiante. Use este modo quando já tiver material e quiser mais conteúdo sem emendas visíveis.

Áudio nativo

O modelo também pode produzir áudio nativo junto com o vídeo, controlado por parâmetros opcionais no mesmo payload da requisição. Como esses parâmetros são opcionais, fluxos de trabalho puramente de vídeo podem ignorá-los completamente — basta omitir os campos de áudio e a requisição se comporta exatamente como se eles não existissem.

O modelo mental central no qual o restante deste guia se apoia é: não são duas APIs independentes, nem dois tutoriais separados. São duas formas da mesma requisição; uma vez entendido o esqueleto compartilhado, alternar entre elas é apenas substituir algumas entradas. Todo o resto — credenciais, cabeçalhos, identificador do modelo, tratamento da resposta — permanece igual.

Esse design é intencional. Isso significa que seu código de autenticação, tratamento de erros, lógica de retry e análise de resposta precisam ser escritos uma única vez e podem ser reutilizados nos dois modos; adicionar áudio depois também não obriga você a reescrever nada.

Autenticação, endpoint e anatomia da requisição

Cada chamada a flux-3-video segue o mesmo esqueleto. Aprenda-o uma vez e os dois modos de chamada se tornam variantes do mesmo tema.

Credenciais

A HiAPI autentica requisições com uma API key. Você a passa através de um cabeçalho, normalmente como bearer token. Não escreva a chave no código-fonte — leia-a de uma variável de ambiente ou de um gerenciador de segredos, garantindo que ela nunca entre no controle de versão:

export HIAPI_API_KEY="your-key-here"

Endpoint e identificador do modelo

As chamadas vão para a URL base da API HiAPI, e o payload especifica explicitamente o modelo através do identificador flux-3-video. Colocar o nome do modelo no corpo da requisição em vez de codificá-lo na URL significa que o mesmo código cliente pode apontar para outro modelo depois com apenas uma linha alterada.

A estrutura de payload compartilhada

Independentemente do modo, o payload é um objeto JSON que conceitualmente contém três partes:

• O campo model — sempre flux-3-video.
• As entradas que definem o modo — no text-to-video, um prompt; na continuação, o clipe de origem mais um prompt. Esta é a única parte que muda substancialmente entre os dois modos.
• Modificadores opcionais — parâmetros de áudio e outros ajustes. Omiti-los resulta no comportamento padrão.

A pseudoestrutura de uma requisição é assim:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

A ideia geral é exatamente essa: um identificador de modelo, um objeto input aninhado que carrega os campos específicos do modo e chaves opcionais adicionadas apenas quando necessário. As seções seguintes detalham cada modo.

Text-to-video: sua primeira requisição curl funcional

Abaixo está uma requisição mínima, mas completa, que gera um vídeo a partir de um prompt. Ela assume que HIAPI_API_KEY já está exportada no seu shell.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

O papel de cada campo

• Authorization — carrega seu bearer token. Sem ele, a requisição é rejeitada antes de qualquer geração começar.
• Content-Type: application/json — o corpo é JSON, então declare isso; esquecê-lo é uma causa comum de respostas 4xx confusas.
• model — identifica flux-3-video como o modelo de destino.
• input.prompt — a única entrada criativa obrigatória no modo text-to-video. Escreva como uma descrição de plano: sujeito, movimento, composição, luz, atmosfera.

Pontos de escrita de prompt que valem a pena

Como o prompt é a única alavanca criativa neste modo, sua qualidade determina diretamente o resultado. Dois hábitos ajudam:

• Descreva o movimento, não apenas o conteúdo. "A dolly shot through…" (um travelling de aproximação atravessando…) dá ao modelo um comportamento de câmera que pode ser animado; uma descrição estática não lhe dá nada em que se apoiar.
• Seja específico. Indícios concretos de luz e material ("wet asphalt" — asfalto molhado, "neon reflections" — reflexos de neon) geralmente produzem imagens mais coerentes do que adjetivos abstratos.

Depois de executar esta requisição e inspecionar a resposta, você validou a chave, os cabeçalhos e o payload básico — a base de tudo o que vem a seguir.

Continuação de vídeo: estender um clipe existente

A continuação reutiliza o esqueleto da seção anterior, mas a forma do objeto input muda. O prompt deixa de existir sozinho e passa a ser emparelhado com o clipe de origem que o modelo deve estender.

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

O que muda em relação ao text-to-video

• Surge uma entrada de vídeo. Você fornece o clipe existente sobre o qual o modelo deve construir. Esta é a diferença decisiva entre os dois modos.
• O prompt passa a ser orientador, não gerativo. No text-to-video você descreve a cena inteira; aqui você descreve o que acontece a seguir. Escreva como uma instrução de continuação: para onde a câmera vai, o que entra em cena, como a cena evolui.
• Todo o resto é idêntico. Mesmo endpoint, mesmos cabeçalhos, mesmo identificador de modelo, mesmo invólucro input. Seu código cliente só precisa ramificar na hora de montar o payload.

Manter a consistência na emenda

O modelo precisa corresponder à aparência do clipe de origem para evitar um corte visível. Instruções curtas e específicas que preservam o estilo existente costumam funcionar melhor do que descrições longas que reimaginam a cena. Se a primeira continuação desviar, aproxime o prompt do conteúdo real do clipe de origem em vez de adicionar mais detalhes em outro lugar.

Nota sobre a referência do clipe

A convenção exata de entrada para o clipe de origem é definida pelo schema de entrada do modelo na HiAPI. Siga esse schema em vez de adivinhar o formato do campo — ele é a fonte autoritativa sobre o que a entrada de continuação aceita.

Adicionar parâmetros de áudio nativo

É aqui que o padrão de modificadores opcionais se prova útil. Os parâmetros de áudio ficam no mesmo objeto input que os demais campos e, como são opcionais, as requisições das duas seções anteriores continuam válidas sem eles.

Onde eles ficam

As configurações de áudio pertencem ao interior de input, lado a lado com prompt e (no modo de continuação) video. Conceitualmente:

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

Manter fluxos puramente de vídeo seguros

A disciplina importante aqui é simples: trate o bloco de áudio como puramente aditivo.

• Não defina explicitamente os campos de áudio com um valor "desligado" — simplesmente os omita. A ausência do bloco é mais limpa do que a desativação explícita e menos propensa a conflitar com mudanças futuras de schema.
• Construa o payload incrementalmente. Comece com o corpo mínimo e adicione a chave audio apenas nos caminhos de código em que o usuário realmente solicita áudio. Assim, seu caminho padrão permanece idêntico aos exemplos puramente de vídeo.
• Antes de integrar áudio em produção, consulte o schema para confirmar os nomes exatos dos flags e os valores aceitos. A nomenclatura dos parâmetros é definida pelo schema de entrada do modelo na HiAPI; o bloco acima apenas mostra o local, sem garantir a grafia dos campos.

Quando ativar

Ative áudio quando a entrega for um clipe final e autossuficiente — conteúdo para redes sociais, apresentações, peças narrativas curtas. Mantenha desligado quando você for adicionar sua própria trilha ou narração posteriormente; gerar áudio que você acabará descartando é desperdício de poder computacional no pipeline.

Como o áudio fica no mesmo payload que todo o resto, não há chamada separada, nem segunda credencial, nem ramificação extra de tratamento de resposta além de ler o que a resposta retorna.

Escrever a mesma requisição em Python

Transcrever a chamada curl para Python é mecânico, porque a estrutura da requisição é idêntica. O exemplo abaixo usa apenas a biblioteca padrão, então roda em qualquer ambiente; se você preferir requests ou httpx, a estrutura se mapeia diretamente.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

Por que está organizado assim

• Uma função, dois modos. O parâmetro video é opcional; quando é None, a função gera uma requisição de text-to-video. Quando é definido, a mesma função gera uma requisição de continuação. Não há cliente separado nem cabeçalhos duplicados.
• O áudio exige ativação explícita. O flag audio é False por padrão, então o bloco de áudio nunca é adicionado a menos que solicitado explicitamente — exatamente o padrão descrito acima.
• A chave vem do ambiente. A API key é lida de HIAPI_API_KEY e nunca codificada diretamente.

Para adaptar, basta substituir as chamadas a print pela ação que seu pipeline exige — gravar a resposta em um manifesto, enfileirar tarefas subsequentes ou notificar alguma fila. A lógica da requisição em si não precisa mudar.

Diagnóstico de falhas e checklist para produção

Quando uma chamada falhar, percorra a lista abaixo em ordem — ela cobre a grande maioria dos problemas.

Checklist de diagnóstico

• 401 ou erro de autenticação — a HIAPI_API_KEY está realmente exportada no shell ou processo que executa o código? Uma chave definida em um terminal não é passada para um job de cron.
• 415 ou erro inesperado de parsing — o Content-Type: application/json está presente? Esquecê-lo é a falha silenciosa mais típica.
• Chamada de continuação retorna 4xx — seu payload inclui o clipe de origem na forma esperada pelo schema de entrada do modelo? Uma referência de clipe malformada falha antes de a geração começar.
• Áudio ausente na saída — o bloco audio realmente entrou no payload? Ao depurar, registre o corpo serializado da requisição; é fácil montar o dicionário e esquecer de anexar a chave.
• input vazio ou truncado — imprima o JSON exato que você está enviando. Quase toda falha "estranha" se resolve ao ver o corpo da requisição que está realmente trafegando.

Antes de ir para produção

• Nunca codifique chaves diretamente. Sempre use variáveis de ambiente ou um gerenciador de segredos.
• Registre tanto o corpo da requisição quanto o da resposta, pelo menos em ambiente de staging. Reproduzir uma falha sem o payload exato é apenas adivinhação.
• Trate campos opcionais como opcionais. Construa o payload incrementalmente — primeiro o corpo mínimo, depois adicione video e, por último, audio apenas quando necessário. Isso mantém seu caminho padrão alinhado aos exemplos da documentação.
• Mantenha a escolha de modo explicitamente visível no seu código. Uma função com um parâmetro video opcional é aceitável; enterrar um booleano três camadas adentro não é.
• Sempre que adicionar um campo, consulte novamente o schema de entrada do modelo na HiAPI. Ele é a referência autoritativa para nomes de parâmetros e formatos aceitos, e estará mais atualizado do que qualquer tutorial.

O ponto central merece ser repetido: text-to-video, continuação e áudio nativo são três variantes da mesma forma de requisição. Aprenda o esqueleto uma vez e cada nova capacidade se torna uma mudança aditiva, não uma reescrita. Bons builds.