Comment utiliser l'API Ideogram 3.0 Character ? Créez votre première image de personnage en 5 minutes

TL;DR

• Ideogram 3.0 Character est un modèle de génération de personnage à partir d'une image de référence : téléchargez 1 image de référence de personnage, écrivez une phrase de prompt de scène, et le même visage et la même tenue apparaissent dans la nouvelle scène. Ouvrez la page du modèle pour l'essayer en ligne ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription.
• Le prix est facturé à l'image : TURBO 0,09 $, BALANCED 0,13 $, QUALITY 0,18 $. L'image de référence est gratuite, et aucun frais n'est débité en cas d'échec (voir la page tarifs).
• L'appel passe par l'endpoint HiAPI /v1/tasks : soumettez une tâche pour obtenir un taskId, puis utilisez-le pour interroger le résultat ; en cas de succès, téléchargez l'image depuis output[0].url.

Ce qu'il peut faire

• Génération cohérente de personnage : une image de référence verrouille le personnage, le visage et la tenue restent cohérents, et la scène peut être changée librement.
• Illustration comme rendu réaliste : style propose AUTO / REALISTIC / FICTION, adapté aux personnages photographiques comme illustrés.
• Format d'image selon la référence : une référence verticale produit du 3:4 (864×1152), une référence horizontale du 16:9 (1328×752), sans paramètre de dimensions à renseigner.
• Endpoint d'édition associé : ideogram-v3-character/edit utilise un masque pour intégrer le personnage dans une zone précise d'une image existante, sans toucher au reste.

Voici un résultat réel (image de référence : un personnage d'illustration horizontal) :

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(En français : ce personnage explorateur marche dans un marché nocturne éclairé de lanternes, tenant une barquette en papier de nouilles chaudes, avec des stands à lumière chaude des deux côtés, style illustration de livre jeunesse, sans texte, sans enseignes.)

ideogram-v3-character, TURBO, 16:9, 1328×752, 0,09 $.

Générer avec ce prompt →

Comment choisir entre les deux endpoints

	ideogram-v3-character	ideogram-v3-character/edit
Rôle	Générer une nouvelle scène de personnage à partir de zéro	Intégrer le personnage dans la zone masquée d'une image existante
Entrées obligatoires	prompt + 1 image de référence	prompt + image d'origine + masque + 1 image de référence
Prix (TURBO / BALANCED / QUALITY)	0,09 $ / 0,13 $ / 0,18 $	0,09 $ / 0,13 $ / 0,18 $
Sortie	WebP, format d'image selon la référence	WebP, dimensions selon l'image d'origine
Idéal pour	Affiches, séries, images de scènes en série	Remplacer ou ajouter un personnage sur une image finalisée

Convention du masque : noir = repeindre, blanc = conserver ; le masque et l'image d'origine doivent avoir le même ratio largeur/hauteur. L'endpoint d'édition n'accepte pas negative_prompt ; en transmettre renvoie une erreur 400.

Deux parcours de prise en main

Navigateur en 3 étapes : ouvrez la page du modèle → téléchargez l'image de référence du personnage, collez le prompt → cliquez sur générer, une image TURBO coûte 0,09 $.

API en 3 étapes : POST /v1/tasks pour soumettre → récupérez le taskId → GET /v1/tasks/<taskId> jusqu'au statut success, puis téléchargez.

curl : la première image

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Pour l'endpoint d'édition, remplacez model par ideogram-v3-character/edit et ajoutez image_url (image d'origine) et mask_url (masque) dans input :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Le taskId renvoyé sert de référence pour l'interrogation.

Python : soumettre, interroger, télécharger

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# Soumission : avec Idempotency-Key, une nouvelle tentative réseau ne crée pas de tâche en double
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Interrogation : queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # adresse temporaire, à télécharger rapidement
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Tableau des paramètres (ideogram-v3-character)

Champ	Obligatoire	Valeurs	Description
prompt	Oui	1–5000 caractères	Décrit la scène où le personnage doit apparaître, pas son apparence (l'apparence vient de l'image de référence)
reference_image_urls	Oui	Exactement 1 image, JPEG / PNG / WebP, ≤10 Mo	Image de référence du personnage ; son format détermine le format de sortie
rendering_speed	Non	TURBO / BALANCED / QUALITY, par défaut BALANCED	Détermine le niveau et le prix
style	Non	AUTO / REALISTIC / FICTION, par défaut AUTO	REALISTIC privilégie un rendu photographique, FICTION conserve l'aspect illustration
seed	Non	Entier 0–2147483647	Mêmes paramètres et même seed pour reproduire l'image
expand_prompt	Non	Par défaut true	Étend automatiquement le prompt ; mettez false pour appliquer strictement le texte d'origine
negative_prompt	Non	≤5000 caractères	Contenu à ne pas faire apparaître

L'endpoint d'édition ajoute deux champs obligatoires hors tableau, image_url et mask_url, et ne prend pas en charge negative_prompt. Tout champ hors tableau dans le corps de la requête renvoie directement une 400 (additional properties ... not allowed).

Erreurs que vous rencontrerez (messages bruts de l'API)

Ce que vous avez fait	Réponse
prompt non transmis	400 invalid input: prompt: missing required field "prompt"
2 images de référence transmises	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed mal orthographié	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Champ inconnu de l'API transmis	400 invalid input: <root>: additional properties 'foo' not allowed
negative_prompt transmis à l'endpoint d'édition	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Solde insuffisant	402 insufficient account balance; top up and retry

Une resoumission avec le même Idempotency-Key renvoie 409 (en cours de traitement) ou 422 (paramètres différents) ; changez de clé et réessayez.

À vérifier avant la mise en production

• Callback : transmettez "callback": {"url": "https://..."} au niveau racine du corps de la requête ; lorsque la tâche atteint un état final, votre service est notifié, ce qui évite l'interrogation répétée.
• Archivage rapide : output[0].url est une adresse temporaire ; téléchargez-la dès réception et stockez-la dans votre propre stockage, ne l'utilisez pas comme lien permanent.
• Indiquez explicitement le niveau et le format : transmettez toujours rendering_speed de manière explicite (sinon la facturation se fait en BALANCED) ; le format de sortie dépend de l'image de référence, prévoyez donc une référence verticale pour une scène verticale.
• Une clé d'idempotence par tâche en lot : chaque soumission porte un Idempotency-Key unique ; une nouvelle tentative réseau avec la même clé ne touche que la même tâche, sans créer de doublons ni débiter à nouveau des crédits.

Questions fréquentes

L'image de référence peut-elle être une URL ?

Oui. Il suffit d'une adresse http/https accessible, en JPEG, PNG ou WebP, 10 Mo maximum.

Combien d'images de référence peut-on transmettre ?

Exactement 1 : c'est une règle stricte, en transmettre deux renvoie directement une 400 ; pour changer de personnage, changez l'image de référence.

Faut-il transmettre un paramètre de dimensions ?

Non. Le format de sortie suit l'image de référence : une référence verticale produit du 864×1152, une référence horizontale du 1328×752.

Les deux endpoints s'appellent-ils de la même façon ?

Oui. Seuls model et les champs de input changent.

Un échec est-il facturé ?

Non, les crédits prélevés sont intégralement remboursés après un état final d'échec.

Étape suivante : reprenez le prompt du marché nocturne ci-dessus pour essayer une image sur la page du modèle, puis choisissez vos prompts selon la scène dans le guide complet des prompts ; les trois niveaux de prix et le tableau budgétaire figurent sur la page tarifs.