Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

Verrouiller le même personnage à partir de l'image de référence, maintenir la cohérence du visage et des vêtements à travers les changements de scène, de pose et d'éclairage, et prolonger l'avantage de mise en page typographique intégrée à l'image d'Ideogram

ideogram-v3-character ideogram-v3-character/edit

Essayer ideogram-v3-character/edit

Entrée

Créations

Voir toutes les créations

Sortie

image

Renseignez les paramètres et générez : les résultats s'afficheront ici.

Tarifs

ideogram-v3-character/edit per image

Spécifications	Prix unitaire
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

Présentation

ideogram-v3-character/edit est un modèle d'image dédié à l'édition avec cohérence de personnage : téléchargez une image source et un masque, désignez la zone à repeindre, puis utilisez exactement une image de référence de personnage comme point d'ancrage visuel pour réécrire une partie de l'image tout en préservant le visage, la coiffure, les vêtements et la silhouette. Il convient aux développeurs qui doivent réutiliser un même personnage, une mascotte ou un avatar dans une série de contenus, en particulier pour les productions en série où l'apparence du personnage reste uniforme tandis que les scènes et les textes varient.

Points clés

Repentir localisé ancré sur le personnage — l'image source et le masque définissent la zone d'édition, l'image de référence verrouille l'identité du personnage : on change la scène sans changer le visage.
Scène variable, apparence constante — le prompt permet de remplacer la pose, l'éclairage et l'arrière-plan, tandis que les traits essentiels du personnage restent contraints par l'image de référence.
Production en série reproductible — prise en charge d'une graine aléatoire fixe, avec des niveaux de style et de vitesse de rendu, pour reproduire fidèlement une série de contenus.

Capacités

Édition ciblée par masque : fournissez une image source et un masque de même rapport largeur-hauteur ; seule la zone couverte par le masque est repeinte, le reste de l'image reste inchangé, ce qui convient au remplacement d'arrière-plans ou d'éléments locaux.

Verrouillage du personnage par une seule image de référence : une seule image de référence (JPEG, PNG ou WebP, 10 Mo maximum) suffit pour contraindre les traits physiques du personnage dans le résultat repeint.

Scène pilotée par prompt : un prompt de 5 000 caractères maximum décrit la scène cible, avec possibilité d'activer l'extension de prompt pour compléter automatiquement les détails.

Niveaux de style et de vitesse : style au choix parmi AUTO, REALISTIC, FICTION ; vitesse de rendu en TURBO, BALANCED, QUALITY, le niveau déterminant le degré de détail.

Cas d'usage

Itération en série de contenus de personnage — les équipes marketing et design utilisent une même image de référence avec différents masques pour produire en série des illustrations multi-scènes d'un même personnage, destinées aux réseaux sociaux et aux pages d'événement.
Changement local de décor pour affiches et visuels promotionnels — remplacer l'arrière-plan et l'éclairage tout en conservant le sujet principal, pour obtenir des visuels promotionnels directement diffusables et des supports avec mise en page typographique.
Cohérence de personnage en bande dessinée et storyboard — l'auteur repeint les poses et les scènes des cases à partir d'une image de référence de référence, produisant des images successives cohérentes pour le storyboard.

Limites et conseils de choix

La cohérence de personnage n'est pas absolue : des scènes complexes ou des poses et expressions extrêmes peuvent encore produire des écarts visibles ; l'image de référence doit présenter un visage net, un bon éclairage et peu d'occlusions, faute de quoi le résultat se dégrade. Le masque et l'image source doivent conserver le même rapport largeur-hauteur, et une seule image de référence est acceptée. Si la tâche consiste à générer une création indépendante unique sans verrouiller un même personnage, il vaut mieux passer par la génération texte-image ; les niveaux de détail QUALITY et supérieurs allongent le temps de génération, il faut donc arbitrer entre vitesse et qualité.

Nouveautés

Voir le journal des modifications →

