Comment utiliser ideogram-v3-character via l'API HiAPI : guide curl + Python

Qu'est-ce qu'ideogram-v3-character et quand l'utiliser

ideogram-v3-character est un modèle de génération d'images sur HiAPI spécialisé dans la cohérence de personnage. Il ne traite pas chaque génération comme une invite indépendante ; il permet de fournir une image de référence du personnage afin que les rendus suivants conservent le même visage, les mêmes vêtements et la même identité globale.

Utilisez-le lorsque qui et quoi ont la même importance :

• Storyboards et bandes dessinées : le même personnage apparaît dans plusieurs cases.
• Variantes d'assets de jeu : générer différentes poses, expressions ou tenues pour un personnage principal.
• Mascottes de marque : doivent rester identiques dans de nombreuses scènes et arrière-plans différents.
• Direction artistique itérative : affiner un personnage au fil de plusieurs passes sans perdre la ressemblance.

Si vous avez seulement besoin d'une illustration ponctuelle et que peu importe la correspondance avec des images précédentes, un modèle texte-vers-image généraliste est plus simple. La structure supplémentaire apportée par l'image de référence est précisément ce qui justifie le champ de requête en plus d'ideogram-v3-character.

Ce modèle, comme les autres, est exposé via le point de terminaison unifié de génération d'images de HiAPI, si bien que la structure de requête vous semblera familière : vous envoyez une charge utile JSON, recevez une référence de tâche asynchrone et interrogez jusqu'à ce que le résultat soit prêt. Ce tutoriel se concentre sur la bonne exécution de ce flux.

Avant d'envoyer la requête : configuration et authentification

Avant le premier appel, il vous suffit de préparer quelques éléments.

1. Clé d'API

Créez une clé d'API dans le tableau de bord de votre compte HiAPI. Traitez-la comme un secret : elle autorise chacune de vos requêtes et est facturée sur votre compte.

2. Gestion des identifiants via des variables d'environnement

Ne codez jamais la clé en dur dans un fichier source et ne la validez pas dans git. Utilisez plutôt des variables d'environnement :

export HIAPI_API_KEY="your_api_key_here"

En Python, vous pouvez la lire ainsi :

import os
api_key = os.environ["HIAPI_API_KEY"]

Si vous utilisez un fichier .env en développement local, ajoutez-le à .gitignore avant toute autre chose.

3. URL de l'image de référence

Comme la cohérence de personnage repose sur une image de référence, préparez une image accessible via une URL. Assurez-vous que cette URL est accessible publiquement ou autrement accessible à l'API — un lien privé derrière une authentification échouera. Une image carrée ou verticale montrant clairement le visage du personnage fonctionne le mieux.

4. Moyen d'effectuer des requêtes HTTP

curl en ligne de commande, ou un environnement Python avec requests installé, l'un ou l'autre suffit. Les exemples ci-dessous supposent que vous disposez de l'un des deux.

Une fois ces quatre éléments prêts, vous pouvez envoyer votre première requête.

Analyse ligne par ligne d'une requête curl fonctionnelle

Voici une requête complète soumettant une tâche ideogram-v3-character à HiAPI. Remplacez les espaces réservés par vos propres valeurs.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "un mécanicien robot amical debout dans un atelier ensoleillé, tenant une clé à molette, vue de trois quarts",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

Rôle de chaque partie

• POST /v1/images/generations — point de terminaison unifié de génération d'images de HiAPI. Tous les modèles passent par le même chemin.
• Authorization: Bearer $HIAPI_API_KEY — authentifie l'appel. Le shell développe la variable d'environnement que vous avez définie précédemment.
• Content-Type: application/json — vous envoyez un corps JSON, il faut donc le déclarer.
• model — sélectionne ideogram-v3-character. Sans cela, la requête ne sait pas vers quel modèle router.
• prompt — description de la scène. Décrivez la pose, l'environnement, l'éclairage et l'ambiance ; confiez l'identité du personnage à l'image de référence.
• reference_images — tableau d'URL d'images. Pour un seul personnage, une seule entrée suffit généralement.
• aspect_ratio — forme de sortie. Faites-la correspondre à l'usage prévu (carré, vertical, etc.).
• num_images — nombre de variantes générées par tâche.

