¿Cómo usar la API de FLUX.1 Kontext Max? Genera tu primera imagen en 5 minutos

TL;DR

• Qué es: FLUX.1 Kontext Max, creado por Black Forest Labs; la generación de texto a imagen y la edición de una sola imagen comparten el mismo ID de modelo. Ya está disponible en HiAPI: abre la página del modelo e introduce un prompt para generar; los nuevos usuarios reciben 200 créditos al registrarse, equivalentes a unas 1.4 imágenes.
• Cuánto cuesta: $0.0715 por imagen (143 créditos), el mismo precio para generación y edición; con $10 se generan unas 139 imágenes. Las tareas fallidas reembolsan el cargo retenido.
• Cómo llamar a la API: POST https://api.hiapi.ai/v1/tasks con model establecido en flux-1-kontext-max; tras obtener el taskId, consulta periódicamente o espera el callback y descarga el resultado desde data.output[0].url.

Desde el lanzamiento de FLUX.1 Kontext Max, hay dos preguntas frecuentes: si al editar una imagen se puede modificar solo una parte, y cuánto se tarda en integrarlo en un producto propio. Primero revisemos sus capacidades y luego dos rutas para empezar.

Qué es FLUX.1 Kontext Max y qué tiene de nuevo

• Un solo ID de modelo gestiona dos tipos de tarea. Si no se envía una imagen en input, es texto a imagen; si se envía input_image, es edición, sin necesidad de mantener dos conjuntos de código.
• La edición sigue la lógica de «qué cambiar y qué conservar». Permite modificar materiales y estilo, añadir o eliminar elementos, ajustar color e iluminación y cambiar texto en la imagen; lo que no se menciona en el prompt se mantiene igual en la medida de lo posible.
• Seis relaciones de aspecto, y al editar se puede conservar la proporción de la imagen original. aspect_ratio admite 21:9, 16:9, 4:3, 1:1, 3:4 y 9:16; si se deja vacío al editar, la salida mantiene la proporción original y los píxeles se ajustan a múltiplos de 32: 1280×720 pasa a 1328×752.
• Salida en jpeg o png, de aproximadamente 1 millón de píxeles por imagen. El límite de prompt es de 4.000 caracteres; los prompts en chino se traducen automáticamente al inglés antes de generar.

Texto a imagen, 16:9. El prompt completo es el mismo que aparece en el curl de abajo y se puede copiar tal cual.

Generar con este prompt →

Dos rutas para empezar: prueba en línea o API

Para ver resultados, usa la prueba en línea; para integrarlo en un producto, usa la API. Ambas rutas emplean el mismo modelo y la misma estructura de precios.

Prueba en línea (unos 1 minuto)

1. Abre la página del modelo FLUX.1 Kontext Max o haz clic en el enlace bajo la imagen anterior; el prompt se rellenará automáticamente.
2. Regístrate o inicia sesión; las cuentas nuevas incluyen 200 créditos.
3. Selecciona 16:9 y pulsa generar.
4. Si te gusta el resultado, descárgalo; para editar una imagen, sube la original en la misma página y escribe el prompt de edición.

Integración por API (unos 5 minutos)

1. Crea una API Key (sk-...) en la consola de HiAPI.
2. Haz POST /v1/tasks para crear la tarea y obtén data.taskId de la respuesta.
3. Consulta con GET /v1/tasks/{taskId} o espera la notificación de callback.url; cuando data.status pase a success, descarga la imagen desde data.output[0].url.

Cada imagen cuesta $0.0715; con $10 se generan unas 139 imágenes, suficientes para ajustar el prompt hasta quedar satisfecho. Consulta todos los parámetros en la documentación en chino.

Primera imagen: versión curl

Crear la tarea:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

El ID de tarea devuelto está en data.taskId:

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

Consultar el resultado:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Solo prompt es obligatorio. output_format es jpeg por defecto, prompt_upsampling está desactivado por defecto y safety_tolerance es 2 por defecto (0 es el más estricto).

