Black Forest Labs

FLUX.1 Kontext Max

flux-1-kontext-max

La versión insignia de edición de imágenes de la serie Kontext, especializada en realizar modificaciones locales siguiendo instrucciones en lenguaje natural, con un mejor seguimiento de las indicaciones y una composición tipográfica del texto en la imagen más sólida, ideal para la producción por lotes de visuales de marca y storyboards

flux-1-kontext-max

Probar flux-1-kontext-max

Entrada

Salida

Rellena los parámetros y genera: los resultados aparecerán aquí.

Precios

flux-1-kontext-max per image

Precio unitario	$0.0715

Descripción general

FLUX.1 Kontext Max es un modelo de generación y edición de imágenes presentado por Black Forest Labs, que se invoca a través de la interfaz unificada de HiAPI.ai. Admite generación de imágenes a partir de texto y edición de una sola imagen: cuando se proporciona la imagen original, modifica el contenido especificado según el prompt y conserva el resto; si se omite la imagen original, genera una nueva imagen según el prompt. En comparación con las versiones inferiores de la misma serie, es más potente en el seguimiento de prompts y en la composición tipográfica del texto dentro de la imagen, lo que lo hace adecuado para desarrolladores y equipos de producción de contenido que necesitan un control preciso del alcance de la edición y mantener la coherencia visual.

Puntos clave

Edición local que conserva las áreas no especificadas: basta con indicar en el prompt el color, el objeto, el fondo o el estilo que se desea cambiar, y el resto del contenido de la imagen se mantiene lo más fiel posible al original.
El mayor seguimiento de prompts y la mejor composición tipográfica de la serie: como la versión de gama más alta de la serie Kontext, la ejecución de intenciones de edición complejas y la presentación del texto dentro de la imagen son más precisas y limpias.
Texto a imagen e imagen a imagen comparten un mismo conjunto de parámetros: con la misma interfaz, basta con decidir si se envía la imagen original para elegir entre una generación completamente nueva y una edición basada en la imagen original.
Relación de aspecto e intensidad de moderación ajustables: admite seis relaciones de salida, formatos jpeg/png y un nivel de permisividad de moderación de contenido de 0 a 2.

Descripción de capacidades

Edición local con lenguaje natural: al enviar una sola imagen original y un prompt, el modelo solo modifica las partes descritas y las áreas no mencionadas permanecen sin cambios, lo que resulta adecuado para iterar rápidamente sobre material existente.

Generación de texto a imagen: cuando no se envía la imagen original, se genera una imagen completamente nueva según el prompt, y la misma interfaz permite encadenar la generación desde cero y la edición posterior.

Tratamiento del texto dentro de la imagen: el mejor rendimiento de composición tipográfica de la serie, ideal para generar o modificar textos en imágenes manteniendo la legibilidad y la limpieza.

Control de proporción y formato: al editar, si se deja vacía la proporción se conserva la de la imagen original; si se especifica, se recorta o se rellena según la proporción objetivo; la salida puede ser jpeg o png, lo que facilita la integración directa con los flujos posteriores.

Interruptor de reescritura de prompts: se puede activar el sobremuestreo del prompt para añadir detalle y creatividad, o desactivarlo para garantizar una generación estrictamente fiel al texto original.

Casos de uso

Equipos de marketing que modifican material de marca existente: introducir un póster o banner terminado e indicar el color, el objeto o el fondo que se debe sustituir para obtener una variante lista para publicar.
Diseñadores que ajustan el texto dentro de la imagen: sustituir textos y composición tipográfica según el prompt sobre un borrador visual existente y producir imágenes finales para espacios publicitarios o redes sociales.
Producción de storyboards y contenido multiescena: editar imagen por imagen partiendo de una misma imagen base de estilo para obtener una serie de escenas con continuidad de plano y estilo unificado para el storyboard.
Sustitución local en fotos de producto: subir una foto de producto y especificar el cambio de fondo o de combinación de colores para producir las imágenes finales que necesitan las páginas de detalle de e-commerce y las páginas de exhibición.

Limitaciones y recomendaciones de selección

Solo admite la entrada de una única imagen original y no puede mantener la consistencia de personajes mediante referencias de múltiples imágenes; su enfoque principal es la edición de imágenes y la modificación de áreas especificadas, y la generación puramente a partir de texto no es su ventaja principal. Como modelo alojado de código cerrado, no se puede desplegar localmente y no es adecuado para escenarios que requieren controlar el propio entorno de inferencia. Se factura por imagen, por lo que el coste debe tenerse en cuenta en ediciones masivas de alta frecuencia; si solo se necesitan ajustes sencillos de color o fondo, se pueden considerar versiones inferiores de la misma serie para controlar el gasto.

Crear una tarea de generación

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

Encabezados

AuthorizationstringObligatorio

Clave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API

Content-TypestringOpcional

El cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.

Idempotency-KeystringOpcional

Clave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.

Clave de idempotencia

Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.

Cuerpo

modelstringObligatorio

Valor fijo actual: flux-1-kontext-max

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para flux-1-kontext-max y la ruta default; consulta la tabla de parámetros a continuación.

promptstringObligatoriominLength 1maxLength 4000

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

input_imagestringOpcional

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

aspect_ratiostringOpcional

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

Opciones:21:916:94:31:13:49:16

output_formatstringOpcionalPredeterminado: "jpeg"

输出文件格式：jpeg 或 png。

Opciones:jpegpng

safety_toleranceintegerOpcionalPredeterminado: 2

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

Opciones:012

prompt_upsamplingbooleanOpcionalPredeterminado: false

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

callbackobjectOpcional

Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.

Callbacks (Webhook)

Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.

urlstringObligatorio

Obligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.

whenstringOpcionalPredeterminado: "final"

Actualmente solo se admite final: notifica tanto en success como en fail.

Opciones:final

storagestringOpcionalPredeterminado: "temp"

Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.

Opciones:temppersistent

Ejemplos de solicitud

# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
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"
}

Obtener el detalle de la tarea

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

Campos de respuesta

taskIdstringObligatorio

ID de tarea, siempre con prefijo tk-hiapi-.

modelstringObligatorio

Nombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.

routestringOpcional

Solo aparece si se usó el parámetro route explícito; repite el valor enviado.

statusstringObligatorio

Estado de la tarea.

Valores de estado

queued En cola, sin iniciar. handling Procesando. archiving Proceso terminado, preparando artefactos. success Terminal: completado, artefactos disponibles (se devuelve output). fail Terminal: error (se devuelve error). Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.

creatednumberObligatorio

Hora de creación de la tarea (segundos Unix).

completednumberObligatorio

Segundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.

outputarrayOpcional

Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).

Array [ object ]

Elementos del array

urlstringObligatorio

URL del artefacto, descargable directamente.

typestringObligatorio

Valores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.

expireAtnumberObligatorio

Segundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.

errorobjectOpcional

Solo con status == fail.

codestringObligatorio

Código de error de negocio.

messagestringObligatorio

Descripción del error.

Ejemplos de respuesta

Éxito

{
  "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
      }
    ]
  }
}

En proceso (no terminal)

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

Fallido

{
  "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"
    }
  }
}