Une soumission réussie renvoie un corps JSON contenant l'identifiant de la tâche. Notez cette valeur — l'étape d'interrogation en aura besoin. La réponse peut aussi contenir un champ de statut indiquant que la tâche est en file d'attente ou en cours de traitement. Si le statut est déjà final, le résultat peut être inclus directement dans la réponse ; sinon, continuez à interroger.

La même requête en Python

Voici exactement le même appel en Python. Il lit la clé depuis une variable d'environnement, envoie la requête et affiche la référence de la tâche.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "un mécanicien robot amical debout dans un atelier ensoleillé, tenant une clé à molette, vue de trois quarts",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Remarques sur la version Python

• timeout=60 empêche le script de rester bloqué indéfiniment en cas de mauvaise connexion réseau.
• raise_for_status() transforme les réponses non 2xx en exceptions, vous remarquez ainsi immédiatement les problèmes d'authentification et de validation.
• Extraction de l'ID de tâche — HiAPI renvoie l'identifiant de tâche dans le corps de la réponse. Selon la structure de la réponse, il peut se trouver sous id ou job_id ; l'exemple vérifie les deux, mais vous devriez d'abord examiner une vraie réponse, puis coder en dur le nom de champ correct pour plus de clarté.

La charge utile est délibérément identique à l'exemple curl. Copier le corps JSON de l'un à l'autre est une bonne vérification de cohérence lors du débogage : si l'un fonctionne et pas l'autre, le problème vient de la couche de transport, pas du modèle.

Gestion des images de référence pour la cohérence de personnage

Les images de référence sont précisément ce qui distingue ideogram-v3-character des modèles texte-vers-image ordinaires. Bien les gérer, c'est faire la moitié du travail.

Comment fournir les images de référence

Le champ reference_images est un tableau d'URL. Chaque URL doit pointer vers une image que l'API peut récupérer directement. Si vous stockez du contenu téléversé par les utilisateurs, servez-le depuis un bucket ou un CDN autorisant les requêtes GET non authentifiées, ou générez une URL signée valable pendant l'exécution de la tâche.

Conseils pour des images de référence qui assurent vraiment la cohérence

• Une seule personne par image de référence. Les photos de groupe rendent difficile de savoir quel visage conserver.
• Visage net, bien éclairé. Évitez les ombres marquées, les angles extrêmes et les occultations.
• Pose neutre ou caractéristique. La vue de face ou de trois quarts préserve le mieux les traits d'identité.
• Si vous souhaitez conserver les vêtements, les vêtements de l'image de référence doivent être cohérents — le modèle reproduit ce qu'il voit.
• La résolution compte, mais sans excès. Une image de taille raisonnable avec un visage net vaut mieux qu'une image énorme et floue.

Garder le personnage reconnaissable au fil des générations

Lorsque vous générez une deuxième scène pour le même personnage, réutilisez la même image de référence, et non la sortie générée précédemment. Enchaîner des images générées peut accumuler de légères dérives. Si vous avez besoin d'une nouvelle référence — par exemple une tenue différente — générez-la une fois, vérifiez-la, puis réutilisez ce fichier comme nouvelle référence pour les tâches suivantes.

Vérifier la cohérence

Générez deux ou trois variantes de poses différentes pour le même personnage et comparez-les côte à côte. Si le visage ou les vêtements dérivent, la cause est généralement une image de référence faible ou ambiguë. Avant de modifier l'invite, resserrez l'image de référence.

Tâches asynchrones : soumettre, interroger et récupérer les résultats

La génération d'images prend du temps, c'est pourquoi HiAPI la traite de manière asynchrone. Le schéma est toujours le même : soumettre, capturer l'ID de tâche, interroger jusqu'à ce que la tâche atteigne un état final, puis lire l'URL de sortie.

