Ideogram

Ideogram V3 Character

ideogram-v3-character

Mit dem Referenzbild dieselbe Figur festlegen, Gesicht und Kleidung über Szenen-, Posen- und Beleuchtungswechsel hinweg konsistent halten und die Stärke von Ideogram bei der Textgestaltung im Bild fortsetzen

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

ideogram-v3-character ausprobieren

Eingabe

Expand Prompt

Galerie

Alle Arbeiten ansehen

Ausgabe

image

Fülle die Parameter aus und generiere – die Ergebnisse erscheinen hier.

Preise

ideogram-v3-character per image

Spezifikationen	Einzelpreis
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

Einordnung

ideogram-v3-character ist ein Bildgenerierungsmodell, das ein Referenzbild als visuellen Anker für eine Figur verwendet: Übergibt man ein klares Foto einer Figur, bleiben Gesichtszüge, Frisur, Kleidung und Körperproportionen der Person über mehrere Generierungen hinweg erhalten, während Szenen, Posen, Beleuchtung und Hintergrund per Prompt geändert werden können. Es eignet sich für Entwickler und Kreativteams, die dieselbe Figur in Comic-Panels, Social-Media-Serienillustrationen oder Markenmaskottchen-Erweiterungen wiederverwenden möchten, und führt Ideograms Stärke beim Textlayout innerhalb des Bildes fort.

Hauptmerkmale

Figur mit einem einzigen Referenzbild fixieren – Es genügt ein JPEG-, PNG- oder WebP-Bild der Figur als Eingabe, und das Modell verwendet es als visuellen Anker, um das Erscheinungsbild der Person konsistent zu halten.
Szene wechseln, Figur behalten – Während das Aussehen der Figur fixiert bleibt, lassen sich Szene, Pose, Beleuchtung und Hintergrund per Prompt deutlich anpassen.
Reproduzierbare Parametersteuerung – Unterstützt seed, Negative Prompts und Rendergeschwindigkeitsstufen, was stabile Ergebnisse bei der Batch-Generierung sowie die bedarfsgerechte Anpassung von Details und Tempo ermöglicht.

Fähigkeiten

Figurenkonsistenz über Referenzbild: Wird ein Referenzbild einer Figur als Eingabe verwendet, bewahren die Ergebnisse Gesicht, Frisur, Kleidung und Körperproportionen – ideal für Serieninhalte, die dieselbe Figur über mehrere Bilder hinweg wiederverwenden.

Prompt-gesteuerte Szenenwechsel: Bei fixierter Figur beschreibt ein Prompt mit bis zu 5000 Zeichen die neue Szene und Pose; unerwünschte Elemente lassen sich durch Negative Prompts ausschließen.

Reproduzierbare Generierung: Ein zufälliger Seed kann festgelegt werden, um dasselbe Ergebnis beim Debugging oder in der Serienproduktion zu wiederholen und den Auswahlaufwand zu senken.

Wahl der Renderstufe: Drei Rendergeschwindigkeitsstufen – TURBO, BALANCED und QUALITY – ermöglichen Entwicklern, je nach Ausgabetempo und Detailanforderung zwischen Geschwindigkeit und Qualität abzuwägen.

Anwendungsfälle

Comic- und Storyboard-Autoren: fortlaufende Bilder derselben Figur – Eine Charakter-Referenzaufnahme plus Beschreibung einer einzelnen Panel-Szene eingeben und ein konsistentes Storyboard-Bild erzeugen, das direkt in Layout und Postproduktion übergeht.
Social-Media-Management: einheitliches Figurenbild für Serieninhalte – Mit einem festen Charakter-Referenzbild verschiedene thematische Illustrationen in Serie generieren, damit die visuelle Hauptfigur über mehrere Ausgaben hinweg gleich bleibt.
Markenteams: Maskottchen über verschiedene Szenen hinweg erweitern – Mit einem Maskottchen-Bild Erweiterungsmaterial für verschiedene Events, Jahreszeiten oder Postermotive erzeugen, das für Marketingmaßnahmen eingesetzt wird.

Einschränkungen und Auswahlhinweise

