Black Forest Labs

FLUX.1 Kontext Max

flux-1-kontext-max

A versão de edição de imagem carro-chefe da série Kontext, especializada em modificações locais por instruções em linguagem natural, com melhor aderência a prompts e tipografia de texto na imagem, ideal para produção em lote de visuais de marca e storyboards

flux-1-kontext-max

Experimentar flux-1-kontext-max

Entrada

Saída

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

Preços

flux-1-kontext-max per image

Preço unitário	$0.0715

Visão geral

FLUX.1 Kontext Max é um modelo de geração e edição de imagens lançado pela Black Forest Labs, acessível por meio da interface unificada do HiAPI.ai. Ele suporta geração de imagem a partir de texto e edição de imagem única: ao fornecer uma imagem original, ele altera o conteúdo indicado pelo prompt e preserva o restante; ao omitir a imagem original, ele gera uma nova imagem a partir do prompt. Em comparação com as versões inferiores da série, ele é mais forte em aderência ao prompt e na tipografia de textos dentro da imagem, sendo adequado para desenvolvedores e equipes de produção de conteúdo que precisam de controle preciso do escopo de edição e de consistência visual.

Destaques principais

Edição local preserva as áreas não especificadas — basta descrever no prompt a cor, o objeto, o fundo ou o estilo a alterar, e o restante do conteúdo da imagem é mantido o máximo possível como está.
Maior aderência ao prompt e melhor tipografia da série — como versão mais avançada da série Kontext, executa intenções complexas de edição com mais precisão e apresenta textos na imagem de forma mais limpa e precisa.
Geração a partir de texto e de imagem compartilham os mesmos parâmetros — na mesma interface, basta alternar se uma imagem original é enviada para escolher entre geração totalmente nova e edição a partir da imagem original.
Proporção e rigor de moderação ajustáveis — suporta seis proporções de saída, formatos jpeg/png e níveis de tolerância de moderação de conteúdo de 0 a 2.

Descrição das capacidades

Edição local por linguagem natural: ao enviar uma única imagem original e um prompt, o modelo altera apenas as partes descritas; as áreas não mencionadas permanecem inalteradas, ideal para iterar rapidamente sobre materiais existentes.

Geração a partir de texto: sem enviar imagem original, gera uma imagem totalmente nova conforme o prompt, permitindo usar a mesma interface para encadear a criação do zero e edições posteriores.

Tratamento de texto dentro da imagem: melhor desempenho de tipografia da série, adequado para gerar ou modificar textos na imagem mantendo legibilidade e organização.

Controle de proporção e formato: na edição, deixar a proporção em branco mantém a da imagem original; ao especificá-la, a imagem é recortada ou preenchida conforme a proporção desejada; a saída pode ser jpeg ou png, facilitando a integração direta com fluxos posteriores.

Interruptor de reescrita de prompt: pode-se ativar o upsampling de prompt para acrescentar detalhes e criatividade, ou desativá-lo para garantir geração estritamente conforme o texto original.

Cenários de aplicação

Equipes de marketing alteram materiais de marca existentes — inserir um pôster ou banner finalizado e indicar cores, objetos ou fundos a substituir, obtendo variações prontas para veiculação.
Designers ajustam textos dentro da imagem — substituir textos e tipografia em peças visuais existentes conforme o prompt, gerando imagens finais para anúncios ou redes sociais.
Produção de storyboards e conteúdo multicena — editar imagem por imagem a partir de uma base de mesmo estilo, obtendo uma série de cenas com continuidade de enquadramento e estilo unificado para storyboards.
Substituição local em fotos de produto — enviar fotos de produto e indicar a troca de fundo ou de cores, gerando imagens finais para páginas de detalhes e vitrines de e-commerce.

Limitações e recomendações de escolha

Suporta apenas uma imagem original por vez, não sendo possível manter consistência de personagem por meio de múltiplas referências; seu foco é edição de imagens e modificação de áreas específicas, e a geração puramente a partir de texto não é seu principal ponto forte. Como modelo proprietário hospedado, não pode ser implantado localmente e não é adequado para cenários que exigem controle próprio do ambiente de inferência. A cobrança é por imagem, e o custo deve ser avaliado em edições frequentes em grande volume; se forem necessárias apenas edições cotidianas simples, como ajustes de cor ou fundo, versões inferiores da mesma série podem ser consideradas para controlar despesas.

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-1-kontext-max

routestringOpcional

Valor fixo atual: default

inputobjectObrigatório

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

promptstringObrigatóriominLength 1maxLength 4000

描述要生成的图片；使用原图时，描述需要修改和需要保留的内容。可用中文或英文，非英文提示词会先自动转成英文再生成。

input_imagestringOpcional

可选的原图地址，只支持单张。提供后在该图基础上按提示词编辑；省略时按提示词生成全新图片。

aspect_ratiostringOpcional

输出宽高比。编辑时留空沿用原图比例（实际像素按 32 的倍数微调），指定后按该比例裁切或补边；文生图留空时由模型选择画幅。

Opções:21:916:94:31:13:49:16

output_formatstringOpcionalPadrão: "jpeg"

输出文件格式：jpeg 或 png。

Opções:jpegpng

safety_toleranceintegerOpcionalPadrão: 2

内容审核严格程度：0 最严格，2 最宽松；文生图与编辑两种模式统一提供 0–2。

Opções:012

prompt_upsamplingbooleanOpcionalPadrão: false

开启后自动改写提示词以增加细节与创意，耗时略长；需要严格按原文生成时关闭。

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-1-kontext-max",
  "input": {
    "prompt": "…",
    "output_format": "jpeg",
    "safety_tolerance": 2,
    "prompt_upsampling": false
  }
}'

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-1-kontext-max",
    input: {
      "prompt": "…",
      "output_format": "jpeg",
      "safety_tolerance": 2,
      "prompt_upsampling": false
    }
  }),
});
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-1-kontext-max",
        "input": {
          "prompt": "…",
          "output_format": "jpeg",
          "safety_tolerance": 2,
          "prompt_upsampling": False
        }
    },
)
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"
    }
  }
}