Comment utiliser l'API Ideogram 4.5 ? Génération, édition et suivi des tâches

TL;DR

• Ideogram 4.5 est une famille de génération d'images à partir de texte qui privilégie la typographie : ideogram-v4.5/text-to-image génère des visuels contenant du texte comme des affiches, des logos ou des packaging bilingues, tandis que ideogram-v4.5/image-to-image utilise Precise Edit pour modifier précisément du texte, appliquer le style d'une image de référence ou repeindre une zone via un masque. Vous pouvez choisir une tâche depuis la page du modèle ou appeler l'API comme décrit ci-dessous.
• Le prix est calculé à l'image et varie selon le niveau de qualité : LOW 0,043 $, MEDIUM (par défaut) 0,086 $, HIGH 0,3145 $ ; en édition, à partir de 0,0115 $ en VERY_LOW ; actuellement, chaque requête produit 1 image, num_images ne peut valoir que 1. Voir la page des tarifs.
• Les appels passent par l'API HiAPI /v1/tasks : après soumission, lisez data.taskId, puis interrogez data.status ; en cas de succès, récupérez dans data.output l'URL de l'élément dont type=image pour télécharger l'image.

Ce qu'il sait faire

• Structurer la hiérarchie du texte dans l'image : placez entre guillemets le texte qui doit apparaître et précisez séparément la position du titre, du sous-titre, de la date et du programme ; après génération, vérifiez chaque caractère.
• Explorer des compositions avec des tâches à une seule image : chaque requête produit 1 image ; ajustez le prompt ou la seed et soumettez plusieurs tâches pour comparer les directions.
• API d'édition associée : Precise Edit (edit_precision=high) permet des modifications ciblées comme un nom de marque ou une date ; comparez avec l'image source pour vérifier les zones conservées.
• Image de référence + masque : jusqu'à 4 images de référence (3 avec un masque) ; dans le masque, noir = repeindre, blanc = conserver.