Die Figurenkonsistenz ist nicht absolut: Bei komplexen Szenen, übertriebenen Posen und wechselnden Gesichtsausdrücken können Gesicht und Details sichtbare Abweichungen aufweisen. Die Qualität des Referenzbildes beeinflusst das Ergebnis direkt; empfohlen werden Figurenbilder mit klarem Gesicht, gleichmäßiger Beleuchtung und wenigen Verdeckungen. Wird nur ein einzelnes, unabhängiges Kreativbild ohne feste Figur benötigt, ist ein reguläres Text-zu-Bild-Modell besser geeignet. Bei kommerziellen Projekten mit sehr hohen Anforderungen an die Figurentreue empfiehlt es sich, die Konsistenz zunächst mit wenigen Stichproben zu prüfen und erst dann in Serie zu generieren.

Neuigkeiten

Changelog ansehen →

Neues Modell Neu: ideogram-v3-character zur konsistenten Charaktergenerierung und ideogram-v3-character/edit… Oct 17, 2026

Häufige Fragen

Alle Fragen ansehen →

Welche Anforderungen gelten für die Maske?

Die Maske muss dasselbe Seitenverhältnis wie das Originalbild haben, schwarze Bereiche werden neu gezeichnet, weiße Bereiche bleiben erhalten. Ist der Bereich etwas größer als die Kontur der Figur, wirkt es natürlicher.
Wie groß ist die Ausgabegröße?

Die Ausgabe entspricht der Größe des Originalbilds; ein Originalbild mit beispielsweise 1024×768 ergibt ein Ergebnis mit 1024×768.
Können Personen im Originalbild ersetzt werden?

Ja, malen Sie die zu ersetzende Person in die Maske ein und beschreiben Sie die Aktion der neuen Figur im Prompt; Personen und Hintergrund außerhalb der Maske bleiben erhalten.
In welchem Format wird die Maske verwendet?

Verwenden Sie ein Bild mit demselben Seitenverhältnis wie das Originalbild und malen Sie den zu übermalenden Bereich auf weißem Hintergrund schwarz aus; das Beispiel auf dieser Seite verwendet eine PNG-Maske.

Generierungsaufgabe erstellen

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

Header

AuthorizationstringPflicht

Account-API-Schlüssel. Bei jeder Anfrage erforderlich. Beispiel: Bearer YOUR_HIAPI_API_KEY. API-Schlüssel holen

Content-TypestringOptional

Der Anfragekörper wird immer als JSON geparst; beim Senden ist nur application/json (optional mit charset) zulässig — andere Werte liefern 415. Beispiel: application/json.

Idempotency-KeystringOptional

Idempotenz-Schlüssel, bis 255 Bytes. Wiederholungen mit demselben Schlüssel desselben Kontos erstellen die Aufgabe nur einmal; Replays liefern die ursprüngliche taskId.

Idempotenz-Schlüssel

Bei Netzwerk-Timeouts oder Client-Wiederholungen erstellt derselbe Schlüssel die Aufgabe nur einmal — keine doppelte Abbuchung (Geltungsbereich = das Konto des API-Schlüssels). Empfohlen: geschäftsseitig eindeutige Kennung (z. B. "order-42"); Replays liefern die ursprüngliche taskId, Schlüssel laufen 24 Stunden nach der ersten Anfrage ab. Die vollständige Szenariomatrix steht in der Übersicht der Unified Async API.

Body

modelstringPflicht

Aktueller Festwert: ideogram-v3-character

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

Geschäftsparameter für ideogram-v3-character und Route default — siehe Parametertabelle unten.

seedintegerOptionalmin 0max 2147483647

Zufälliger Seed für reproduzierbare Generierungsergebnisse; der Wert ist eine Ganzzahl, gleicher Seed reproduziert gleiche Ausgabe.

stylestringOptionalStandard: "AUTO"

Stiltyp, steuert den Gesamtstil des generierten Bildes; Standard AUTO.

Optionen:AUTOREALISTICFICTION

promptstringPflichtminLength 1maxLength 5000

Szenen-Prompt zur Beschreibung der referenzierten Figur, maximale Länge 5000 Zeichen.

expand_promptbooleanOptionalStandard: true

Ob MagicPrompt zur Erweiterung des Prompts aktiviert wird; Standard true.

negative_promptstringOptionalmaxLength 5000

Negativ-Prompt, der angibt, welche Inhalte aus dem Bild ausgeschlossen werden sollen, maximale Länge 5000 Zeichen.

