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

O que esta integração realmente faz

flux-3-max/keyframes-to-video é uma API de tarefas assíncronas para gerar vídeos a partir de imagens de keyframe. Diferente de endpoints síncronos que retornam o resultado na mesma resposta HTTP, este modelo recebe seus keyframes, cria uma tarefa em segundo plano e retorna um identificador de tarefa que você pode usar para verificar o progresso.

O ciclo de vida completo tem quatro fases:

1. Autenticação — cada requisição carrega sua chave de API HiAPI.
2. Envio — envie os keyframes e os parâmetros para iniciar a tarefa de vídeo.
3. Polling — consulte repetidamente o status da tarefa até atingir um estado terminal.
4. Obtenção — baixe o vídeo gerado a partir da URL retornada quando a tarefa for concluída com sucesso.

Ter esse ciclo de vida em mente determina como você escreve o cliente: o envio e a obtenção do resultado são chamadas separadas, e sua aplicação precisa tolerar uma tarefa que leva de dezenas de segundos a alguns minutos. Os exemplos em curl e Python abaixo seguem as mesmas quatro fases, para que você possa portar esse fluxo para qualquer linguagem ou executor de jobs.

Obter a chave de API e autenticar

Sua chave de API é emitida no painel da HiAPI. Trate-a como uma senha: ela identifica sua conta e autoriza chamadas faturáveis, portanto nunca deve aparecer no código-fonte, no histórico de commits ou na saída de logs.

A autenticação é transmitida em cada requisição como um cabeçalho HTTP:

Authorization: Bearer $HIAPI_API_KEY

Na prática, armazene a chave em uma variável de ambiente e leia em tempo de execução. Para os exemplos em shell, exporte-a uma vez por sessão:

export HIAPI_API_KEY="your-key-here"

Em Python, leia com os.environ["HIAPI_API_KEY"] em vez de codificar a string diretamente. Adicione o arquivo .env ao .gitignore e, se registrar requisições para depuração, oculte o cabeçalho Authorization antes que ele chegue ao agregador de logs. Se a chave for exposta em algum momento, rotacione-a imediatamente no painel.

Montar a requisição com curl

Enviar uma tarefa de vídeo significa enviar um corpo JSON que especifica o modelo e carrega seus keyframes. Os nomes exatos dos campos de entrada de keyframes e dos parâmetros de geração estão documentados na página do modelo, então use-a como fonte autoritativa; a estrutura abaixo mostra o formato da requisição.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/keyframes-to-video",
    "input": {
      "keyframes": [
        "https://example.com/frame-01.png",
        "https://example.com/frame-02.png"
      ]
    }
  }'

O papel de cada parte:

• model — seleciona flux-3-max/keyframes-to-video, de modo que o mesmo endpoint possa posteriormente rotear para outros modelos sem alterar seu código de transporte.
• input.keyframes — lista ordenada de URLs de imagens. A ordem importa: o primeiro frame ancora o início do clipe, e os frames seguintes guiam os momentos subsequentes.
• Authorization — o cabeçalho bearer descrito acima.
• Content-Type — obrigatório para o corpo JSON.

A resposta é um objeto de tarefa que contém um identificador. Guarde esse ID; ele é o handle para cada polling posterior.

A mesma requisição em Python

A versão em Python espelha a chamada curl. Usar requests mantém o código curto, mas a biblioteca padrão também funciona se você quiser zero dependências.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"


def submit_video_task(keyframe_urls: list[str]) -> str:
    response = requests.post(
        f"{BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "flux-3-max/keyframes-to-video",
            "input": {"keyframes": keyframe_urls},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


task_id = submit_video_task([
    "https://example.com/frame-01.png",
    "https://example.com/frame-02.png",
])
print(task_id)

Dois detalhes que vale manter: o timeout explícito, para que uma conexão travada não bloqueie seu worker para sempre; e raise_for_status(), para que erros 4xx ou 5xx apareçam como exceções em vez de payloads de erro silenciosos. Mantenha a função pequena e pura — ela deve enviar e retornar o ID, nada mais. O polling é outra história.

Consultar o status da tarefa e obter o resultado

A geração de vídeo exige tempo real de computação, então a API não bloqueia até o arquivo aparecer. Em vez disso, você consulta a tarefa até que ela termine. O status succeeded traz a URL de saída; failed traz o erro; qualquer outro valor significa continuar esperando.

import time
import requests


def wait_for_video(task_id: str, poll_interval: int = 5, max_wait: int = 600) -> str:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "succeeded":
            return task["output"]["video_url"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(poll_interval)

    raise TimeoutError(f"task {task_id} did not finish in time")

Notas de design para produção:

• Intervalo de polling — alguns segundos são suficientes. Martelar o endpoint aumenta a carga sem fazer a tarefa terminar mais rápido.
• Prazo limite — sempre limite o tempo total de espera e lance um erro explícito em caso de falha, em vez de repetir para sempre.
• Download — a URL retornada é temporária; busque o arquivo imediatamente após o sucesso da tarefa e mova-o para seu próprio armazenamento.
• Desacoplamento — em uma aplicação web, execute esse loop em um worker em segundo plano e notifique o cliente via webhook ou fila, em vez de manter a requisição HTTP aberta.

Tratar erros e casos extremos

A maioria das falhas de integração se enquadra em quatro categorias.

Erros de autenticação (401/403). A chave está ausente, malformada ou não é mais válida. Verifique se a variável de ambiente foi realmente exportada no processo que faz a chamada — uma armadilha comum é funcionar no shell local, mas faltar a variável no contêiner ou no job cron.

Erros de entrada (4xx). URLs de keyframe inacessíveis, formatos de imagem não suportados ou parâmetros fora da faixa permitida farão o envio ser rejeitado. Valide antes do envio que cada URL de keyframe é acessível publicamente; hosts lentos ou restritos são a causa mais comum de falha de requisições que de resto estão corretas.

Falha da tarefa. Uma tarefa pode ser aceita e depois falhar durante a geração. Sempre verifique o campo de erro, em vez de tratar um polling concluído como sucesso. Registre o ID da tarefa junto com o erro para poder associá-lo a uma solicitação de suporte.

Timeouts e retentativas. Erros de rede no envio geralmente podem ser repetidos com segurança usando backoff. Repetir após um envio bem-sucedido não — você pode criar tarefas duplicadas e incorrer em cobranças duplicadas. Leia a resposta antes de tentar novamente e use também backoff exponencial com jitter no loop de polling.

Um último lembrete de higiene: nunca registre o cabeçalho Authorization e, se as URLs de keyframe contiverem strings de consulta assinadas, limpe-as. Em caso de dúvida sobre os nomes de campos ou limites desse modelo, consulte a documentação de flux-3-max/keyframes-to-video e replique esses valores exatamente no seu cliente.