Nouveau modèle Ajout de la génération cohérente de personnage ideogram-v3-character et de ideogram-v3-character/edit… Oct 17, 2026

Questions fréquentes

Voir toutes les questions →

Quelles sont les exigences pour le masque ?

Le masque doit avoir le même rapport largeur-hauteur que l'image originale ; les zones noires seront redessinées et les parties blanches conservées. Une zone légèrement plus grande que la silhouette du personnage donne un résultat plus naturel.
Quelle est la taille de sortie ?

La sortie conserve les dimensions de l'image d'origine ; par exemple, une image d'origine de 1024×768 donne un résultat de 1024×768.
Puis-je remplacer un personnage déjà présent dans l'image d'origine ?

Oui, peignez le personnage à remplacer dans le masque et décrivez l'action du nouveau personnage dans le prompt ; les personnages et l'arrière-plan en dehors du masque seront conservés.
Quel format utiliser pour le masque ?

Utilisez une image ayant le même rapport largeur/hauteur que l'image d'origine, avec la zone à repeindre peinte en noir sur fond blanc ; les exemples de cette page utilisent un masque PNG.

Créer une tâche de génération

POST https://api.hiapi.ai/v1/tasks

En-têtes

AuthorizationstringRequis

Clé API du compte. Requise sur chaque requête. Exemple : Bearer YOUR_HIAPI_API_KEY. Obtenir une clé API

Content-TypestringOptionnel

Le corps de la requête est toujours analysé en JSON ; s'il est envoyé, seul application/json (charset facultatif) est accepté — toute autre valeur renvoie 415. Exemple : application/json.

Idempotency-KeystringOptionnel

Clé d'idempotence, jusqu'à 255 octets. Les reprises avec la même clé du même compte ne créent la tâche qu'une seule fois ; les rejeux renvoient le taskId d'origine.

Clé d'idempotence

En cas de timeout réseau ou de relance automatique du client, la même clé ne crée la tâche qu'une seule fois, sans double facturation (portée = le compte de la clé API). Utilisez un identifiant métier unique (ex. "order-42") ; les rejeux renvoient le taskId d'origine et les clés expirent 24 h après la première requête. La matrice complète des scénarios est dans la présentation de l'API asynchrone unifiée.

Corps

modelstringRequis

Valeur fixe actuelle : ideogram-v3-character/edit

routestringOptionnel

Valeur fixe actuelle : default

inputobjectRequis

Objet de paramètres métier pour ideogram-v3-character/edit et la route default — voir le tableau des paramètres ci-dessous.

seedintegerOptionnelmin 0max 2147483647

Graine aléatoire de type entier, utilisée pour rendre reproductibles les résultats de génération d'un même prompt ; la valeur se présente sous forme d'entier.

stylestringOptionnelDéfaut: "AUTO"

Spécifie le type de style utilisé pour la génération, AUTO par défaut.

Options：AUTOREALISTICFICTION

promptstringRequisminLength 1maxLength 5000

Décrit la scène dans laquelle se trouve le personnage de référence, c'est-à-dire le contenu de l'image à générer lors de cette édition, 5000 caractères maximum.

mask_urlstringRequisminLength 1pattern ^https?://

URL de l'image de masque spécifiant la zone à repeindre ; le masque doit conserver le même rapport largeur-hauteur que l'image source.

image_urlstringRequisminLength 1pattern ^https?://

URL de l'image source à éditer ; cette image doit conserver le même rapport largeur-hauteur que le masque.

expand_promptbooleanOptionnelDéfaut: true

Interrupteur booléen contrôlant l'utilisation de MagicPrompt pour l'extension automatique du prompt, true par défaut.

rendering_speedstringOptionnelDéfaut: "BALANCED"

Spécifie le niveau de vitesse de rendu ; TURBO est le plus rapide et le moins cher, QUALITY offre le plus de détails, les différents niveaux ont des tarifs différents ; BALANCED par défaut.

Options：TURBOBALANCEDQUALITY

