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

La réputation des modèles Ideogram repose sur une chose que la plupart des modèles d'image ne savent toujours pas faire : la typographie. Les titres d'affiche sont correctement orthographiés, les lettres des logos sont nettes, et le texte des enseignes ne se transforme pas en un amas de caractères illisibles. ideogram-v4, comme tous les autres modèles d'image et de vidéo, est disponible sur hiapi via la même API de tâches unifiée, et ce guide parcourt l'intégralité de la requête : une version curl prête à copier-coller, un script Python complet, les paramètres que le schéma valide réellement (ils ne sont pas identiques à ceux exposés par l'API native d'Ideogram), et les erreurs que vous rencontrerez en pratique.

Ce que vous allez construire et ce qu'il vous faut

Objectif : envoyer un prompt texte à POST /v1/tasks, attendre la fin de la tâche, puis télécharger une image dont le texte est rendu comme vous l'avez demandé.

Vous n'avez besoin que d'une seule chose : une clé API hiapi — créez-en une dans la console. Elle est utilisée comme token Bearer dans chaque requête. Il n'existe pas de niveau gratuit non authentifié ; tous les appels ci-dessous supposent l'usage de Authorization: Bearer sk-....

Comme tous les modèles sur hiapi, ideogram-v4 est asynchrone : vous créez une tâche, obtenez immédiatement un taskId, puis soit vous interrogez le résultat, soit vous recevez un callback. Il n'existe pas de mode synchrone « attendre 40 secondes sur une seule connexion HTTP » — et pour la génération d'images, vous n'en voudriez de toute façon pas.

Requête minimale : curl

Créer la tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "Une affiche de festival de jazz au style Art déco rétro. Le titre principal \"MIDNIGHT & BRASS\" en caractères gras dorés sur fond bleu marine profond, avec le sous-titre \"Live at the Riverside, Fridays\" en dessous dans une fine police sans empattement.",
      "rendering_speed": "BALANCED",
      "aspect_ratio": "3:4"
    }
  }'

La réponse revient immédiatement, avec l'id de tâche dans data.taskId (de la forme tk-hiapi-...). Interrogez-le :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
  -H "Authorization: Bearer $HIAPI_KEY"

Pendant la génération de l'image, data.status passe successivement par queued puis handling. À l'état terminal, il devient success ou fail. En cas de succès, l'URL de l'image se trouve dans data.output[0].url :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-XXXXXXXX",
    "status": "success",
    "output": [
      { "url": "https://.../result.png?...expireAt=..." }
    ]
  }
}

Un point à surveiller concernant cette URL : elle est signée et expirante (expireAt). Téléchargez les octets immédiatement après le succès de la tâche et enregistrez-les dans votre propre stockage. Ne stockez jamais de lien direct dans une base de données.

Les paramètres réellement acceptés par ideogram-v4

C'est la partie qui mérite d'être traitée avec précision. Si vous avez lu la documentation propre à Ideogram, vous savez que son API native expose des presets de style, un interrupteur de prompt magique, des prompts négatifs et un nombre d'images par lot. Le schéma de tâche ideogram-v4 de hiapi est délibérément plus restreint, et le validateur rejette tout ce qui sort du schéma. Voici la gamme complète confirmée par l'API en temps réel :

Champ	Requis	Type / valeurs
prompt	oui	string
rendering_speed	oui	"TURBO", "BALANCED", "QUALITY"
aspect_ratio	non	"1:1", "16:9", "4:3", "9:16", "3:4"
seed	non	entier

Les deux champs obligatoires sont validés strictement. Envoyer un input vide renvoie :

invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"

En cas de faute de frappe dans une valeur d'énumération, l'erreur vous indique les valeurs autorisées :

invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'

Et tout ce qui, dans l'interface native d'Ideogram, n'apparaît pas dans le tableau ci-dessus est rejeté comme propriété inconnue — style_type, magic_prompt, negative_prompt, num_images, size ainsi que les entrées d'image renvoient tous une erreur 400, par exemple :

invalid input: <root>: additional properties 'style_type' not allowed

Conséquences pratiques :

