Como usar a API FLUX 3: guia completo para desenvolvedores

Resposta rápida

FLUX 3 é o modelo multimodal de vídeo da Black Forest Labs para geração de texto-para-vídeo e imagem-para-vídeo com áudio sincronizado. Na CometAPI, o ID do modelo de produção é flux-3. O fluxo assíncrono verificado usa POST /v1/videos para criar uma tarefa, GET /v1/videos/{task_id} para consultar o status e GET /v1/videos/{task_id}/content para baixar o MP4 concluído.

Atualização de disponibilidade (verificada em 24 de setembro de 2026): a Black Forest Labs levou o FLUX 3 Video além da fase de Early Access de julho e disponibilizou a versão inicial de texto-para-vídeo e imagem-para-vídeo de forma geral pela API da BFL e parceiros selecionados em 4 de agosto de 2026. A CometAPI adicionou o ID de modelo de produção flux-3 em seu formato de Video API em 13 de agosto de 2026. Use o anúncio de lançamento da BFL e a página do modelo ativa na CometAPI como fonte de verdade para disponibilidade, campos e preços.

O que mudou desde o Early Access do FLUX 3?

A mudança importante é a disponibilidade operacional. A cobertura inicial focou no lançamento de julho baseado em aplicação, mas o lançamento de agosto da BFL introduziu um endpoint de vídeo invocável, restrições publicadas e preços de produção. Em seguida, a CometAPI expôs o flux-3 por meio do seu fluxo unificado de Video API.

O artigo anterior da CometAPI, FLUX 3 API: Availability, Early Access, Video & Dev, continua útil para o histórico do lançamento e a avaliação preliminar de julho. A comparação mais ampla Best AI Video APIs in 2026 cobre a seleção em nível de mercado. Este guia mantém esses tópicos concisos e foca em requisições funcionais, polling, prompts, controle de custo e uso em produção.

O que é o FLUX 3?

FLUX 3 é a família de modelos multimodais da BFL para vídeo, áudio, imagens e previsão relacionada a ações. A versão de vídeo atual oferece suporte a texto-para-vídeo, imagem-para-vídeo e continuação de vídeo por meio de um único endpoint nativo do provedor.

Para desenvolvedores de vídeo, os destaques são até 20 segundos a 24 fps, saída em HD ou Full HD, áudio sincronizado, fala multilíngue com lip-sync, múltiplos planos em uma única geração e até dez keyframes fixados para controle de imagem-para-vídeo.

Especificações da API do FLUX 3

Quão bom é o FLUX 3 Video?

A BFL relata uma pontuação Elo de texto-para-vídeo de 1135 em sua avaliação de preferência humana all-vs-all. Na mesma comparação publicada, o FLUX 3 empatou com o Seedance 2.0 em preferência de imagem-para-vídeo e ficou à frente dos outros modelos testados.

Esses resultados são evidências úteis de posicionamento, mas são avaliações de preferência humana executadas pelo fornecedor, não um benchmark de produção independente. Eles não medem a latência do gateway, a confiabilidade da fila, a consistência de custos ou a estabilidade de gerações repetidas; portanto, equipes de produção ainda devem avaliar seu próprio conjunto de prompts.

Desempenho de benchmark do FLUX 3

Fonte: Black Forest Labs — FLUX 3 Video, Part 1: Generation.

O que você precisa antes de usar a API do FLUX 3

• Uma conta na CometAPI e uma chave de API armazenada em uma variável de ambiente no backend.
• Um prompt que defina o assunto, o movimento, a direção da câmera, a atmosfera e qualquer áudio ou diálogo necessário.
• Um fluxo robusto de tratamento de jobs, pois a geração de vídeo é assíncrona.
• Crédito suficiente para testes iterativos; a cobrança depende da duração e da resolução geradas.

Crie a chave no dashboard da API da CometAPI. Não a coloque em JavaScript de frontend, pacotes mobile, repositórios públicos ou capturas de tela.

ID do modelo FLUX 3 e endpoints

Como usar a API do FLUX 3 com a CometAPI

Etapa 1: defina sua chave de API

No macOS ou Linux:

export COMETAPI_KEY="your_api_key"

No Windows PowerShell:

$env:COMETAPI_KEY="your_api_key"

Etapa 2: criar um vídeo do FLUX 3

