gpt-image-2.5-flare pour les photos produits e-commerce : un workflow par lots via l'API hiapi

La photographie produit est généralement l'étape la plus lente de la mise en ligne d'un catalogue : chaque SKU doit être photographié en studio, chaque arrière-plan saisonnier doit être repris, et chaque format d'image imposé par une plateforme doit être tourné à nouveau. gpt-image-2.5-flare sur hiapi regroupe l'essentiel de ce travail dans un seul ID de modèle : il génère des photos produits à partir d'un prompt texte et modifie aussi des photos existantes (remplacement d'arrière-plan, mise en scène dans un contexte de vie, adaptation des dimensions aux différents canaux), sans altérer le produit lui-même. Ce guide le démontre à travers trois workflows réels et des sorties d'API non retouchées, puis montre comment l'appliquer par lots à tout le catalogue, plutôt qu'à une seule image à la fois.

Les produits présentés ci-dessous (un flacon en verre vert étiqueté « MOSS » et une bouilloire bleu cobalt étiquetée « AER ») sont des accessoires conceptuels servant à illustrer la technique ; il ne s'agit pas de photographies clients réelles. En revanche, chaque image est une sortie réelle et non retouchée de l'API hiapi, et non une simulation.

Pourquoi l'essentiel tient à un seul ID de modèle

gpt-image-2.5-flare traite deux types de tâches différents selon ce que vous lui transmettez :

• Si vous omettez image_urls, il génère une image uniquement à partir de votre prompt texte (texte vers image).
• Si vous ajoutez image_urls, il modifie la photo fournie (image vers image) : même modèle, même endpoint, même tarification.

Pour un catalogue, c'est plus important qu'il n'y paraît : que vous photographiiez un produit pour la première fois ou que vous réutilisiez une photo existante, vous n'avez pas à jongler entre deux ID de modèles ou deux grilles tarifaires. Deux autres détails le rendent particulièrement adapté au traitement par lots :

• Des paliers de qualité plutôt qu'un coût fixe unique. Vous choisissez low / medium / high / xhigh / max par requête, de sorte qu'un lot de vignettes pour 500 SKU et la douzaine de visuels principaux de la page d'accueil n'ont pas à être facturés au même coût unitaire.
• Des ratios d'aspect flexibles. Chaque requête peut opter pour 1:1, 4:5, 9:16, 16:9 et d'autres ratios : une même photo produit peut donc être recadrée en carré pour une grille de place de marché, en vertical pour un fil mobile ou en bannière large, sans nouvelle prise de vue.

Chaque appel passe par l'API de tâches asynchrones de hiapi : POST /v1/tasks soumet une tâche, puis vous interrogez GET /v1/tasks/{id} (ou utilisez un callback) jusqu'à ce que le statut soit success. Il n'existe pas d'appel synchrone qui renvoie directement l'image dans la réponse : la génération comme l'édition prennent plusieurs secondes.

Étape 1 : générer une photo de studio propre à partir de zéro

Commencez par une photo de studio simple et bien éclairée : c'est la base que vous allez ensuite retoucher.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" est une valeur par défaut raisonnable pour un premier passage : toutes les images de cet article utilisent ce même palier. Ne passez un SKU donné à high que lorsque le détail supplémentaire justifie le coût (voir le tableau tarifaire ci-dessous).

Étape 2 : redessiner l'arrière-plan sans régénérer le produit

C'est le workflow qui fait réellement gagner du travail sur un catalogue : repassez la photo de studio en image_urls, décrivez uniquement la modification souhaitée, et le produit reste identique au pixel près (même forme de flacon, même bouchon, même étiquette) tandis que l'arrière-plan change.

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

Le même schéma fonctionne pour des produits totalement différents : ici une bouilloire bleu cobalt, dont l'arrière-plan a été remplacé par un fond de studio pêche chaleureux, générée de la même façon :

C'est le cœur de la tâche « rafraîchissement saisonnier » ou « nouveau thème de marché » : un appel d'édition par SKU, le produit reste intact, l'arrière-plan change. Répétez 500 fois et vous avez rhabillé tout le catalogue sans nouvelle prise de vue.

Étape 3 : mettre le produit en scène dans un contexte de vie