Primera imagen: versión Python

Creación, consulta periódica y descarga en un solo bloque; solo tienes que poner tu propia Key para ejecutarlo:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

Modo edición: basta con añadir input_image

Al añadir input_image dentro de input, la misma solicitud pasa de texto a imagen a edición. A continuación se toma la imagen del rincón de lectura anterior como original y solo se cambia el sillón y se añade una lámpara de pie:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image acepta una URL de imagen accesible públicamente. Al editar, si no se indica aspect_ratio, la salida conserva la proporción de la imagen original; para fusionar varias imágenes, elige la edición de imágenes de GPT Image 2, que admite de 1 a 16 imágenes de referencia.

Cómo escribir el prompt de edición: primero di qué cambiar y luego enumera qué conservar

1. Escribe el cambio como una instrucción clara. Sé concreto con el objeto y su nuevo estado: cambiar linen armchair por deep forest-green velvet armchair.
2. Nombra uno por uno los elementos que se conservan. Ventana, libros, taza, mesa y luz de la tarde: menciona lo que te importa de la imagen original y cierra con keep ... unchanged.
3. Los cambios relacionados pueden ir en una misma frase. Cambiar el sillón y añadir una lámpara de pie de latón a la vez; el modelo lo procesará en conjunto. Las modificaciones no relacionadas es mejor enviarlas por separado para verificar mejor el resultado.
4. Al cambiar texto en la imagen, conserva también la maquetación. Por ejemplo, cambiar KYOTO por OSAKA en un póster e indicar al mismo tiempo que la disposición, los espacios en blanco y el estilo tipográfico se mantienen igual.
5. Puedes escribir directamente en chino. El sistema lo traduce primero al inglés y luego genera; mantén el prompt dentro de los 4.000 caracteres.

4 cosas a tener en cuenta antes de publicar

1. Usa callbacks en el servidor. Añade "callback": {"url": "https://yourapp.com/webhook", "when": "final"} en el cuerpo de la solicitud para recibir una notificación automática cuando la tarea llegue a su estado final y evitar la consulta periódica.
2. No repitas el POST por tiempo de espera agotado. Cada creación genera una nueva tarea y se cobra por separado; guarda primero el taskId y deduplica en tu propio sistema antes de reintentar.
3. Los enlaces de los resultados caducan. data.output[0].url es un enlace temporal; descárgalo en cuanto lo obtengas y guárdalo en tu propio almacenamiento.
4. Los píxeles se alinean a múltiplos de 32. Al editar, deja aspect_ratio vacío: la proporción original se mantiene y los píxeles se ajustan a múltiplos de 32; 1280×720 da como salida 1328×752. Si especificas una proporción, se recorta o se rellena según esa proporción.

Preguntas frecuentes

¿Hay que cambiar de modelo entre texto a imagen y edición? No. Es el mismo flux-1-kontext-max; enviar o no input_image determina qué ruta se usa, y el precio es el mismo.

¿Cuántas imágenes de referencia se pueden enviar a la vez? Una. Para fusionar varias imágenes, elige la edición de imágenes de GPT Image 2, que admite de 1 a 16 imágenes de referencia.

¿Se pueden usar prompts en chino? Sí. El límite del prompt es de 4.000 caracteres y el chino se traduce automáticamente al inglés antes de generar.

¿Cambia el formato de imagen tras editar? Si no indicas aspect_ratio, se conserva la proporción original y los píxeles se ajustan a múltiplos de 32; si lo indicas, se recorta o se rellena según la proporción especificada.

¿Se cobra si la tarea falla? Se cobra según el número de imágenes generadas con éxito; cada solicitud devuelve 1 imagen y las tareas fallidas reembolsan el cargo retenido.

Copia el prompt del rincón de lectura anterior en la página del modelo FLUX.1 Kontext Max, selecciona 16:9 y pulsa generar una vez; primero observa cómo maneja la luz y los materiales y luego decide si conviene integrarlo en tu proyecto.