Black Forest Labs

FLUX 3 Image

flux-3-image

Modelo de imagem da família multimodal da Black Forest Labs, que compartilha a arquitetura de treinamento conjunto e o framework Self-Flow com vídeo e áudio, ideal para atualizar pipelines de geração de imagens baseados no sistema FLUX

flux-3-image

Experimentar flux-3-image

Entrada

Criações

Ver todas as criações

Saída

image

Preencha os parâmetros e gere — os resultados aparecerão aqui.

Preços

flux-3-image per image

Especificações	Preço unitário
768S	$0.041
1K	$0.048
1.5K	$0.070
2K	$0.100
4K	$0.607

Visão geral

flux-3-image é o modelo de imagem da família multimodal FLUX 3 da Black Forest Labs, acessível por meio da interface unificada do HiAPI.ai. Ele aceita tanto prompts de texto puro para gerar imagens diretamente quanto até 10 imagens de referência para participarem da geração e de modificações locais, com formato de saída, níveis de resolução e tolerância à segurança de conteúdo ajustáveis. É indicado para desenvolvedores que estão construindo pipelines de geração de conteúdo visual e para equipes que precisam integrar a nova geração de modelos aos fluxos de trabalho de imagem FLUX existentes.

Destaques principais

Controle combinado de imagens de referência e prompt — é possível enviar até 10 imagens de referência e especificar no prompt, imagem por imagem, o papel de cada uma como sujeito, estilo ou composição.
Busca na web opcional para complementar informações visuais — o grounding vem habilitado por padrão e, antes da geração, consulta páginas web e imagens para complementar entidades e detalhes de cena do prompt.
Resolução e formato com opções detalhadas — a saída cobre cinco níveis de pixels, de 768 a 4K, e 16 proporções de imagem; o modo auto pode definir o formato automaticamente com base no prompt e nas imagens de referência.

Descrição das capacidades

Geração de imagem a partir de texto e geração guiada por imagens de referência: uma única requisição gera uma imagem a partir do prompt; ao fornecer imagens de referência, basta indicar no prompt o que deve ser modificado e o que deve ser preservado para concluir o ajuste direcionado, sem etapas separadas.

Combinação de múltiplas imagens de referência: é possível usar até 10 imagens de referência por requisição, cada uma desempenhando o papel de sujeito, estilo ou composição, o que é adequado para reunir diversos materiais visuais em uma mesma cena.

Controle de formato e resolução: aspect_ratio oferece 16 proporções, de imagens horizontais 21:9 a verticais 9:21, com seleção automática, e resolution cobre de 768 a 4K, facilitando a geração em lote conforme o canal de veiculação e os requisitos de nitidez.

Ajuste da tolerância à segurança de conteúdo: safety_tolerance é ajustável de 0 a 4, com padrão 2, permitindo que as equipes restrinjam ou afrouxem a intensidade do filtro conforme suas exigências de conformidade.

Cenários de aplicação

Geração de imagens estilizadas por equipes de design criativo — inserir a descrição do design e imagens de referência de estilo para produzir peças visuais com composição e formato especificados, usadas em materiais publicitários e propostas conceituais.
Atualização de modelos em pipelines FLUX existentes — substituir a chamada atual de geração de imagem por prompts de texto, mantendo o formato da interface de saída, o que facilita atualizar o modelo sem alterar os fluxos superiores.
Produção de imagens de cena que exigem detalhes factuais — com o grounding habilitado, descrever o sujeito com um prompt curto e obter uma imagem complementada com informações de busca, usada para ilustrar conteúdos e representar cenários.
Composição de múltiplos materiais e retoque de imagens — enviar várias imagens de referência e indicar o papel de cada uma para obter resultados compostos ou modificados em estilo unificado, usados em imagens de e-commerce e reutilização de materiais.

Limitações e recomendações de escolha

As informações públicas concentram-se na família FLUX 3 como um todo e na vertente de vídeo, com divulgação limitada de especificações específicas desta versão de imagem; as descrições de treinamento conjunto e capacidades de vídeo no nível da família não equivalem diretamente a todas as capacidades deste modelo. O grounding realiza a busca antes da geração, o que pode aumentar o tempo de cada requisição. Para desempenho em velocidade de geração, estabilidade e prompts extremamente difíceis, recomenda-se validar primeiro com amostras próprias antes de adotar em produção. Se a necessidade for geração de vídeo ou áudio, deve-se escolher o modelo da vertente correspondente dentro da mesma família.

Perguntas frequentes

Ver todas as perguntas →

É possível gerar e editar em um único ponto de entrada?

Sim. Sem imagem de referência, gere a partir de texto; com 1 a 10 imagens de referência, edite com base no material existente. Basta preparar o texto ou as imagens de acordo com o objetivo de criação.
Como escolher entre os cinco níveis de resolução?