reference_image_urlsarrayRequisminItems 1maxItems 1

Tableau d'images de référence du personnage, nécessitant exactement une image de référence du personnage, aux formats JPEG, PNG ou WebP, 10 Mo maximum par image.

Array [ string ]

callbackobjectOptionnel

Configuration de notification d'état terminal. Sans elle, aucun callback — interrogez la tâche vous-même.

Rappels (Webhook)

Fournissez callback.url à la création et HiAPI envoie un POST à votre service à l'état terminal — plus besoin de polling. Le corps du rappel reprend la structure du détail de tâche ; vérification de signature, relances et idempotence sont décrits dans la présentation de l'API asynchrone unifiée.

urlstringRequis

Obligatoire si callback est présent. Un POST est envoyé vers cette URL à l'état terminal ; doit être une URL http(s) valide.

whenstringOptionnelDéfaut: "final"

Seul final est pris en charge pour l'instant — notifié sur success et fail.

Options：final

storagestringOptionnelDéfaut: "temp"

Niveau de stockage des artefacts : temp (par défaut, ~7 jours) ou persistent (long terme, facturé au volume). Solde insuffisant ou dépassement de limite ⇒ rétrogradation silencieuse en temp ; le niveau effectif figure dans la réponse de détail.

Options：temppersistent

Exemples de requête

# Soumet une tâche asynchrone ; renvoie immédiatement un taskId (n'attend pas la génération)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "mask_url": "…",
    "image_url": "…",
    "expand_prompt": true,
    "rendering_speed": "BALANCED",
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ideogram-v3-character/edit",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "mask_url": "…",
      "image_url": "…",
      "expand_prompt": true,
      "rendering_speed": "BALANCED",
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ideogram-v3-character/edit",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "mask_url": "…",
          "image_url": "…",
          "expand_prompt": True,
          "rendering_speed": "BALANCED",
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obtenir le détail de la tâche

GET https://api.hiapi.ai/v1/tasks/:id

Champs de réponse

taskIdstringRequis

Identifiant de tâche, toujours préfixé tk-hiapi-.

modelstringRequis

Nom complet résolu du modèle. Les tâches envoyées avec le paramètre route renvoient base@route (ex. gpt-image-2/text-to-image@ext) ; sinon identique au nom fourni.

routestringOptionnel

Présent uniquement si le paramètre route explicite a été utilisé ; renvoie la valeur soumise.

statusstringRequis

Statut de la tâche.

Valeurs de statut

queued En file, pas encore démarrée. handling En cours de traitement. archiving Traitement terminé, préparation des artefacts. success Terminal : terminé, artefacts disponibles (output renvoyé). fail Terminal : échec (error renvoyé). Après soumission, suivez status : success et fail sont terminaux, le reste non terminal. Interrogez toutes les 1–3 s jusqu'à l'état terminal. En cas de succès, téléchargez les artefacts via output[].url et transférez-les avant expireAt ; pour une conservation longue durée, indiquez storage: "persistent" à la création.

creatednumberRequis

Date de création de la tâche (secondes Unix).

completednumberRequis

Secondes Unix de l'état terminal ; 0 tant que non terminal.

outputarrayOptionnel

Présent uniquement si status == success. Liste d'artefacts — toujours un tableau ; une tâche peut renvoyer plusieurs types à la fois (ex. video + first_frame).

Array [ object ]

Éléments du tableau

urlstringRequis

URL de l'artefact, téléchargeable directement.

typestringRequis

Valeurs possibles actuelles : video, image, audio, first_frame, last_frame, thumbnail ; d'autres pourront s'ajouter.

expireAtnumberRequis

Secondes Unix de disponibilité de l'artefact ; téléchargez ou transférez avant l'expiration.

errorobjectOptionnel

Présent uniquement si status == fail.

codestringRequis

Code d'erreur métier.

messagestringRequis

Description de l'erreur.

Exemples de réponse

Succès

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

En cours (non terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Échec

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}