Cómo usar flux-2-klein-4b/image-to-image a través de la API de hiapi

FLUX.2 [klein] 4B es el modelo de edición de imágenes compacto y rápido de Black Forest Labs: proporciónale una imagen de referencia y una instrucción en lenguaje natural, y devolverá una imagen editada de hasta 4 MP. En hiapi, se ejecuta a través de la misma Unified Async API que todos los demás modelos: crea una tarea con POST /v1/tasks y luego sondea o recibe un callback para obtener el resultado. Esta guía cubre la estructura exacta de la solicitud, ejemplos funcionales de curl/Python y cómo integrarlo en producción.

Qué necesitas

• Una clave de API de hiapi. Obtén una desde el dashboard: la clave tiene el formato sk-... y se envía en el encabezado Authorization: Bearer.
• Una URL de imagen de referencia de acceso público (jpeg, png o webp; no se admite svg). Las imágenes de más de 4 MP se reducen automáticamente a 4 MP.
• El precio actual de flux-2-klein-4b/image-to-image se divide en tramos según la resolución (de 0.25 MP a 4 MP); consulta hiapi pricing para obtener el precio en tiempo real y no lo codifiques aquí.

Ejemplo mínimo funcional

El ID del modelo es flux-2-klein-4b/image-to-image: úsalo exactamente así (incluida la barra) como valor de model (no en la ruta de la URL). Todos los modelos de hiapi comparten el mismo endpoint; solo los campos del objeto input varían según el modelo.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Mantén el sujeto y el ángulo de cámara. Reemplaza el fondo por un degradado de estudio azul profundo y añade una iluminación de contorno suave.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

La solicitud devuelve inmediatamente un taskId: la generación es asíncrona:

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Sondea para obtener el resultado:

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Cuando status pase a "success", la imagen editada estará en data.output[0].url. Esa URL es temporal (incluye expireAt), así que descarga o rehostea el archivo de inmediato; no almacenes este enlace directo.

El mismo flujo en Python:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Mantén el sujeto y el ángulo de cámara. Reemplaza el fondo por un degradado "
    "de estudio azul profundo y añade una iluminación de contorno suave.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Parámetros de la solicitud

flux-2-klein-4b/image-to-image acepta un esquema de entrada estricto: los campos adicionales que no se enumeran aquí se rechazan con un 400:

Campo	¿Obligatorio?	Descripción
prompt	Sí	Descripción en lenguaje natural de la edición que se va a aplicar.
image_urls	Sí	Array que contiene exactamente una URL de imagen de referencia. Si se pasan varias, devuelve maxItems: got N, want 1.
resolution	No	Uno de estos valores: 0.25 MP, 0.5 MP, 1 MP (predeterminado), 2 MP, 4 MP. Usa 0.25/0.5 MP para borradores de bajo coste y 2/4 MP para la salida final.
aspect_ratio	No	Uno de estos valores: match_input_image (predeterminado), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	No	Entero que permite obtener resultados reproducibles entre solicitudes idénticas en todo lo demás.
output_format	No	jpg (predeterminado), png o webp.
output_quality	No	Entero, calidad de compresión para jpg/webp (predeterminado 95).

Este modelo no tiene campos size ni n: son convenciones de otros proveedores y este esquema no las reconoce. Cada modelo de hiapi tiene su propio conjunto de campos, así que antes de portar una solicitud creada para otro modelo, consulta la página de referencia del modelo.

Consideraciones para producción

Prefiere callbacks en lugar de sondeo. Añade un objeto callback de nivel superior y hiapi notificará a tu servicio en lugar de obligarte a sondear en un bucle:

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when solo acepta "final": se envía una notificación cuando la tarea alcanza un estado terminal (success o fail), no un flujo de progreso. Trata el callback como una señal de activación: al recibirlo, debes seguir haciendo GET /v1/tasks/<taskId> para leer el estado autoritativo, y haz que el manejador sea idempotente respecto a taskId para protegerse frente a entregas duplicadas.

Idempotencia. Persiste el taskId en cuanto create_task devuelva, antes de empezar a sondear o esperar el callback. Si el proceso se cae mientras espera, al reiniciar debe reanudar con GET /v1/tasks/<taskId> en lugar de volver a crear la tarea: la creación de tareas es un evento facturable, mientras que GET puede repetirse sin coste.

Gestión de errores. Una clave no válida o no autorizada devuelve HTTP 401 con un cuerpo de respuesta estructurado:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Registra el request_id: el equipo de soporte puede localizar la llamada exacta con él. Un input mal formado (falta prompt/image_urls, un valor de aspect_ratio no admitido o campos adicionales no reconocidos) devuelve 400 con error_code: "INVALID_REQUEST" y un mensaje que señala el campo problemático; corrige el cuerpo de la solicitud en lugar de reintentar tal cual.

Lecturas relacionadas

• Referencia del modelo de imagen a imagen FLUX.2 [klein] 4B: documentación completa de parámetros y cuerpos de solicitud de ejemplo.
• Referencia del modelo de texto a imagen FLUX.2 [klein] 4B: la variante de texto a imagen correspondiente, que no necesita imagen de referencia.
• hiapi pricing: coste actual por imagen según el tramo de resolución.
• Unified Async API 概览: el contrato POST /v1/tasks / GET /v1/tasks/:id que comparten todos los modelos de la plataforma.

Preguntas frecuentes

¿Qué formatos de imagen acepta image_urls? jpeg, png o webp. No se admite svg. Las imágenes de más de 4 MP se reducen automáticamente a 4 MP antes de la edición.

¿Puedo pasar varias imágenes de referencia? No: image_urls en este modelo admite exactamente un elemento. Si se pasan más, devuelve 400 (maxItems: got N, want 1).

¿Por qué se rechaza mi solicitud con "additional properties ... not allowed"? El esquema es estricto: cualquier campo que no esté en la tabla de parámetros anterior (por ejemplo, convenciones de otros proveedores como size, n o strength) provoca un 400. Consulta la referencia del modelo para conocer el conjunto exacto de campos aceptados.

¿Cómo mantengo la relación de aspecto de la imagen original? Establece aspect_ratio en match_input_image, que también es el valor predeterminado si omites el campo por completo.

¿Cuál es la diferencia entre flux-2-klein-4b/image-to-image y la variante 9B? Ambos comparten el mismo esquema de solicitud (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). La ruta 9B sacrifica algo de velocidad y coste a cambio de un mayor realismo, mejor renderizado de texto y más detalle: usa 4B cuando iteres rápido y a bajo coste, y 9B cuando la edición deba resistir el escrutinio en detalles finos.

¿Necesito una URL de callback o basta con el sondeo? El sondeo con GET /v1/tasks/:id está bien para desarrollo local, tareas de bajo volumen o como respaldo cuando se pierde la entrega de un callback. Para tráfico de producción, los callbacks evitan la sobrecarga de un bucle de sondeo por cada solicitud.