Les photos de studio conviennent bien aux grilles de place de marché ; les scènes de vie servent à vendre le produit sur une page d'atterrissage ou dans une publicité. Même schéma d'édition, prompt plus ambitieux : le modèle place le produit exact dans un contexte réel plausible, et ne se contente pas de changer la couleur de l'arrière-plan.

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

Conservez une formulation contraignante dans chaque prompt d'édition (« keep the original ... completely unchanged ») : c'est elle qui empêche le modèle de faire dériver le produit alors qu'il modifie tout ce qui l'entoure.

Automatisation par lots pour un catalogue complet

Un appel d'édition isolé est utile ; à l'échelle d'un catalogue, la valeur réside dans l'exécution du même schéma sur chaque SKU, sans intervention. Voici une structure qui fait ses preuves en production :

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

Au-delà de quelques images, plusieurs points comptent :

• Une clé d'idempotence par ligne. Envoyez un en-tête Idempotency-Key distinct pour chaque SKU/variante, afin qu'une requête réessayée après un timeout ne crée pas de tâche en double, ni ne la facture deux fois.
• Limitez la concurrence, ne lancez pas tout d'un coup. Un petit pool de threads (ou un sémaphore asynchrone) évite de déclencher les limites de débit ; en cas de 429, reculez et réessayez au lieu de le traiter comme un échec définitif.
• Choisissez le palier de qualité selon l'usage de l'image, non selon un standard unique : les vignettes et les listings de grille se contentent souvent de low/medium, tandis qu'un visuel principal de page d'accueil ou une création publicitaire mérite high ou xhigh.
• Dérivez les différents ratios d'aspect à partir de la même image source éditée, et non de l'originale : lancez d'abord une fois l'édition de remplacement d'arrière-plan, puis demandez à partir de ce résultat des recadrages en 1:1, 4:5 et 9:16, pour que chaque canal affiche exactement la même présentation du produit.
• Téléchargez ou réhébergez immédiatement l'URL de sortie. Les sorties de tâches expirent ; ne conservez pas une URL temporaire comme source permanente de vos images.

Tarification

gpt-image-2.5-flare est facturé au nombre d'images produites, selon le palier de qualité, au même tarif que ce soit pour une génération à partir de zéro ou une édition :

Qualité	Prix par image
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

Au palier medium, refondre le thème d'un catalogue de 500 SKU, avec une édition de remplacement d'arrière-plan par produit, coûte environ $33.60. Consultez la page de tarification pour la grille tarifaire complète et à jour de tous les modèles.

Questions fréquentes

Une édition peut-elle modifier mon produit par inadvertance ? Limitez le prompt d'édition à une seule modification (« change ONLY the seamless background... ») et énumérez explicitement ce qui doit rester inchangé (forme, couleur, texte de l'étiquette, angle de caméra). Les exemples ci-dessus montrent un produit qui reste identique à chaque édition.

Un même modèle peut-il générer et éditer ? Oui : gpt-image-2.5-flare est un seul ID de modèle. Incluez image_urls pour éditer une photo existante ; omettez-le pour générer uniquement à partir du prompt.

Combien d'images sources peut-on transmettre à un appel d'édition ? Jusqu'à 16 via image_urls, même si la plupart des éditions de catalogue de produits n'en nécessitent qu'une : la photo que vous souhaitez redessiner.

Comment éviter la double facturation lors d'un nouvel essai ? Envoyez un en-tête Idempotency-Key unique pour chaque requête. Une requête réessayée avec la même clé renvoie la tâche d'origine au lieu d'en créer une nouvelle.

Pour aller plus loin

Si vous préparez votre premier appel, commencez par le guide de l'API gpt-image-2.5-flare pour obtenir un exemple minimal fonctionnel et approfondir le cycle de vie des tâches asynchrones. Pour davantage de schémas de prompts au-delà de la photographie produit, consultez GPT Image 2.5 Flare : recettes de prompts à copier-coller avec sorties réelles. Les paramètres et le schéma complets figurent sur la page du modèle, et les conventions générales de l'API (authentification, interrogation des tâches, callbacks) dans la documentation hiapi.

Prêt à l'essayer sur votre propre catalogue ? Obtenez une clé API depuis le tableau de bord hiapi, puis lancez l'exemple de photo de studio ci-dessus sur votre première photo produit.