Comece com 768 ou 1K para discutir a direção; considere 1.5K ou 2K quando precisar de mais detalhes e 4K quando precisar de imagens maiores e espaço para recorte. Os níveis não são dimensões fixas; verifique a largura e a altura da imagem retornada.
Como as imagens de referência distribuem seus papéis?

Explique, em ordem, qual imagem fornece o sujeito, qual fornece o ambiente e qual fornece apenas o esquema de cores ou o estilo, indicando também quais elementos não devem ser trazidos.
Quantas imagens são geradas por vez?

Cada tarefa retorna uma imagem. Quando precisar de outra direção, ajuste a descrição e envie uma tarefa separada.

Criar uma tarefa de geração

POST https://api.hiapi.ai/v1/tasks

Cabeçalhos

AuthorizationstringObrigatório

Chave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API

Content-TypestringOpcional

O corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.

Idempotency-KeystringOpcional

Chave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.

Chave de idempotência

Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.

Corpo

modelstringObrigatório

Valor fixo atual: flux-3-image

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

Objeto de parâmetros de negócio para flux-3-image e a rota default — veja a tabela de parâmetros abaixo.

promptstringObrigatóriominLength 1maxLength 5000

Descreva o conteúdo da imagem que deseja gerar; quando uma imagem de referência for fornecida, você também pode especificar aqui as partes da imagem que precisam ser modificadas e as que devem ser preservadas.

groundingbooleanOpcionalPadrão: true

Valor booleano que controla se, antes da geração, deve-se pesquisar na web e em imagens para complementar as informações visuais do prompt; o padrão é true.

image_urlsarrayOpcionalminItems 1maxItems 10

Array de URLs de imagens de referência, usado para fornecer referência visual à geração; o papel de cada imagem (sujeito, estilo ou composição) deve ser descrito no prompt.

Array [ string ]

resolutionstringOpcionalPadrão: "1K"

Nível de resolução de saída; a largura e a altura específicas variam conforme a proporção da imagem; o padrão é 1K.

Opções:7681K1.5K2K4K

aspect_ratiostringOpcionalPadrão: "auto"

Proporção da imagem de saída, podendo ser horizontal, vertical ou quadrada; auto indica que a proporção é determinada automaticamente com base no prompt e nas imagens de referência; o padrão é auto.

Opções:21:92:116:93:27:54:35:41:1

Mostrar tudo (8)

4:53:45:72:39:161:29:21auto

safety_toleranceintegerOpcionalPadrão: 2min 0max 4

Número inteiro que indica a tolerância de segurança de conteúdo; o valor 0 é o mais rigoroso; o padrão é 2.

callbackobjectOpcional

Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.

Callbacks (Webhook)

Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.

urlstringObrigatório

Obrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.

whenstringOpcionalPadrão: "final"

Atualmente só há suporte a final — notifica tanto em success quanto em fail.

Opções:final

storagestringOpcionalPadrão: "temp"

Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.

Opções:temppersistent

Exemplos de requisição

# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geraçã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-image",
  "input": {
    "prompt": "…",
    "grounding": true,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "safety_tolerance": 2
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "flux-3-image",
    input: {
      "prompt": "…",
      "grounding": true,
      "resolution": "1K",
      "aspect_ratio": "auto",
      "safety_tolerance": 2
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "flux-3-image",
        "input": {
          "prompt": "…",
          "grounding": True,
          "resolution": "1K",
          "aspect_ratio": "auto",
          "safety_tolerance": 2
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obter detalhes da tarefa

GET https://api.hiapi.ai/v1/tasks/:id

Campos da resposta

taskIdstringObrigatório

ID da tarefa, sempre com prefixo tk-hiapi-.

modelstringObrigatório

Nome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.

routestringOpcional

Presente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.

statusstringObrigatório

Estado da tarefa.

Valores de status

queued Na fila, ainda não iniciada. handling Em processamento. archiving Processamento concluído, preparando artefatos. success Terminal: concluído, artefatos disponíveis (retorna output). fail Terminal: falha (retorna error). Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.

creatednumberObrigatório

Momento de criação da tarefa (segundos Unix).

completednumberObrigatório

Segundos Unix do estado terminal; 0 enquanto não terminal.

outputarrayOpcional

Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).

Array [ object ]

Itens do array

urlstringObrigatório

URL do artefato, baixável diretamente.

typestringObrigatório

Valores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.

expireAtnumberObrigatório

Segundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.

errorobjectOpcional

Presente apenas com status == fail.

codestringObrigatório

Código de erro de negócio.

messagestringObrigatório

Descrição do erro.

Exemplos de resposta

Sucesso

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Em processamento (não final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Falhou

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}