O quickstart do FLUX 3 atual usa uma requisição multipart com model, prompt, seconds e size. Este exemplo solicita um clipe de cinco segundos em 720p:

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=flux-3" \
  -F "prompt=Um barco de papel desliza por um lago parado na luz suave da manhã" \
  -F "seconds=5" \
  -F "size=1280x720"

Esta requisição inicia um job. Não projete o aplicativo para receber um MP4 concluído na mesma resposta HTTP.

Etapa 3: salve o ID da tarefa

Persista o identificador imediatamente após a criação ter sucesso:

{
  "id": "video_task_id",
  "status": "queued"
}

Armazene o task ID junto ao registro do usuário ou do job antes de iniciar o polling. Uma reinicialização de processo não deve perder uma geração que já foi cobrada.

Etapa 4: consulte o status do vídeo

curl https://api.cometapi.com/v1/videos/{task_id} \
  -H "Authorization: Bearer $COMETAPI_KEY"

Comece com um intervalo moderado, como dez segundos. Trate completed, succeeded ou success como estados de sucesso terminais; trate failed, failure, cancelled ou canceled como falhas terminais.

Etapa 5: baixe o MP4

curl https://api.cometapi.com/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  --output flux3_output.mp4

Após a conclusão, copie o arquivo para seu próprio storage de objetos ou pipeline de mídia, em vez de manter uma URL temporária do provedor como ativo permanente.

Workflow completo em Python para geração de vídeo com o FLUX 3

O exemplo a seguir cria um job, salva seu ID, faz polling até a conclusão, verifica estados de falha, valida a assinatura do MP4 e grava a saída em disco.

import os
import time
from pathlib import Path

import requests

api_key = os.environ["COMETAPI_KEY"]
base_url = "https://api.cometapi.com"
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.post(
    f"{base_url}/v1/videos",
    headers=headers,
    files={
        "model": (None, "flux-3"),
        "prompt": (
            None,
            "Uma garrafa de produto gira lentamente sobre pedra preta molhada, "
            "iluminação de contorno suave, lente macro, reflexos realistas.",
        ),
        "seconds": (None, "5"),
        "size": (None, "1280x720"),
    },
    timeout=120,
)
response.raise_for_status()

task = response.json()
data = task.get("data") or {}
task_id = (
    task.get("id")
    or task.get("task_id")
    or data.get("id")
    or data.get("task_id")
)
if not task_id:
    raise RuntimeError(f"A resposta de criação não contém task ID: {task}")

while True:
    response = requests.get(
        f"{base_url}/v1/videos/{task_id}",
        headers=headers,
        timeout=60,
    )
    response.raise_for_status()
    task = response.json()
    data = task.get("data") or {}
    status = str(task.get("status") or data.get("status") or "").lower()
    progress = task.get("progress") or data.get("progress") or "unknown"
    print(f"Status: {status or 'unknown'}; progresso: {progress}")

    if status in {"failed", "failure", "cancelled", "canceled"}:
        raise RuntimeError(f"Falha na geração de vídeo: {task}")
    if status in {"completed", "succeeded", "success"} or progress == "100%":
        break
    time.sleep(10)

response = requests.get(
    f"{base_url}/v1/videos/{task_id}/content",
    headers=headers,
    timeout=300,
)
response.raise_for_status()
video = response.content

if len(video) < 12 or video[4:8] != b"ftyp":
    raise RuntimeError("A resposta de conteúdo não é um arquivo MP4 não vazio")

output_dir = Path("output")
output_dir.mkdir(parents=True, exist_ok=True)
output_path = output_dir / f"{task_id}.mp4"
output_path.write_bytes(video)
print(f"Salvo: {output_path} ({len(video)} bytes)")

Como usar imagem-para-vídeo e keyframes

A página do FLUX 3 na CometAPI lista imagem-para-vídeo como um recurso compatível. Seu exemplo público atual demonstra texto-para-vídeo, portanto, verifique a documentação do gateway ao vivo antes de assumir que um campo de imagem de referência copiado de outro modelo funcionará inalterado.

A API nativa da BFL é explícita: imagem-para-vídeo usa mode i2v e o campo keyframes. Uma imagem fixa o quadro inicial; duas imagens podem fixar o início e o fim; até dez imagens temporizadas podem criar um storyboard de um clipe contínuo.

Exemplo nativo de keyframes da BFL

