Comment utiliser ideogram-v4.5 via l'API HiAPI : curl, Python et une requête fonctionnelle

Ce que ideogram-v4.5 sur HiAPI vous apporte

Quand le texte dans une image compte vraiment, ideogram-v4.5 est le modèle qu'il vous faut. Mises en page d'affiches, logos, rendus de packaging, cartes sociales — tous les scénarios où un titre mal orthographié ou une légende floue ruine le visuel : c'est précisément là que ce modèle apporte de la valeur. Si vous générez des textures abstraites ou des paysages photographiques où rien n'a besoin d'être lisible, un modèle d'image générique est généralement moins cher et plus rapide.

Cet article est un guide d'intégration, pas une évaluation du modèle. À la fin, vous disposerez d'une requête exécutable, d'un client Python réalisant la même opération, et d'une fonction utilitaire réutilisable qui gère les points où l'on se trompe habituellement : le paramètre de ratio d'aspect, l'interrogation répétée des tâches asynchrones et la récupération des sorties.

Un point à intégrer dès le départ : la génération d'images sur HiAPI est une API de tâches asynchrones. Vous soumettez une requête, vous recevez un identifiant, puis vous interrogez jusqu'à ce que la tâche soit terminée. Le code qui suppose que le corps de la réponse contient déjà l'image ne fonctionnera pas. Chaque section ci-dessous converge vers ce schéma.

Avant d'envoyer la requête

Quatre éléments sont nécessaires avant le premier appel.

1. Clé d'API

Créez-en une dans la console de votre compte HiAPI et tenez-la à l'écart du contrôle de version. Exportez-la comme variable d'environnement plutôt que de la coller dans un script :

export HIAPI_API_KEY="your_key_here"

2. URL de base

Toutes les requêtes sont envoyées à l'URL de base de l'API HiAPI, avec le chemin spécifique de l'endpoint de génération ajouté. La documentation de la plateforme liste le chemin actuel ; si la documentation diffère, ne codez pas en dur un chemin vu dans un article de blog (y compris celui-ci).

3. Identifiant du modèle

La chaîne de modèle que vous passez dans le corps de la requête identifie ideogram-v4.5. Utilisez la casse exacte affichée dans la liste des modèles de la plateforme — les identifiants de modèle sont comparés littéralement, et le moindre écart renvoie une erreur de validation, pas une suggestion utile.

4. Référence des paramètres

La page du modèle ideogram-v4.5 est la source d'autorité pour les champs acceptés par le corps de la requête : limite de longueur du prompt, ratios d'aspect pris en charge, formats de sortie et tout contrôle de graine ou de style. Lisez-la avant d'écrire du code. Les paramètres qui n'y figurent pas peuvent être silencieusement ignorés ou rejetés, et deviner les valeurs est la façon la plus courante de perdre du temps en débogage.

Avec ces quatre éléments, vous pouvez envoyer votre première requête.

Une requête curl fonctionnelle

Voici un exemple de soumission minimal. Si votre compte affiche des valeurs différentes, remplacez le chemin de l'endpoint et l'identifiant du modèle par ceux de la documentation de la plateforme.

curl -X POST "$HIAPI_BASE_URL/<generation-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4.5",
    "input": {
      "prompt": "A vintage travel poster for the Amalfi Coast, bold serif headline reading \"AMALFI\", warm sunset palette, grainy print texture"
    }
  }'

Le rôle de chaque partie :