rendering_speedstringOptionalStandard: "BALANCED"

Stufe der Render-Geschwindigkeit: TURBO ist am schnellsten und günstigsten, QUALITY liefert die meisten Details, unterschiedliche Stufen werden unterschiedlich abgerechnet; Standard BALANCED.

Optionen:TURBOBALANCEDQUALITY

reference_image_urlsarrayPflichtminItems 1maxItems 1

Array von Referenzbildern der Figur, muss genau ein Referenzbild der Figur enthalten, unterstützt JPEG, PNG oder WebP, maximal 10 MB pro Bild.

Array [ string ]

callbackobjectOptional

Konfiguration der Endzustands-Benachrichtigung. Ohne Angabe wird kein Callback gesendet — selbst abfragen.

Callbacks (Webhook)

Beim Erstellen callback.url angeben, dann POSTet HiAPI im Endzustand an Ihren Service — kein Polling nötig. Der Callback-Body entspricht der Aufgaben-Detailstruktur; Signaturprüfung, Wiederholungen und Idempotenz sind in der Übersicht der Unified Async API beschrieben.

urlstringPflicht

Pflicht, wenn callback angegeben ist. Nach dem Endzustand wird an diese URL gepostet; muss eine gültige http(s)-URL sein.

whenstringOptionalStandard: "final"

Derzeit wird nur final unterstützt — Benachrichtigung bei success und fail.

Optionen:final

storagestringOptionalStandard: "temp"

Speicherstufe für Artefakte: temp (Standard, ca. 7 Tage) oder persistent (langfristig, nach Größe abgerechnet). Bei unzureichendem Guthaben oder Überschreitung des Speicherlimits erfolgt ein stiller Downgrade auf temp; die wirksame Stufe steht in der Aufgaben-Detailantwort.

Optionen:temppersistent

Anfragebeispiele

# Asynchrone Aufgabe senden; gibt sofort eine taskId zurück (wartet nicht auf die Generierung)
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",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "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",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "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",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "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"
}

Aufgabendetails abrufen

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

Antwortfelder

taskIdstringPflicht

Aufgaben-ID, stets mit Präfix tk-hiapi-.

modelstringPflicht

Aufgelöster vollständiger Modellname. Mit route-Parameter eingereichte Aufgaben geben base@route zurück (z. B. gpt-image-2/text-to-image@ext); sonst identisch mit dem übermittelten Namen.

routestringOptional

Erscheint nur bei explizitem route-Parameter; gibt den übermittelten Wert zurück.

statusstringPflicht

Aufgabenstatus.

Statuswerte

queued Eingereiht, noch nicht gestartet. handling In Verarbeitung. archiving Verarbeitung abgeschlossen, Artefakte werden vorbereitet. success Endzustand: abgeschlossen, Artefakte verfügbar (output wird zurückgegeben). fail Endzustand: fehlgeschlagen (error wird zurückgegeben). Nach dem Senden den status prüfen: success und fail sind Endzustände, alles andere nicht. Alle 1–3 Sekunden bis zum Endzustand pollen. Nach Erfolg Artefakte aus output[].url laden und vor expireAt übertragen; für Langzeitaufbewahrung storage: "persistent" beim Erstellen angeben.

creatednumberPflicht

Zeitpunkt der Aufgabenerstellung (Unix-Sekunden).

completednumberPflicht

Unix-Sekunden des Endzustands; vor Abschluss stets 0.

outputarrayOptional

Nur bei status == success. Artefaktliste — immer ein Array; eine Aufgabe kann mehrere Typen gleichzeitig liefern (z. B. video + first_frame).

Array [ object ]

Array-Elemente

urlstringPflicht

Artefakt-URL, direkt herunterladbar.

typestringPflicht

Aktuell mögliche Werte: video, image, audio, first_frame, last_frame, thumbnail; später können weitere folgen.

expireAtnumberPflicht

Unix-Sekunden, bis wann das Artefakt verfügbar ist; vorher herunterladen oder übertragen.

errorobjectOptional

Nur bei status == fail.

codestringPflicht

Business-Fehlercode.

messagestringPflicht

Fehlerbeschreibung.

Antwortbeispiele

Erfolg

{
  "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
      }
    ]
  }
}

In Bearbeitung (nicht final)

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

Fehlgeschlagen

{
  "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"
    }
  }
}