curl -X POST https://api.bfl.ai/v1/flux-3-video \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v",
    "prompt": "Eles correm por um beco iluminado por lanternas enquanto a câmera os acompanha por trás.",
    "keyframes": [
      [0, "data:image/png;base64,<first-frame>"],
      [8, "data:image/png;base64,<last-frame>"]
    ],
    "duration": 8
  }'

Mantenha parâmetros nativos do provedor e do gateway em adaptadores separados. A BFL usa campos como mode, keyframes, start_video, resolution e draft; o exemplo verificado da CometAPI usa model, prompt, seconds e size.

Parâmetros da API do FLUX 3 explicados

Como escrever prompts melhores para o FLUX 3

O guia de prompts para vídeo da BFL recomenda direção clara para o assunto e a ação, câmera, cena e atmosfera, qualidade do movimento e continuidade. Para cenas guiadas por áudio, especifique diálogo, voz, efeitos sonoros e ambiência.

Uma estrutura prática de prompt

Assunto + Ambiente + Ação + Câmera + Iluminação
+ Diálogo/Voz + Efeitos Sonoros + Ambiência + Restrições

Prompt cinematográfico

Um ciclista solitário percorre uma rua neon encharcada de chuva à meia-noite.
A câmera começa baixa ao lado da roda traseira e então sobe para um travelling suave.
Reflexos se estendem sobre o asfalto molhado sob luz ciano e magenta em movimento.
Áudio: chuva constante, som da corrente, tráfego distante, sem música, sem diálogo.
Mantenha o mesmo ciclista, bicicleta, jaqueta e clima durante todo o plano.

Prompt de vídeo de produto

Uma máquina de espresso premium em aço inox sobre um balcão de pedra escura.
Comece com um close macro de gotas d’água no corpo metálico.
Orbite no sentido horário enquanto a máquina extrai; o vapor recebe luz lateral quente.
Termine em um ângulo heroico de três quartos com a xícara em primeiro plano.
Áudio: vibração da bomba, chiado do vapor, contato da cerâmica, ambiência de café silencioso.
Não altere o formato do produto, a posição do logo, o material ou a cor.

Prompt com diálogo e áudio nativo

Um jovem chef trabalha sozinho em uma pequena loja de ramen em Tóquio à noite.
Comece fechado no caldo fervendo, depois afaste enquanto o chef coloca uma tigela.
Iluminação quente de tungstênio, reflexos naturais, movimento documental de câmera na mão.
O chef diz baixinho em japonês: 「お待たせしました。」
Áudio: caldo borbulhando, chuva suave do lado de fora, tráfego distante.
Sem legendas e sem música de fundo.

Um prompt como “faça um vídeo cinematográfico de uma loja de ramen” deixa movimento, enquadramento, som e continuidade sem especificação. Uma direção explícita produz um briefing de produção mais testável.

Preços da API do FLUX 3

A precificação da BFL é específica por fluxo: renderizações completas de texto-para-vídeo e imagem-para-vídeo custam $0.17/s em HD ou $0.29/s em FHD, com Modo Draft em HD a $0.06/s. Continuação de vídeo custa $0.43/s em HD ou $0.54/s em FHD, com drafts em HD a $0.12/s. A CometAPI atualmente lista o flux-3 a $0.136/s para 720p e $0.232/s para 1080p. Verifique os preços ao vivo antes de um lote grande.

Lendo as duas últimas colunas: os valores são mostrados primeiro para HD/720p e em segundo para FHD/1080p.

Como reduzir custos de iteração

• Prototipe em 720p antes de mover um prompt selecionado para 1080p.
• Use clipes de cinco segundos para validar composição, movimento e interpretação do prompt.
• Altere uma variável principal do prompt por vez.
• Ao usar a API nativa da BFL, teste o Modo Draft antes de um render de qualidade total.
• Armazene prompts bem-sucedidos e decisões de referência nos metadados do aplicativo.

FLUX 3 vs Wan 3.0 vs Seedance 2.5

Compare FLUX 3, Wan 3.0 e Seedance 2.5 por fluxo de trabalho em vez de procurar por um vencedor universal. Os links de especificações autoritativas permanecem no cabeçalho da tabela abaixo.

Observação sobre preços: preços iniciais não são uma comparação “maçãs com maçãs” de qualidade ou resolução. Use a tabela específica de resolução na página ao vivo de cada modelo para orçamento.

