Comment utiliser gpt-image-2.5-flare via l'API hiapi

gpt-image-2.5-flare est un modèle unique sur hiapi qui gère à la fois la génération d'images à partir de texte et l'édition d'images via le même point de terminaison unifié — vous n'avez pas besoin d'utiliser deux ID de modèle distincts, « génération » et « édition ». Ce guide vous accompagne de zéro jusqu'à la génération d'images exploitables en quelques minutes avec l'API de tâches asynchrones de hiapi, avec un exemple Node.js complet ainsi que les patterns de niveau production dont vous aurez besoin avant la mise en ligne (callbacks, idempotence, réessais).

Ce dont vous avez besoin

• Une clé API hiapi. Inscrivez-vous et récupérez-la depuis la console — la clé ressemble à sk-... et se place dans l'en-tête Authorization: Bearer.
• N'importe quel client HTTP. Les exemples ci-dessous utilisent Node.js 18+ (avec fetch intégré), mais les mêmes trois appels peuvent être effectués avec curl, Python ou tout outil capable d'envoyer des requêtes POST JSON.

hiapi expose gpt-image-2.5-flare via la même famille de points de terminaison asynchrones : vous soumettez une tâche, puis vous interrogez le résultat, ou vous recevez un webhook callback lorsque la tâche est terminée. Il n'y a pas d'appel synchrone qui « attend l'image dans le corps de la réponse » — la génération prend plusieurs secondes, donc l'API est basée sur des tâches depuis le départ.

Exemple minimal fonctionnel (Node.js)

Le code ci-dessous crée une tâche, interroge jusqu'à l'achèvement et affiche l'URL de l'image générée.

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

Exécutez avec HIAPI_API_KEY=sk-... node generate.js. Le tableau data.output de la réponse n'apparaît que lorsque status vaut "success" ; chaque entrée possède une url temporaire (avec expireAt), alors téléchargez-la ou réhébergez-la immédiatement plutôt que de conserver le lien.

Si vous souhaitez éditer une image existante plutôt que d'en générer une depuis zéro, ajoutez input.image_urls (un tableau d'URL accessibles publiquement, 1 à 16 images) et décrivez dans le prompt le traitement à appliquer à chaque image — même modèle, même point de terminaison, pas d'ID de modèle « édition » séparé :

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

Autres champs input utiles : background (auto / transparent / opaque, par défaut auto) et output_format (png / jpeg / webp, par défaut webp). Ce modèle n'a pas de champ resolution — les dimensions sont entièrement contrôlées par aspect_ratio (il accepte aussi des dimensions explicites en pixels comme 1536x1024 si vous avez besoin de pixels exacts plutôt que d'un ratio).

Patterns de niveau production

Utilisez les callbacks au lieu du polling en production. Le polling convient aux scripts, mais pour un vrai backend, enregistrez un webhook pour que hiapi vous notifie au moment où la tâche se termine, au lieu de solliciter régulièrement GET /v1/tasks/<id> :

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

Votre handler de webhook reçoit le même objet tâche que le polling GET /v1/tasks/<id> — vérifiez status et branchez selon success ou fail.

Rendez les réessais idempotents. Si votre exécuteur de tâches réessaie des appels HTTP échoués (timeout, 5xx, instabilité réseau) sans précaution, il risque de soumettre deux fois la même tâche de génération et de payer les deux. Passez un en-tête Idempotency-Key stable — jusqu'à 255 octets, généralement votre propre ID de tâche/requête — et les requêtes de réessai avec la même clé renvoient la tâche d'origine au lieu d'en créer une nouvelle :

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

Gérez les modes d'échec spécifiques. Les codes de statut suivants doivent être traités par des branches explicites plutôt que de tout considérer comme « à réessayer » :

Code de statut	Signification	Traitement
401 et error.code: "permission_denied"	Clé API incorrecte ou manquante	Ne pas réessayer — vérifiez l'en-tête Authorization
402	Solde insuffisant	Ne pas réessayer — rechargez d'abord
400	Corps de requête invalide (champ erroné, type incorrect)	Ne pas réessayer à l'aveugle — corrigez le corps de requête
503	Temporairement indisponible	Réessai avec backoff sans risque
Tâche status: "fail"	La tâche a échoué après avoir été acceptée (par exemple des image_urls inaccessibles)	Vérifiez error.code / error.message, ne bouclez pas indéfiniment

Voici le corps d'une réponse d'erreur 401 — tous les modèles hiapi ont la même forme, il vaut donc la peine de le vérifier une fois dans un gestionnaire d'erreurs partagé :

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

Référence

• Page du modèle gpt-image-2.5-flare — tarification en temps réel et un playground pour tester un prompt en ligne, pratique avant d'intégrer le code.
• Documentation de l'API de tâches asynchrones : créer une tâche et obtenir le statut d'une tâche — référence complète des champs pour tous les modèles (pas seulement celui-ci).
• Documentation d'authentification — comment fonctionnent la clé API et l'en-tête Authorization sur tous les points de terminaison hiapi.
• Besoin de migrer du code existant depuis gpt-image-2, ou envie d'un tutoriel d'édition spécifique à Sunburst ? Consultez le Guide de l'API GPT Image 2.5 pour le parcours de migration.
• Tarification — coût actuel par image selon les paliers de qualité (non reproduit ici car il change).

FAQ

gpt-image-2.5-flare est-il un modèle ou deux (génération + édition) ? Un seul. Qu'il génère ou édite dépend uniquement de la présence ou non de input.image_urls — pas besoin de basculer vers un ID de modèle séparé.

Pourquoi l'image n'apparaît-elle pas immédiatement dans la réponse ?Tous les modèles d'image de hiapi sont asynchrones — POST /v1/tasks renvoie seulement un taskId. Vous devez interroger GET /v1/tasks/<id> jusqu'à ce que status vaille success, ou enregistrer un callback pour obtenir le tableau output réel.

Combien de temps prend une tâche ?Généralement quelques secondes, parfois plus en cas de forte charge. Utilisez un timeout de polling généreux (60 à 120 secondes) plutôt que de supposer qu'elle se termine toujours immédiatement.

Peut-on passer plusieurs images de référence pour l'édition ?Oui, image_urls accepte jusqu'à 16 images — précisez dans le prompt le rôle de chaque image (par exemple « utilisez la pose de la première image avec la tenue de la deuxième »), car l'ordre du tableau compte.

Que se passe-t-il si mon URL de callback est inaccessible lorsque la tâche se termine ?hiapi appelle une seule fois lorsque la tâche atteint son état final (when: "final"). Si votre point de terminaison est inaccessible, vous ne recevrez pas de notification — pour tout cas où un oubli est inacceptable, utilisez le polling en solution de repli, ou réconciliez périodiquement avec GET /v1/tasks/<id> en utilisant l'ID de tâche que vous avez enregistré.

Dois-je stocker moi-même les URL de sortie ?Oui — l'url dans output[0] est temporaire et expire. Téléchargez-la ou réhébergez-la dans votre propre stockage immédiatement après le succès de la tâche.