• Authorization — authentification par bearer token. Un en-tête manquant ou mal formé est la cause la plus fréquente des 401.
• Content-Type — doit être application/json. Certains clients HTTP ne le définissent pas automatiquement en POST, ce qui produit des erreurs de parsing déroutantes côté serveur.
• model — l'identifiant littéral du modèle. Placez-le au niveau supérieur du corps de la requête, comme indiqué dans la documentation.
• input.prompt — votre instruction de génération. Comme montré ci-dessus, mettez entre guillemets le texte que vous voulez voir rendu dans l'image, afin que le modèle le traite comme une copie littérale et non comme une description.
• input.* — tous les autres paramètres de génération (ratio d'aspect, format, graine, etc.) appartiennent à cet objet imbriqué, aux côtés de prompt.

Une soumission réussie renvoie un objet JSON contenant l'identifiant de la tâche et un champ de statut. Il n'y a pas d'image dans cette réponse — c'est le comportement attendu. Conservez l'identifiant ; l'étape d'interrogation l'utilisera.

Effectuer le même appel en Python

La version Python est une traduction un pour un. Nous utilisons requests et partageons le même corps de requête, pour que vous puissiez comparer les deux côte à côte.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
GEN_PATH = "/<generation-path>"  # confirm in platform docs

payload = {
    "model": "ideogram-v4.5",
    "input": {
        "prompt": (
            "A vintage travel poster for the Amalfi Coast, bold serif "
            'headline reading "AMALFI", warm sunset palette, grainy print texture'
        )
    },
}

response = requests.post(
    BASE_URL + GEN_PATH,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=30,
)
response.raise_for_status()

job = response.json()
print(job)

Deux choix délibérés :

• json.dumps plutôt que json= rend le format de transport visiblement identique à l'exemple curl. Les deux fonctionnent ; l'écriture explicite facilite l'inspection de ce que vous envoyez réellement lors du débogage.
• timeout=30 ne concerne que la soumission. La soumission est rapide, la génération ne l'est pas. Ne laissez jamais l'appel de soumission hériter d'un timeout court prévu pour l'interrogation, sinon vous signalerez comme échouées des tâches qui fonctionnent correctement.

Le dictionnaire job affiché contient l'identifiant de la tâche et le statut actuel. Stockez l'identifiant quelque part — la boucle d'interrogation en dépend.

Contrôler le ratio d'aspect et le format de sortie

Le ratio d'aspect et le format de sortie sont des paramètres du corps de la requête, pas des endpoints séparés. Ils se trouvent dans le même objet input que le prompt :

{
  "model": "ideogram-v4.5",
  "input": {
    "prompt": "...",
    "aspect_ratio": "<ratio from docs>",
    "output_format": "<format from docs>"
  }
}

La discipline importante ici est de ne pas deviner les valeurs. Chaque modèle de génération expose des énumérations fixes de ratios et de formats, et les modèles acceptent des orthographes différentes — 16:9 contre 16x9, png contre PNG, etc. Passer une valeur non prise en charge par le modèle produit généralement une erreur de validation ou, pire, un retour silencieux à la sortie par défaut, qui ressemble à un bug dans votre prompt.

Le flux de travail est donc le suivant :

1. Ouvrez la page du modèle ideogram-v4.5 sur la plateforme et copiez mot pour mot la liste des ratios d'aspect et des formats de sortie pris en charge.
2. Placez ces valeurs dans une petite liste blanche dans votre code, afin que les entrées invalides échouent au point d'appel plutôt qu'au niveau de l'API.
3. Utilisez par défaut un ratio correspondant à votre mise en page en aval. Si l'image doit s'insérer dans un emplacement de carte sociale de 1200×630, choisissez une valeur proche de ce ratio plutôt que de générer un carré puis de rogner le contenu.

Les images riches en texte méritent un avertissement supplémentaire : les ratios extrêmes (bannières ultra-larges, affiches ultra-hautes) compressent l'espace disponible pour le rendu du texte. Pour les titres que vous voulez vraiment lisibles, un ratio paysage ou portrait modéré est plus sûr qu'un ratio panoramique extrême.

Gérer les tâches asynchrones et télécharger les résultats

Le cycle de vie d'une génération se déroule en trois étapes : soumettre → interroger → récupérer.

Soumettre

Vous maîtrisez déjà cette étape grâce aux sections précédentes. La réponse vous donne un identifiant de tâche et un statut, par exemple queued ou processing.

Interroger

Interrogez l'endpoint de statut de la tâche avec cet identifiant jusqu'à ce que le statut indique l'achèvement. Deux règles rendent ce processus propre :

• Dormez entre les interrogations. Commencez par environ une seconde et augmentez progressivement. Marteler l'endpoint de statut ne fera pas terminer la tâche plus vite et risque de déclencher une limitation de débit.
• Limitez la durée d'attente. Fixez un nombre maximal de tentatives ou une échéance, et signalez une erreur explicite en cas de dépassement, plutôt que de boucler indéfiniment.

import time

def wait_for_job(job_id, headers, base_url, status_path,
                 max_attempts=60, initial_delay=1.0, factor=1.5):
    delay = initial_delay
    for _ in range(max_attempts):
        r = requests.get(
            f"{base_url}{status_path}/{job_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "completed", "success"):
            return data
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended with status {status}: {data}")
        time.sleep(delay)
        delay *= factor
    raise TimeoutError(f"job {job_id} did not finish in time")

Consultez la documentation de la plateforme pour connaître les chaînes de statut et le chemin de statut exacts de votre compte — comparez avec les valeurs de la documentation et traitez tout statut non reconnu comme toujours en cours, plutôt que comme un succès.

Récupérer

Lorsque la tâche signale son achèvement, la réponse contient l'emplacement de la sortie (généralement une URL). Téléchargez-la avec un simple GET et écrivez les octets sur disque. L'URL de sortie peut être limitée dans le temps, alors téléchargez rapidement plutôt que de stocker l'URL pour un usage ultérieur. Tout ce qu'il faut savoir pour écrire cette boucle provient de la structure de la réponse de soumission — il n'y a pas d'API « récupérer l'image » séparée à apprendre.

Encapsuler dans une fonction utilitaire réutilisable

Trois scripts en ligne réimplémentant chacun l'interrogation, c'est un problème de maintenance. Emballez-le une fois.

import os, json, time, requests

class IdeogramClient:
    def __init__(self, base_url, api_key, gen_path, status_path,
                 poll_attempts=60, poll_factor=1.5):
        self.base_url = base_url.rstrip("/")
        self.gen_path = gen_path
        self.status_path = status_path
        self.poll_attempts = poll_attempts
        self.poll_factor = poll_factor
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }

    def generate(self, prompt, **params):
        body = {"model": "ideogram-v4.5", "input": {"prompt": prompt, **params}}
        r = requests.post(self.base_url + self.gen_path,
                          headers=self.headers,
                          data=json.dumps(body), timeout=30)
        r.raise_for_status()
        job = r.json()
        done = self._wait(job["id"])
        url = done["output"]["url"]  # confirm shape in docs
        return self._download(url)

    def _wait(self, job_id):
        delay = 1.0
        for _ in range(self.poll_attempts):
            r = requests.get(f"{self.base_url}{self.status_path}/{job_id}",
                             headers=self.headers, timeout=30)
            r.raise_for_status()
            data = r.json()
            if data.get("status") in ("succeeded", "completed", "success"):
                return data
            if data.get("status") in ("failed", "error", "cancelled"):
                raise RuntimeError(data)
            time.sleep(delay)
            delay *= self.poll_factor
        raise TimeoutError(job_id)

    def _download(self, url):
        r = requests.get(url, timeout=60)
        r.raise_for_status()
        return r.content

L'utilisation ne demande qu'un seul appel : img_bytes = IdeogramClient(...).generate("...", aspect_ratio="<from docs>"). Ajustez l'accès à done["output"]["url"] et les chaînes de statut pour qu'ils correspondent à la structure de réponse de la documentation — ce sont les deux endroits les plus susceptibles de nécessiter un réglage selon le compte.

Erreurs courantes et astuces de débogage

La plupart des échecs de la première semaine se répartissent en cinq catégories.

401 / 403 — authentification. Clé manquante, espace blanc dû au copier-coller, ou préfixe Bearer absent. Affichez les quatre premiers et derniers caractères de la clé que vous envoyez réellement ; le retour à la ligne final introduit par un fichier d'environnement est le coupable classique.

400 — JSON mal formé ou champ inconnu. Si le corps de la requête est assemblé par concaténation de chaînes, des guillemets non échappés dans le prompt cassent le JSON. Construisez le corps comme un dictionnaire et sérialisez-le avec json.dumps. Si le JSON se parse, le suspect suivant est un nom de paramètre que le modèle n'accepte pas — vérifiez vos clés caractère par caractère par rapport à la page du modèle.

404 / modèle introuvable. Généralement une erreur d'orthographe ou de casse dans l'identifiant du modèle, ou un chemin d'endpoint obsolète. Copiez les deux depuis la documentation de la plateforme, pas de mémoire ni depuis un ancien tutoriel.

429 — limitation de débit. Presque toujours dû à une interrogation trop agressive. Augmentez le délai initial d'interrogation et le facteur de backoff. Côté soumission, ajoutez des tentatives avec jitter pour les réponses 429 et 5xx, mais ne réessayez pas les erreurs de validation 4xx — elles échoueront de la même manière à chaque fois.

Tâche réussie mais image impossible à ouvrir. Vérifiez que vous téléchargez bien des octets et non une page d'erreur JSON ; appeler raise_for_status() sur le GET de téléchargement intercepte la plupart de ces problèmes. Vérifiez aussi que vous traitez l'URL de téléchargement comme valable à court terme, plutôt que de la mettre en cache entre sessions.

En cas de doute, journalisez le corps complet de la réponse et le code de statut de chaque appel dans toute la chaîne — soumission, chaque interrogation et le téléchargement. L'API indique généralement clairement où ça a échoué ; le bug vient souvent du fait que nous n'avons jamais regardé.

Avec une soumission fonctionnelle, une boucle d'interrogation et une gestion d'erreurs raisonnable, ideogram-v4.5 s'intègre dans un vrai pipeline comme n'importe quel autre appel de modèle HiAPI.