Como chamar flux-3-max/text-to-video pela API HiAPI: guia com curl e Python

O que flux-3-max/text-to-video faz e quando usá-lo

flux-3-max/text-to-video é o endpoint de texto para vídeo na HiAPI: você envia um prompt que descreve uma cena e o modelo retorna um clipe de vídeo gerado. Ele é a ferramenta adequada quando você tem uma ideia em texto em vez de material pronto — por exemplo, um teaser de produto, um vídeo curto para redes sociais, uma prévia de storyboard ou planos vazios gerados em lote — e deseja tratar a geração como uma tarefa hospedada em vez de executá-la por conta própria.

Ele se aplica a fluxos de trabalho em que o vídeo é apenas uma etapa de um processo maior. Um gerador de roteiros produz prompts, flux-3-max/text-to-video os converte em clipes de vídeo e sua aplicação armazena ou entrega o resultado. Como a chamada é assíncrona, ele também serve para serviços de backend que não podem manter uma requisição aberta durante o tempo de renderização.

Não o use quando você precisar de edição quadro a quadro de um vídeo existente ou quando seu prompt for, na prática, apenas uma imagem estática — para este último caso, o endpoint de texto para imagem é mais barato e mais rápido. Se a saída precisar reagir a um material fornecido, use a variante de imagem para vídeo. Considere flux-3-max/text-to-video como a porta de entrada para a geração de clipes a partir de prompts e projete sua integração em torno do envio de tarefas, e não de respostas síncronas.

Estrutura da requisição: endpoint, autenticação e payload

Cada requisição a flux-3-max/text-to-video tem três partes: o caminho do endpoint, o cabeçalho de autenticação e um corpo JSON que indica o modelo e suas entradas.

Autenticação

A HiAPI usa token bearer. Coloque sua chave de API no cabeçalho Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Mantenha a chave no lado do servidor. Não a incorpore em código de cliente nem a envie ao repositório; em desenvolvimento, carregue-a de uma variável de ambiente e, em produção, de um gerenciador de segredos.

Identificador do modelo

No corpo da requisição, o campo model seleciona o endpoint. Use o identificador exato flux-3-max/text-to-video; um erro de digitação aqui é a causa mais comum de requisições rejeitadas.

Estrutura do payload

O corpo mínimo contém o nome do modelo e o prompt:

{
  "model": "flux-3-max/text-to-video",
  "prompt": "ao amanhecer, um drone sobrevoa lentamente uma floresta de pinheiros coberta de névoa, iluminação cinematográfica"
}

Os campos opcionais — duração e a chave de áudio nativo — são abordados na próxima seção. Como a geração é assíncrona, a resposta imediata a este POST é um objeto de tarefa com um identificador que você precisa consultar, em vez de um vídeo pronto. Projete seu código para ler primeiro esse identificador e o restante depois.

Controlar a duração e o áudio nativo

Dois controles no nível da requisição determinam o resultado: a duração do clipe e se o modelo gera áudio junto com o vídeo.

Duração

Defina o comprimento do clipe no payload por meio do campo duration. Escolha a menor duração que atenda à narrativa — clipes curtos renderizam mais rápido, são mais fáceis de revisar e você sempre pode solicitar outro depois. Antes de enviar, valide o valor conforme a faixa documentada de flux-3-max/text-to-video; durações fora dessa faixa são rejeitadas no envio, e detectar isso localmente economiza uma ida e volta.

Áudio nativo

A chave de áudio nativo define se o modelo gera uma faixa de áudio junto com o clipe. Ative quando o vídeo for assistido com som e desative quando ele for assistido sem som, legendado ou com trilha adicionada separadamente na pós-produção. Gerar áudio que você vai descartar apenas aumenta o tempo da tarefa sem benefício.

Escolha com consciência

Evite deixar os valores padrão decidirem por você. Para uma revisão rápida de storyboard, um clipe curto e sem som geralmente basta. Para um material final de redes sociais, um clipe mais longo com áudio nativo pode ser o objetivo. Codifique essa escolha na configuração da aplicação, em vez de codificá-la no ponto de chamada, para que você possa alterá-la por funcionalidade sem modificar o código da requisição. Envie apenas os campos que você realmente deseja substituir e deixe que o endpoint aplique os padrões aos demais.

Requisição curl funcional

A forma mais rápida de confirmar credenciais e payload é enviar uma tarefa com uma chamada curl.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "um barquinho de papel flutua por uma rua encharcada pela chuva, luzes de rua quentes, profundidade de campo rasa",
    "duration": 5,
    "native_audio": false
  }'

Defina HIAPI_BASE_URL e HIAPI_API_KEY no shell antes. Os valores de duração e áudio aqui são apenas exemplos — use valores dentro da faixa documentada para o modelo.

Ler a resposta imediata

