Como usar a API hiapi para edição de vídeo com IA via flux-3

O termo "edição" aqui tem um significado específico: o flux-3 (FLUX.3 Video, da Black Forest Labs) estende um clipe existente — continuando seu movimento, movimento de câmera e som, gerando novas imagens — ou constrói uma tomada a partir de um conjunto ordenado de imagens-chave. Ele não recorta, corta, mascara, faz correção de cor ou qualquer outro tratamento in-place do material existente. Se você veio até aqui procurando um editor de vídeo, o FAQ abaixo é o caminho mais rápido para decidir, antes de escrever qualquer código, se o flux-3 é realmente adequado para você.

O que ele faz muito bem: pegar um vídeo que você já tem e gerar uma continuação, mantendo o mesmo sujeito, linguagem de câmera e áudio — útil para estender uma tomada que termina cedo demais, ou para encadear vários clipes gerados em uma tomada mais longa. O outro modo recebe um conjunto de imagens estáticas como quadros-chave ordenados e gera o movimento entre eles, o que funciona como uma edição baseada em storyboard, embora não envolva nenhum vídeo existente.

1. O que você precisa

Uma chave de API hiapi do painel (sk-...). O flux-3, como todos os outros modelos hiapi, é chamado pela API de tarefas unificada, então não há nenhuma configuração específica de modelo aqui — se você já chamou qualquer outro modelo de vídeo hiapi, você já tem tudo o que precisa.

2. Exemplo mínimo funcional

Crie uma tarefa e depois faça polling dela (ou use callback — veja Padrões de produção) até que ela atinja um estado terminal.

# 1. Criar tarefa — modo de continuação (start_video)
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "continue a panorâmica, a câmera continua derivando para a direita, mantenha a mesma iluminação",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Polling até o estado terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video é uma URL HTTPS pública apontando para um MP4 (o material de origem tem limite de 50MB e 15 segundos) — é o clipe que o flux-3 continua. duration é um inteiro de 5 a 20 segundos que controla o comprimento do trecho novo gerado, não o comprimento da saída composta. resolution é 720p ou 1080p; aspect_ratio aceita auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 ou 9:16. generate_audio é booleano — quando true, o som ambiente gerado pelo modelo é incorporado diretamente no MP4 de saída, em vez de virar um arquivo de áudio separado. Defina draft: true ao iterar no prompt; tarefas de rascunho são mais baratas, mas forçam resolution a ser apenas 720p (requisições com draft: true e resolution: "1080p" juntas são rejeitadas).

Storyboard por quadros-chave (não é edição de material existente)

O outro modo de entrada usa image_urls no lugar de start_video — um array ordenado de 1 a 10 URLs de imagem, que o flux-3 trata como storyboard, gerando o movimento que as conecta em sequência:

{
  "model": "flux-3",
  "input": {
    "prompt": "dolly suave passando por cada cena em sequência",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls e start_video são duas formas distintas de tarefa no mesmo modelo — não envie ambos em uma mesma requisição. Use image_urls quando estiver construindo uma tomada do zero a partir de imagens estáticas; use start_video quando já tiver material gerado (ou de origem) que deseja continuar adiante.

3. Padrões de produção

Use callback em vez de polling em escala. Passe o objeto callback no mesmo corpo da requisição, em vez de fazer polling em loop:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" dispara uma única vez, quando a tarefa atinge qualquer estado terminal — succeeded ou failed são ambos terminais, então deduplique seu handler de webhook por taskId em vez de assumir que o callback só significa sucesso. O polling via GET /v1/tasks/:id é mais adequado para depuração local, tarefas avulsas de baixa frequência, ou como fallback de reconciliação quando o callback não chega.

Idempotência. Se você não tomar cuidado, retentativas após timeout ou queda de conexão podem criar tarefas duplicadas (e faturáveis) — guarde o id da tarefa retornado na chamada de criação e, antes de cogitar enviar uma nova tarefa, transforme a retentativa em um GET desse id.

As URLs de saída expiram. O campo expireAt em cada entrada de saída não é decorativo — independentemente de você ter sabido do sucesso via callback ou polling, baixe o vídeo e persista no seu próprio armazenamento imediatamente após o sucesso da tarefa.

Falhas de autenticação. Uma chave inválida ou ausente retorna HTTP 401 com o corpo {"error": {"code": "permission_denied", ...}}. Verifique explicitamente esse status/código, em vez de assumir que qualquer resposta não-2xx significa falha na geração em si — "minha chave está errada" e "o modelo rejeitou minha entrada" exigem correções diferentes.

Valide as URLs de mídia antes de enviar. start_video e image_urls validam tipo e formato, mas não verificam se o arquivo naquela URL realmente existe ou é decodificável — uma URL sintaticamente válida mas quebrada ainda cria uma tarefa, que roda por alguns segundos e só então falha, em vez de ser rejeitada já no envio. Antes de conectar URLs a tarefas em lote, confirme que elas realmente resolvem.

4. Páginas relacionadas

• Página do modelo flux-3 — referência completa de parâmetros, playground e os preços atuais por segundo e por resolução para todos os três modos (texto para vídeo, storyboard por quadros-chave e continuação).
• Documentação de criação de tarefas — referência completa de requisição/resposta de /v1/tasks, incluindo as opções de callback.
• Documentação de autenticação — como funcionam o cabeçalho Authorization: Bearer sk-... e os escopos das chaves.
• Controle de primeiro e último quadro em vídeo com IA — uma abordagem relacionada, para modelos que interpolam entre dois quadros estáticos, caso o modo de storyboard com múltiplos quadros-chave do flux-3 não seja granular o suficiente para a sua tomada.
• Preços do hiapi — tarifas atuais (a continuação custa mais que a geração padrão, e o modo rascunho custa menos que ambos — consulte a página ao vivo, em vez de números fixos no código).

5. Perguntas frequentes

O flux-3 consegue recortar, cortar, mascarar ou fazer correção de cor em vídeos existentes? Não. O modo "vídeo para vídeo" do flux-3 é continuação — ele gera imagens novas, continuando o sujeito, o movimento de câmera e o som do clipe de origem. Ele não modifica os quadros que já existem. Nenhum modelo hiapi atual faz edição de linha do tempo (corte/recorte) ou edição por área mascarada em vídeos.

Qual é a diferença entre continuação e storyboard por quadros-chave? A continuação (start_video) requer um arquivo de vídeo existente e o estende. O storyboard por quadros-chave (image_urls) requer apenas imagens estáticas e gera o movimento entre elas — sem vídeo de origem. São entradas mutuamente exclusivas no mesmo id de modelo flux-3.

Posso usar start_video e image_urls na mesma requisição? Não — cada tarefa escolhe um modo. Enviar ambos não é uma forma de entrada suportada.

draft: true funciona no modo de continuação? Sim, e é a forma mais barata de iterar no prompt de continuação antes de enviar uma execução em resolução plena — mas, como no modo padrão, a continuação em rascunho também fica limitada a 720p.

Por que minha tarefa falhou quase instantaneamente, em vez de levar o tempo normal de geração? A causa mais comum é que a entrada de start_video ou image_urls na verdade não resolveu para um arquivo válido no momento da requisição — a API aceita URLs sintaticamente corretas sem buscá-las de forma síncrona, então um link quebrado se manifesta como um estado failed rápido, em vez de um erro de validação anterior.

Qual o comprimento máximo do clipe de origem no modo de continuação? No máximo 15 segundos e 50MB, em formato MP4. Arquivos de origem maiores ou mais longos não são aceitos como entrada start_video.