Come usare gpt-image-2.5-flare tramite l'API di hiapi

gpt-image-2.5-flare è un singolo modello su hiapi che gestisce sia la generazione di immagini da testo sia la modifica delle immagini attraverso lo stesso endpoint unificato — non è necessario utilizzare due ID modello separati per "generazione" e "modifica". Questa guida ti accompagnerà nella generazione di immagini utilizzabili da zero in pochi minuti con l'API dei task asincroni di hiapi, includendo un esempio completo in Node.js e i pattern di livello produttivo che ti serviranno prima di andare live (callback, idempotenza, retry).

Cosa ti serve

• Una chiave API di hiapi. Registrati e ottienila dalla console — la chiave ha la forma sk-... e va inserita nell'header Authorization: Bearer.
• Qualsiasi client HTTP. Gli esempi seguenti usano Node.js 18+ (fetch integrato), ma le stesse tre chiamate possono essere eseguite con curl, Python o qualsiasi strumento in grado di inviare richieste POST JSON.

hiapi espone gpt-image-2.5-flare attraverso la stessa famiglia di endpoint asincroni: invii un task, poi ne interroghi il risultato periodicamente oppure ricevi un callback webhook al completamento del task. Non esiste una chiamata sincrona "aspetta l'immagine nel corpo della risposta" — la generazione richiede diversi secondi, quindi l'API è basata su task fin dall'inizio.

Esempio minimo funzionante (Node.js)

Il codice seguente crea un task, ne interroga lo stato fino al completamento e stampa l'URL dell'immagine generata.

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

Esegui con HIAPI_API_KEY=sk-... node generate.js. L'array data.output nella risposta compare solo quando status è "success"; ogni voce ha un url temporaneo (con expireAt), quindi scarica o ricarica subito, invece di salvare il link.

Se vuoi modificare un'immagine esistente invece di generarla da zero, aggiungi input.image_urls (un array di URL accessibili pubblicamente, da 1 a 16 immagini) e descrivi nel prompt l'elaborazione di ciascuna immagine — stesso modello, stesso endpoint, nessun ID modello "edit" separato:

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"],
  },
}),

Altri campi input utili: background (auto / transparent / opaque, predefinito auto) e output_format (png / jpeg / webp, predefinito webp). Questo modello non ha un campo resolution — le dimensioni sono controllate interamente tramite aspect_ratio (accetta anche dimensioni esplicite in pixel come 1536x1024, se hai bisogno di dimensioni precise in pixel anziché di un rapporto).

Pattern di livello produttivo

In produzione usa i callback invece del polling. Il polling va bene per gli script, ma per un vero backend registra un webhook e lascia che hiapi ti notifichi nel momento esatto in cui il task si completa, invece di inviare ripetutamente GET /v1/tasks/<id> a intervalli regolari:

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
  },
}),

Il tuo handler webhook riceve lo stesso oggetto task del polling con GET /v1/tasks/<id> — controlla status e gestisci i casi success e fail separatamente.

Rendi i retry idempotenti. Se il tuo executor di task ritenta le chiamate HTTP fallite (timeout, 5xx, problemi di rete) senza accorgersene, potrebbe inviare involontariamente due volte lo stesso task di generazione e pagare entrambi. Passa un header Idempotency-Key stabile — massimo 255 byte, di solito il tuo ID task/richiesta — e i retry con la stessa key restituiranno il task originale invece di crearne uno nuovo:

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

Gestisci i casi di errore specifici. I seguenti codici di stato vanno gestiti con rami espliciti, invece di trattare ogni caso come "riprova":

Codice di stato	Significato	Come gestirlo
401 con error.code: "permission_denied"	Chiave API errata o mancante	Non riprovare — controlla l'header Authorization
402	Saldo insufficiente	Non riprovare — prima ricarica
400	Corpo della richiesta non valido (campo errato, tipo errato)	Non riprovare alla cieca — correggi il corpo della richiesta
503	Temporaneamente non disponibile	Puoi riprovare in sicurezza con backoff
Task con status: "fail"	Il task è fallito dopo essere stato accettato (ad esempio image_urls non accessibili)	Controlla error.code / error.message, non entrare in un ciclo infinito

Il corpo della risposta di errore 401 è il seguente — tutti i modelli hiapi hanno la stessa forma, quindi vale la pena controllarlo una volta in un handler di errori condiviso:

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

Riferimenti

• Pagina del modello gpt-image-2.5-flare — prezzi in tempo reale e un playground per provare i prompt online, utile per testare prima di integrare il codice.
• Documentazione dell'API dei task asincroni: creazione di un task e recupero dello stato del task — riferimento completo dei campi per tutti i modelli (non solo questo).
• Documentazione sull'autenticazione — come funzionano le chiavi API e l'header Authorization in tutti gli endpoint hiapi.
• Devi migrare codice esistente da gpt-image-2 o cerchi un tutorial di modifica specifico per Sunburst? Consulta la guida all'API di GPT Image 2.5 per il percorso di migrazione.
• Prezzi — costo attuale per immagine suddiviso per livello di qualità (non riportato qui perché cambia).

Domande frequenti

gpt-image-2.5-flare è un modello o due (generazione + modifica)? Uno. Genera o modifica a seconda che tu includa o meno input.image_urls — non serve passare a un ID modello separato.

Perché l'immagine non compare subito nella risposta? Tutti i modelli di immagine di hiapi sono asincroni — POST /v1/tasks restituisce solo il taskId. Devi interrogare GET /v1/tasks/<id> finché status non è success, oppure registrare un callback per ottenere l'effettivo array output.

Quanto tempo richiede un task? Di solito pochi secondi, occasionalmente di più con carico elevato. Usa un timeout di polling generoso (60–120 secondi), invece di dare per scontato che si completi sempre immediatamente.

Posso passare più immagini di riferimento durante la modifica? Sì, image_urls accetta fino a 16 immagini — specifica nel prompt il ruolo di ciascuna immagine (ad esempio "usa la posa della prima immagine con l'abbigliamento della seconda"), perché l'ordine dell'array è importante.

Cosa succede se il mio URL di callback non è raggiungibile al completamento del task? hiapi chiama una sola volta quando il task raggiunge lo stato finale (when: "final"). Se il tuo endpoint non è raggiungibile non ricevi la notifica — per qualsiasi caso in cui non puoi perdere l'evento, usa il polling come fallback, oppure riconcilia periodicamente con GET /v1/tasks/<id> usando l'ID task che hai registrato.

Devo archiviare io gli URL di output? Sì — l'url in output[0] è temporaneo e scade. Dopo il successo del task scarica o ricarica immediatamente sul tuo storage.