A resposta é um objeto de tarefa, não um vídeo. Ele contém um job_id (ou identificador equivalente) e um status como queued ou processing. Guarde esse identificador; ele é o seu handle para todas as chamadas subsequentes. Se a resposta parecer um objeto de erro, verifique o código de status e a mensagem antes de tentar novamente — payloads malformados falham da mesma forma todas as vezes.

Um envio bem-sucedido significa apenas que a tarefa foi aceita, nada mais. Não procure uma URL de vídeo na primeira resposta; ela não estará lá até que a tarefa seja concluída.

Lidar com o ciclo de vida de tarefas assíncronas

A geração de vídeo leva de segundos a minutos, então a HiAPI a modela como uma tarefa. Seu cliente envia uma vez e depois verifica o status até que a tarefa atinja um estado terminal.

Estados

A tarefa vai de queued para processing e depois para um estado terminal — completed ou failed. Apenas estados terminais são finais; qualquer estado intermediário significa continuar esperando.

Consultar sem bombardear

Consulte o endpoint de status usando o identificador de tarefa que você guardou. Duas regras mantêm a consulta saudável:

• Espere entre consultas. Comece com um intervalo curto e faça backoff gradual, ou use um intervalo fixo claramente maior que o tempo típico de fila. Bombardear o endpoint de status não traz benefício.
• Defina um limite. Limite o tempo total de espera e o número total de tentativas. Se a tarefa ainda não estiver concluída nesse prazo, escale o problema para sua aplicação em vez de entrar em loop infinito.

Em manipuladores web, não bloqueie a thread da requisição em um loop de consulta. Envie, armazene o identificador da tarefa, retorne imediatamente e deixe um worker em segundo plano ou o cliente consultar até o fim do ciclo de vida. Em cenários de processamento em lote, um loop simples com sleep é suficiente.

Ler o resultado

Quando a tarefa for reportada como completed, a resposta carrega uma referência de saída — uma URL de vídeo ou handle de material que sua aplicação pode baixar ou transmitir. Em caso de falha, leia o campo error; ele normalmente indica o motivo (parâmetro inválido, recusa de conteúdo, erro interno). Registre o identificador da tarefa junto com a mensagem de falha para que uma solicitação de suporte ou nova tentativa tenha base. Nunca trate um campo de saída ausente como sucesso — verifique o status explicitamente.

A mesma requisição em Python

O fluxo curl mapeia diretamente para Python. Um cliente mínimo precisa de envio, loop de consulta e tratamento de erros suficiente para distinguir uma requisição inválida de uma tarefa lenta.

import os, time
import requests

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

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

Notas de implementação

raise_for_status() separa erros de transporte e HTTP (autenticação, payload malformado) de falhas no nível da tarefa, que aparecem dentro de uma resposta bem-sucedida. A verificação de failed lê explicitamente o campo error em vez de presumir que o status seja completed. O limite de tentativas transforma uma espera ilimitada em uma exceção previsível.

Em produção, envolva a consulta com uma política de Retry para erros transitórios de rede e reutilize uma única requests.Session. Se você executar muitas tarefas, mova wait para uma thread de trabalho em vez de deixá-lo no caminho da requisição.

Diagnosticar falhas comuns

A maioria dos problemas de integração se encaixa em algumas categorias. Cada uma tem uma forma concreta de verificação.

Erros de autenticação

401 ou 403 significam chave ausente, expirada ou malformada. Confirme que o cabeçalho Authorization existe, que usa o esquema Bearer e que a variável de ambiente realmente está preenchida no runtime — não apenas no seu shell.

Payload malformado

400 geralmente significa que o corpo da requisição não corresponde ao schema. Verifique se o JSON é analisável, se model é exatamente flux-3-max/text-to-video e se a requisição envia Content-Type: application/json. Use uma biblioteca JSON para serializar em vez de montar strings manualmente.

Valores de parâmetro inválidos

Duração fora da faixa documentada, nome de campo desconhecido ou tipo errado na chave de áudio causam rejeição no envio. Valide localmente conforme os parâmetros da documentação do modelo antes de enviar.

Consulta prematura

Consultar imediata e repetidamente após o envio não faz a tarefa terminar mais rápido. Use backoff ou intervalo fixo e deixe o objeto de tarefa informar quando ele já saiu do estado queued.

Falhas de tarefa não tratadas

Uma tarefa que chega a failed não significa necessariamente um bug na sua requisição — pode ser recusa de conteúdo ou erro interno. Leia a mensagem de erro, registre o identificador da tarefa e decida se tenta novamente com um prompt modificado ou escala o problema.

Tratar a resposta de envio como resultado

Se seu código espera uma URL de vídeo imediatamente após o envio, ele vai falhar. A primeira resposta é uma tarefa; apenas o estado terminal carrega a saída. Com essas seis verificações em vigor, a maioria dos problemas de integração se resolve.