Cómo usar gpt-image-2.5-flare a través de la API de hiapi

gpt-image-2.5-flare es un único modelo en hiapi que maneja tanto la generación de imágenes a partir de texto como la edición de imágenes a través del mismo endpoint unificado: no necesitas usar dos ID de modelo separados para "generar" y "editar". Esta guía te llevará desde cero hasta generar imágenes utilizables en pocos minutos usando la API de tareas asíncronas de hiapi, con un ejemplo completo en Node.js y los patrones de nivel de producción (callbacks, idempotencia, reintentos) que necesitarás antes de salir a producción.

Lo que necesitas preparar

• Una clave de API de hiapi. Regístrate y obtén una desde la consola: la clave tiene la forma sk-... y se coloca en el encabezado Authorization: Bearer.
• Cualquier cliente HTTP. Los ejemplos siguientes usan Node.js 18+ (fetch integrado), pero las mismas tres llamadas también se pueden realizar con curl, Python o cualquier herramienta capaz de enviar solicitudes POST con JSON.

hiapi expone gpt-image-2.5-flare a través de la misma familia de endpoints asíncronos: envías una tarea y luego consultas el resultado periódicamente, o recibes un callback webhook cuando la tarea se completa. No existe una llamada síncrona de "esperar la imagen en el cuerpo de la respuesta": la generación tarda varios segundos, por lo que la API está basada en tareas desde el principio.

Ejemplo mínimo funcional (Node.js)

El siguiente código crea una tarea, consulta su estado hasta que se completa e imprime la URL de la imagen generada.

const API_KEY = process.env.HIAPI_API_KEY; // sk-...
const BASE = "https://api.hiapi.ai/v1/tasks";

async function createTask(prompt) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      input: {
        prompt,
        aspect_ratio: "16:9",
        quality: "high",
      },
    }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`create task failed (${res.status}): ${JSON.stringify(err)}`);
  }
  const { data } = await res.json();
  return data.taskId; // e.g. "tk-hiapi-..."
}

async function waitForTask(taskId, { timeoutMs = 120_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/${taskId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    const { data: task } = await res.json();
    if (task.status === "success") return task;
    if (task.status === "fail") {
      throw new Error(`task failed: ${task.error?.code} ${task.error?.message}`);
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

const taskId = await createTask("a minimalist poster of a lighthouse at dawn, flat color");
const task = await waitForTask(taskId);
console.log(task.output[0].url); // download this — it expires, so save it promptly

Ejecútalo con HIAPI_API_KEY=sk-... node generate.js. El arreglo data.output de la respuesta solo aparece cuando status es "success"; cada entrada tiene una url temporal (con expireAt), así que descárgala o vuelve a subirla de inmediato en lugar de guardar el enlace.

Si quieres editar una imagen existente en lugar de generar desde cero, agrega input.image_urls (un arreglo de URL de acceso público, de 1 a 16 imágenes) y describe en el prompt el tratamiento de cada imagen: el mismo modelo, el mismo endpoint, sin necesidad de un ID de modelo de "edición" separado:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: {
    prompt: "replace the background with a studio gradient, keep the subject unchanged",
    image_urls: ["https://example.com/product-photo.jpg"],
  },
}),

Otros campos útiles de input: background (auto / transparent / opaque, por defecto auto) y output_format (png / jpeg / webp, por defecto webp). Este modelo no tiene un campo resolution: el tamaño se controla completamente a través de aspect_ratio (si necesitas dimensiones exactas en píxeles en lugar de una proporción, también acepta dimensiones explícitas en píxeles como 1536x1024).

Patrones de nivel de producción

Usa callbacks en lugar de polling en producción. El polling es útil para scripts, pero para un backend real registra un webhook para que hiapi te notifique en el momento en que la tarea se completa, en lugar de que consultes repetidamente GET /v1/tasks/<id> a intervalos regulares:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: { prompt: "..." },
  callback: {
    url: "https://yourapp.com/webhooks/hiapi",
    when: "final", // the only supported value — fires once, on success or fail
  },
}),