• Le contrôle typographique repose entièrement sur le prompt. Placez le texte exact que vous voulez rendre entre guillemets doubles dans le prompt, et décrivez la police (« police Art déco grasse », « sans empattement géométrique fine », « lettrage d'enseigne dessiné à la main »). C'est ainsi que l'on obtient l'effet affiche/logo/enseigne qui a fait la réputation d'Ideogram — il n'existe aucun paramètre de style distinct sur lequel compter.
• Une image par tâche. Pas de n ni de num_images. Si vous voulez quatre candidats, soumettez quatre tâches et interrogez chaque taskId séparément.
• seed est votre levier de reproductibilité. Un prompt identique + un seed identique vous donnent un point de départ stable, pratique pour itérer sur la formulation.
• Texte-vers-image uniquement. Le schéma du modèle n'accepte pas d'image de référence. Si votre flux de travail nécessite de l'image-vers-image, choisissez un modèle qui le prend en charge — voir comment appeler plusieurs modèles d'image avec une seule clé API, pour changer de modèle sans modifier votre code d'intégration.

À propos de rendering_speed : TURBO est le niveau rapide, idéal pour ébaucher pendant que vous itérez sur la formulation du prompt ; QUALITY est le niveau lent et soigné, adapté au rendu final ; BALANCED est une valeur par défaut raisonnable. La tarification est facturée à l'usage, par image — consultez la page de tarifs pour les prix actuels.

Le script Python complet

Le même flux — créer, interroger, télécharger — avec des délais d'attente et la gestion des états terminaux. La seule dépendance est requests (pip install requests).

import os
import time
import requests

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

def create_task(prompt: str, rendering_speed: str = "BALANCED",
                aspect_ratio: str = "1:1", seed: int | None = None) -> str:
    input_obj = {
        "prompt": prompt,
        "rendering_speed": rendering_speed,
        "aspect_ratio": aspect_ratio,
    }
    if seed is not None:
        input_obj["seed"] = seed
    resp = requests.post(API_BASE, headers=HEADERS,
                         json={"model": "ideogram-v4", "input": input_obj},
                         timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt=('Conçois un logo minimaliste pour une marque de café nommée "Driftwood", '
                'le mot Driftwood en logotype dans une police à empattements chaleureuse, monochrome, '
                'fond crème'),
        rendering_speed="QUALITY",
        aspect_ratio="1:1",
        seed=42,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    png = requests.get(url, timeout=120).content   # l'URL signée expire - télécharger immédiatement
    with open("driftwood-logo.png", "wb") as f:
        f.write(png)
    print("saved driftwood-logo.png,", len(png), "bytes")

Considérations de production : callbacks, idempotence et erreurs

Interrogation vs. callback. Pour un outil interactif générant une image à la fois, l'interrogation toutes les quelques secondes est plus simple et largement suffisante. Pour des charges de travail par lots ou côté serveur, ajoutez un callback à la requête de création pour que hiapi vous envoie le résultat terminal par POST :

{
  "model": "ideogram-v4",
  "input": { "prompt": "...", "rendering_speed": "BALANCED" },
  "callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}

Deux contraintes, toutes deux appliquées au moment de la création : l'URL doit être en https:// et accessible publiquement, et when n'accepte que "final" — si vous essayez une autre valeur, l'API renvoie directement invalid callback.when: only 'final' is supported. Rendez votre gestionnaire idempotent sur le taskId, retournez rapidement un 2xx, et conservez une solution de secours par interrogation pour les tâches dont le callback n'arrive jamais. Si un callback n'arrive pas, commencez par diagnostiquer selon pourquoi le callback de votre tâche hiapi ne se déclenche pas, avant de blâmer la file d'attente.

Idempotence. La création de tâche n'est pas idempotente — chaque POST /v1/tasks réussi correspond à une nouvelle tâche et à une nouvelle facturation. Dès réception du taskId, stockez-le immédiatement en le reliant à votre propre id de tâche ; toute nouvelle tentative ultérieure doit interroger le taskId stocké plutôt que resoumettre.

Les erreurs que vous verrez réellement.

• 401 avec "code": "permission_denied" — clé invalide ou ne pouvant pas utiliser ce modèle. Le message le dit explicitement : « This API key cannot use the selected model. Please check permissions or use another key. » Corrigez-le dans la console, ne réessayez pas.
• 400 avec "error_code": "INVALID_REQUEST" — échec de validation. Le message indique le champ précis et les valeurs autorisées ; lisez-le et corrigez le corps de la requête. Réessayer avec le même corps échouera toujours.
• 404 "task not found" sur GET /v1/tasks/{id} — id de tâche erroné, ou tâche créée avec une autre clé.
• État fail pour une tâche déjà acceptée — vérifiez data.error.code / data.error.message dans la réponse d'interrogation. Ces cas peuvent être réessayés sans risque comme nouvelle tâche.

Lectures associées

• Page du modèle ideogram-v4 — capacités et niveaux tarifaires actuels
• Pourquoi le callback de votre tâche hiapi ne se déclenche pas — liste de vérification pour le débogage des callbacks
• Comment appeler plusieurs modèles d'image avec une seule clé API — même API de tâches, chaîne model différente
• L'API de génération d'images la moins chère — comment comparer le coût réel par image entre modèles
• Documentation API — référence complète POST /v1/tasks / GET /v1/tasks/{id}

FAQ

ideogram-v4 sur hiapi prend-il en charge l'image-vers-image ou les images de référence ? Non. Le schéma de tâche de ce modèle n'accepte que prompt, rendering_speed, aspect_ratio et seed — tout champ d'entrée d'image est rejeté avec une 400. Si vous devez modifier ou repeindre une image existante, utilisez un modèle prenant en charge l'image-vers-image (par exemple la série gpt-image-2).

Quel rendering_speed dois-je utiliser ? Itérez avec TURBO pendant que vous affinez le prompt et la formulation exacte du texte, puis relancez le rendu de la version retenue avec QUALITY et le même seed. Si vous ne faites qu'un seul rendu, BALANCED est une bonne valeur par défaut.

Comment faire rendre un texte exact par ideogram-v4 ? Placez le texte littéral entre guillemets doubles dans le prompt, et décrivez la typographie autour : titre principal "SUMMER SALE", en sans empattement condensée très grasse. Les chaînes courtes se rendent plus fiablement que les phrases complètes ; si une longue ligne sort de travers, découpez-la en titre principal et sous-titre.

Peut-on générer plusieurs images dans une seule requête ? Non — une tâche génère une image. Soumettez plutôt plusieurs tâches en parallèle ; chacune a son propre taskId et est mise en file indépendamment.

Pourquoi ma clé renvoie-t-elle 401 permission_denied alors qu'elle fonctionne avec d'autres modèles ? Les accès aux modèles sont configurés par clé. Vérifiez les permissions de modèle de cette clé dans la console, ou créez une nouvelle clé ayant accès à ideogram-v4.

Combien de temps l'URL de sortie est-elle valide ? C'est une URL signée avec un horodatage expireAt. Considérez-la comme valable en minutes, pas en jours : téléchargez l'image dès que la tâche atteint success et conservez le fichier vous-même.

Quels ratios d'aspect sont disponibles ? Exactement cinq : 1:1, 16:9, 4:3, 9:16 et 3:4. Pas de paramètre size libre — une requête avec size est rejetée comme propriété inconnue.