Cycle de vie d'une tâche

1. Soumission — vous envoyez la requête des exemples précédents.
2. En file d'attente — la tâche est acceptée, en attente de capacité.
3. En cours de traitement — le modèle effectue le rendu.
4. Terminée ou échouée — état final ; le résultat (ou l'erreur) est disponible.

Interrogation en Python

Après avoir capturé le job_id, interrogez le point de terminaison de la tâche :

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Récupérer les résultats

Une fois la tâche terminée, le corps de la réponse contient la sortie — généralement un tableau d'URL d'images ou une URL unique, plus des métadonnées. Téléchargez l'image depuis cette URL dès que possible ; certaines URL ont une durée limitée. Si vous avez besoin d'un stockage à long terme, copiez le fichier dans votre propre bucket dès que la tâche réussit.

Bonnes pratiques d'interrogation

• Retour arrière progressif. Un intervalle de deux secondes convient pour des tâches courtes ; si vous interrogez de nombreuses tâches, augmentez l'intervalle ou ajoutez du jitter.
• Limitez le nombre de tentatives. La protection max_attempts évite les boucles infinies et offre au code un chemin d'échec explicite.
• N'interrogez pas plus vite que nécessaire. Chaque interrogation est une requête ; marteler le point de terminaison ne fera pas terminer le rendu plus tôt.

Erreurs courantes et comment les diagnostiquer

En cas de problème, le chemin le plus rapide consiste généralement à isoler d'abord si le problème vient de votre requête, de l'image de référence ou de la tâche elle-même.

Échec d'authentification

401 signifie que la clé est absente, mal formée ou révoquée. Vérifiez que la variable d'environnement est réellement définie dans le shell ou le processus qui exécute la requête. Piège courant : définir la variable dans un terminal et exécuter le script dans un autre.

Erreurs de validation

400 pointe presque toujours vers la charge utile. Vérifiez :

• Que le champ model vaut exactement ideogram-v3-character.
• Que reference_images est un tableau, pas une chaîne.
• Que chaque URL du tableau est accessible publiquement.
• Que aspect_ratio utilise une valeur prise en charge.

En cas de doute, envoyez une charge utile minimale — uniquement model, prompt et reference_images — puis rajoutez les champs un par un.

Tâches qui ne se terminent jamais

Si l'interrogation dépasse la limite de tentatives, ne vous contentez pas de réessayer aveuglément. Vérifiez si la réponse de statut de la tâche contient un message. Les causes courantes sont une URL de référence inaccessible ou une file d'attente surchargée. Soumettez à nouveau une fois ; si cela bloque encore, simplifiez l'invite et l'image de référence.

Image de référence silencieusement ignorée

La tâche réussit, mais le personnage ne correspond pas. C'est généralement un problème d'image de référence, pas de code : l'URL peut renvoyer une page d'erreur, un PDF ou une image de remplacement. Récupérez vous-même cette URL dans un navigateur pour confirmer qu'elle renvoie bien l'image attendue avec le bon type de contenu.

Limites de débit

429 signifie que vous envoyez des requêtes trop rapidement. Utilisez un retour arrière exponentiel ; si vous générez par lots, étalez les soumissions au lieu de tout envoyer d'un coup.

Liste de vérification rapide

• La clé est-elle définie dans le bon environnement ?
• L'URL de référence est-elle accessible sans authentification ?
• Les noms des champs de la charge utile sont-ils correctement orthographiés ?
• L'interrogation est-elle limitée et soumise à un retour arrière ?
• La sortie est-elle téléchargée avant l'expiration de son URL ?

En parcourant cette liste dans l'ordre, la plupart des échecs se résolvent rapidement. Après une première exécution de bout en bout réussie, conservez-la comme exemple de référence fiable et comparez toute nouvelle requête à celle-ci. À mesure que vous passez à de nombreux personnages et scènes, cette seule habitude vous fera gagner du temps.