Tu manejador de webhook recibe el mismo objeto de tarea que devuelve el polling de GET /v1/tasks/<id>: revisa status y ramifica según success o fail.

Haz que los reintentos sean idempotentes. Si tu ejecutor de tareas reintenta llamadas HTTP fallidas (tiempos de espera, 5xx, fluctuaciones de red) sin cuidado, podría enviar accidentalmente la misma tarea de generación dos veces y pagar por ambas. Pasa un encabezado Idempotency-Key estable (máximo 255 bytes, normalmente tu propio ID de tarea/solicitud): las solicitudes de reintento con la misma clave devuelven la tarea original en lugar de crear una nueva:

headers: {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": jobId, // reuse the same value across retries of the same logical request
},

Maneja los modos de fallo específicos. Los siguientes códigos de estado deben ramificarse explícitamente en lugar de tratarse todos como "reintentar":

Código de estado	Significado	Manejo
401 y error.code: "permission_denied"	Clave de API incorrecta o ausente	No reintentar: revisa el encabezado Authorization
402	Saldo insuficiente	No reintentar: recarga primero
400	Cuerpo de solicitud inválido (campo incorrecto, tipo incorrecto)	No reintentar a ciegas: corrige el cuerpo de la solicitud
503	Temporalmente no disponible	Es seguro reintentar con retroceso
Tarea con status: "fail"	La tarea falló después de ser aceptada (por ejemplo, image_urls inaccesibles)	Revisa error.code / error.message, no hagas un bucle infinito

El cuerpo de una respuesta de error 401 es el siguiente; todos los modelos de hiapi tienen la misma forma, por lo que vale la pena revisarlo una vez en un manejador de errores compartido:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Referencia

• Página del modelo gpt-image-2.5-flare: precios en tiempo real y un playground para probar prompts en línea, ideal para probar antes de integrar el código.
• Documentación de la API de tareas asíncronas: crear tarea y obtener estado de la tarea: referencia completa de campos para todos los modelos (no solo este).
• Documentación de autenticación: cómo funcionan las claves de API y el encabezado Authorization en todos los endpoints de hiapi.
• ¿Necesitas migrar código existente desde gpt-image-2 o quieres un tutorial de edición específico de Sunburst? Consulta la Guía de la API de GPT Image 2.5 para conocer la ruta de migración.
• Precios: costo actual por imagen según el nivel de calidad (no se copia aquí porque cambia).

Preguntas frecuentes

¿gpt-image-2.5-flare es un modelo o dos (generación + edición)? Uno. Si genera o edita depende completamente de si incluyes input.image_urls: no es necesario cambiar a un ID de modelo separado.

¿Por qué la imagen no aparece de inmediato en la respuesta? Todos los modelos de imagen de hiapi son asíncronos: POST /v1/tasks solo devuelve taskId. Debes consultar GET /v1/tasks/<id> hasta que status sea success, o registrar un callback para obtener el arreglo output real.

¿Cuánto tarda una tarea? Normalmente un número de segundos de un solo dígito, ocasionalmente más bajo carga alta. Usa un tiempo de espera de polling holgado (60–120 segundos) en lugar de asumir que siempre se completará de inmediato.

¿Puedo pasar varias imágenes de referencia al editar? Sí, image_urls acepta hasta 16 imágenes: indica en el prompt la función de cada imagen (por ejemplo, "usa la pose de la primera imagen con la ropa de la segunda imagen"), ya que el orden del arreglo importa.

¿Qué pasa si mi URL de callback no es accesible cuando la tarea se completa? hiapi llama una vez cuando la tarea alcanza el estado final (when: "final"). Si tu endpoint no es accesible, no recibirás la notificación: para cualquier caso que no pueda perderse, usa el polling como respaldo o concilia periódicamente el ID de tarea que registraste con GET /v1/tasks/<id>.

¿Necesito almacenar yo mismo las URL de salida? Sí: la url en output[0] es temporal y caduca. Descarga o vuelve a subir la imagen a tu propio almacenamiento inmediatamente después de que la tarea tenga éxito.