Voici un résultat réel généré (niveau LOW) :

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(Signification en français : affiche de marque moderne et minimaliste pour une conférence de design, grand titre en gras "DESIGN FORWARD" centré, sous-titre plus petit "Typography Summit 2026" en dessous, mise en page en grille suisse épurée, palette orange chaud et bleu marine profond, formes géométriques, lettrage net et précis. Taille choisie : landscape_16_9.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, 0,043 $.

Générer avec ce prompt →

Quelle API choisir

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
Rôle	Générer un visuel mis en page à partir de texte	Modifier une image existante
Entrées obligatoires	prompt	image_url + prompt
Niveaux de qualité	low / medium / high	very_low / low / medium / high
Paramètres spécifiques	num_images: 1, enable_prompt_expansion	edit_precision (Precise), reference_image_urls, mask_url
Dimensions	6 préréglages, square_hd par défaut	auto (par défaut) ou 6 préréglages ; auto uniquement avec masque / Precise
Idéal pour	Affiches, logos, packaging, nouvelles enseignes	Changer du texte, adapter les couleurs, versions saisonnières, repeindre une zone

Pipeline typique : générer une affiche de marque, puis utiliser Edit pour remplacer le nom de marque ou la date par la version du client. Une génération LOW coûte 0,043 $, plus une modification Precise LOW à 0,043 $, soit 0,086 $ pour l'ensemble.

Deux parcours pour démarrer

Navigateur en 3 étapes : ouvrez la page du modèle → collez le prompt et choisissez le niveau de qualité → cliquez sur Générer.

API en 3 étapes : POST /v1/tasks pour soumettre → lisez data.taskId → GET /v1/tasks/<taskId> pour consulter data.status, puis téléchargez une fois success atteint.

curl : la première image

Définissez d'abord dans le terminal HIAPI_IDEMPOTENCY_KEY comme identifiant unique de cette opération métier ; réutilisez cette valeur lors des nouvelles tentatives de la même requête. L'exemple utilise explicitement LOW, un format paysage et l'extension de prompt activée.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

API d'édition : remplacez model par ideogram-v4.5/image-to-image et fournissez l'image source avec les instructions. L'exemple ci-dessous demande via Precise Edit de changer le texte tout en conservant la mise en page ; le résultat doit toujours être comparé à l'image source :

Pour cette tâche d'édition, définissez une autre clé HIAPI_EDIT_IDEMPOTENCY_KEY et ne réutilisez pas la clé de la tâche de génération.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python : soumettre, interroger, télécharger

Installez d'abord requests et définissez HIAPI_API_KEY ; pour la première soumission, définissez aussi HIAPI_IDEMPOTENCY_KEY, en utilisant une valeur distincte pour chaque nouvelle opération métier et en la conservant lors des nouvelles tentatives d'une même soumission. Le programme affiche d'abord l'ID de la tâche ; après une interruption, définissez HIAPI_TASK_ID pour reprendre l'interrogation et le téléchargement sans soumettre à nouveau la génération.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

En cas d'erreur réseau lors de l'interrogation ou du téléchargement, conservez l'ID de tâche déjà affiché avant de reprendre ; le script ne renvoie pas automatiquement la requête de création. Dans l'exemple, l'interrogation est limitée à 600 secondes avec une attente de 3 secondes entre chaque appel, et le téléchargement écrit d'abord un fichier .part avant de le renommer définitivement une fois terminé.

Tableau des paramètres

Génération ideogram-v4.5/text-to-image

Champ	Obligatoire	Valeurs	Description
prompt	Oui	1 à 10 000 caractères	Rédaction en quatre parties : quel visuel → texte et couleurs → mise en page → rendu et contraintes
quality	Non	low / medium / high, medium par défaut	low pour explorer en lot, medium au quotidien, high pour les versions finales avec beaucoup de petits textes
image_size	Non	6 préréglages, square_hd par défaut	Pas de largeur/hauteur personnalisée
num_images	Non	Fixé à 1	Chaque tâche produit 1 image
enable_prompt_expansion	Non	true par défaut	Extension du prompt ; false la désactive, mais il faut toujours vérifier le texte du résultat
seed	Non	Entier	Reproduire avec les mêmes paramètres

Édition ideogram-v4.5/image-to-image

Champ	Obligatoire	Valeurs	Description
image_url	Oui	URL de l'image	Image source
prompt	Oui	1 à 10 000 caractères	Instructions d'édition ; précisez ce qu'il faut changer et ce qu'il faut conserver
edit_precision	Non	regular / high, regular par défaut	high = Precise Edit, adapté aux modifications ciblées de texte
quality	Non	very_low / low / medium / high, medium par défaut	very_low n'est possible qu'avec regular
image_size	Non	auto ou 6 préréglages, auto par défaut	auto uniquement avec masque ou Precise
reference_image_urls	Non	Jusqu'à 4 images	Jusqu'à 3 avec un masque
mask_url	Non	URL de l'image	Noir = repeindre, blanc = conserver
num_images	Non	Fixé à 1	Chaque tâche produit 1 image
seed	Non	Entier

Si input contient un champ absent du tableau des paramètres de ce modèle, l'API renvoie 400 ; les champs de premier niveau comme model et callback se remplissent selon le format de l'API de tâches.

Erreurs que vous rencontrerez

Code de statut	Signification	Que faire
400 INVALID_REQUEST	Corps de requête invalide (prompt ou image_url manquant, valeur d'énumération erronée, champ hors tableau)	Corrigez le corps de la requête en suivant le tableau des paramètres
402 INSUFFICIENT_QUOTA	Solde insuffisant (aucun débit)	Rechargez puis réessayez
429 RATE_LIMITED	Limitation de débit déclenchée	Réduisez la fréquence de soumission
409 IDEMPOTENCY_KEY_PROCESSING	Une tâche avec la même clé est en cours de création	Attendez puis réessayez avec la même clé et le même corps de requête
422 IDEMPOTENCY_KEY_MISMATCH	La même clé est associée à un corps de requête différent	Restaurez le corps de requête d'origine ; ne changez de clé que pour une nouvelle opération métier

Un échec en état final peut inclure des codes d'erreur comme CONTENT_POLICY_VIOLATION, TASK_FAILED ou TASK_TIMEOUT. Conservez taskId et le message d'erreur, et vérifiez la facturation à partir de l'état final de la tâche et des enregistrements du compte ; ne confondez pas un échec d'interrogation ou de téléchargement avec un échec de génération.

À vérifier avant la mise en production

• Callback : transmettez "callback": {"url": "https://..."} au niveau supérieur du corps de la requête pour être notifié automatiquement à l'état final.
• Téléchargez rapidement : les URL des résultats dans data.output ont une durée de validité ; téléchargez-les dès le succès.
• Tâches à une image et idempotence : chaque exécution produit 1 image ; lors d'une nouvelle tentative pour la même opération métier après un délai d'attente, réutilisez la clé d'idempotence d'origine et n'utilisez une nouvelle clé que pour une nouvelle tâche métier.
• Petits textes en chinois : comparez les niveaux de qualité en fonction du texte réel ; relisez caractère par caractère avant livraison, medium ou high ne dispense pas de cette vérification.

Questions fréquentes

Combien d'images peut-on générer au maximum par requête ?

Actuellement, la génération et l'édition produisent chacune 1 image par exécution, et num_images ne peut valoir que 1. Soumettez des tâches séparées pour plusieurs directions.

Le niveau de qualité par défaut est-il LOW ?

Non. Par défaut, il s'agit de MEDIUM, à 0,086 $ par image ; pour LOW à 0,043 $ par image, transmettez explicitement quality: "low".

Quel mode utiliser pour ne changer que le nom de marque et la date ?

Vous pouvez choisir Precise Edit en transmettant explicitement edit_precision: "high", quality: "low" et image_size: "auto" ; 0,043 $ par image.

Que représentent les zones noires et blanches du masque ?

Les zones noires sont repeintes, les zones blanches conservées. Le masque doit avoir les mêmes dimensions que l'image source ; avec un masque, choisissez auto pour image_size.

Faut-il changer la clé d'idempotence après un délai d'attente à la soumission ?

Lors d'une nouvelle tentative pour la même opération métier, ne changez pas de clé : réutilisez le même Idempotency-Key et le même corps de requête ; n'utilisez une nouvelle clé que si vous avez réellement besoin d'une nouvelle tâche.

Étape suivante : récupérez le prompt de l'affiche DESIGN FORWARD pour générer une image sur la page du modèle, puis remplacez le titre par le nom de votre propre événement avec une instruction Precise. Lectures associées : les trois niveaux de prix et le budget · 4 exemples de prompts d'édition.

Pour commencer directement avec un logo ou une affiche d'événement, copiez cette série d'exemples de prompts.