Qual Video API você deve escolher?

• Escolha o FLUX 3 para movimento realista, som sincronizado, lógica multi-plano, keyframes nativos ou continuação.
• Escolha o Wan 3.0 quando o fluxo começa com muitos tipos de entrada e a janela de 30 segundos importa.
• Escolha o Seedance 2.5 para narrativas mais longas com forte controle de identidade, produto e estilo por referência.

Boas práticas de produção com a API do FLUX 3

Persista jobs assíncronos como estado durável

Salve o task ID imediatamente após o envio. Uma reinicialização do servidor ou nova tentativa do worker não deve forçar o usuário a pagar por outra geração porque o aplicativo perdeu a tarefa original.

Evite polling agressivo

Comece por volta de dez segundos, a menos que a documentação ao vivo recomende o contrário. Consultar a cada segundo aumenta a pressão de requisições sem melhorar materialmente a experiência.

Valide o download

Verifique o tamanho do conteúdo e a assinatura do MP4 antes de marcar um ativo como concluído. Uma resposta HTTP bem-sucedida nem sempre prova que o corpo é um vídeo válido.

Separe os esquemas nativo e de gateway

Mantenha adaptadores separados para requisições nativas da BFL e da CometAPI. Isso evita que campos nativos como mode, keyframes e start_video vazem em uma chamada de gateway que espera model, prompt, seconds e size.

Armazene o contexto completo de falhas

Registre o status HTTP, corpo da resposta, task ID, ID do modelo, versão do prompt, tamanho, duração e ID interno do job. Redija a chave de API.

Use um conjunto pequeno de avaliação antes de lançar

Monte 10–30 prompts representativos cobrindo movimento de câmera, pessoas, produtos, tipografia, diálogo, cenas de alta movimentação e proporções exigidas. Rode o mesmo conjunto quando a versão do modelo ou da integração mudar, e repita prompts importantes porque a geração de vídeo é estocástica.

FAQ

Qual é o ID do modelo FLUX 3 na CometAPI?

O ID atual do modelo é flux-3.

Qual endpoint da CometAPI o FLUX 3 usa?

O fluxo verificado de Video API usa POST /v1/videos, seguido por GET /v1/videos/{task_id} e GET /v1/videos/{task_id}/content.

O FLUX 3 é síncrono?

Não. Trate-o como um job assíncrono: envie, persista o task ID, faça polling e baixe.

Por quanto tempo o FLUX 3 pode gerar?

A BFL documenta 5–20 segundos para T2V/I2V e 5–15 segundos para continuação.

O FLUX 3 gera áudio?

Sim. A BFL documenta áudio sincronizado habilitado por padrão em sua API nativa.

O FLUX 3 suporta imagem-para-vídeo?

Sim. A CometAPI lista suporte a imagem-para-vídeo, enquanto a API nativa da BFL o implementa via modo i2v e keyframes.

Posso usar keyframes da BFL pela CometAPI sem alterações?

Não presuma isso. Os esquemas de requisição diferem; verifique o quickstart atual da CometAPI antes de enviar um fluxo de imagem de referência pelo gateway.

Quanto custa um vídeo de cinco segundos do FLUX 3 na CometAPI?

Aos preços atualmente listados pela CometAPI, cinco segundos custam $0.68 em 720p ou $1.16 em 1080p. Veja a tabela de preços consolidada acima para o link de referência ao vivo.

O FLUX 3 é melhor que o Wan 3.0 ou o Seedance 2.5?

Depende do fluxo. O FLUX 3 é atraente para planos audiovisuais com boa coerência de movimento e controle nativo por keyframe ou continuação; o Wan 3.0 enfatiza amplitude de entrada; o Seedance 2.5 enfatiza narrativas mais longas e controle pesado por referência.

Conclusão

FLUX 3 agora tem um caminho assíncrono de Video API funcional na CometAPI, enquanto a documentação nativa da BFL expõe controles mais profundos para keyframes, continuação, áudio e Modo Draft.

Um caminho de integração seguro é direto: comece com uma requisição curta de texto-para-vídeo em 720p, persista o task ID, faça polling de forma conservadora, baixe e valide o MP4; depois, adicione modelos de prompt, storage, lógica de retry e um conjunto de avaliação repetível. Mantenha os esquemas nativo e do gateway separados e verifique a página do modelo ao vivo antes de fixar campos ou preços no código.