Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

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/edit ausprobieren

Eingabe

Galerie

Alle Arbeiten ansehen

Ausgabe

image

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

Preise

ideogram-v3-character/edit per image

Spezifikationen	Einzelpreis
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

Positionsübersicht

ideogram-v3-character/edit ist ein Bildmodell für konsistente Charakterbearbeitung: Lade ein Quellbild und eine Maske hoch, lege den Bereich fest, der neu gezeichnet werden soll, und verwende genau ein Charakterreferenzbild als visuellen Anker, um Teile des Bildes zu ändern, während Gesicht, Frisur, Kleidung und Körperbau erhalten bleiben. Geeignet für Entwickler, die dieselbe Person, dasselbe Maskottchen oder dieselbe virtuelle Figur wiederholt in Serienmaterialien einsetzen möchten, insbesondere für Massenproduktionsszenarien, in denen die Charaktererscheinung einheitlich bleiben soll, während Szene und Text variieren können.

Kernmerkmale

Lokales Neuzeichnen mit Charakterverankerung – Quellbild und Maske definieren den Bearbeitungsbereich, das Referenzbild fixiert die Charakteridentität: Szene ändern, ohne das Gesicht auszutauschen.
Variable Szene, unveränderte Erscheinung – Über Prompts lassen sich Pose, Beleuchtung und Hintergrund ersetzen, während die Kernmerkmale der Person weiterhin durch das Referenzbild bestimmt werden.
Reproduzierbare Massenproduktion – Unterstützt feste Zufallsseeds und bietet zusammen mit Stil- und Render-Geschwindigkeitsstufen eine stabile Reproduktion für Serienmaterialien.

Funktionsbeschreibung

Gezielte Bearbeitung per Maske: Übergib ein Quellbild und eine Maske mit demselben Seitenverhältnis; nur der von der Maske abgedeckte Bereich wird neu gezeichnet, der Rest des Bildes bleibt unverändert – ideal zum Ersetzen von Hintergründen oder einzelnen Elementen.

Charakterfixierung mit einem Referenzbild: Es ist genau ein Referenzbild erlaubt (JPEG, PNG oder WebP, maximal 10 MB), das die äußeren Merkmale der Figur im neu gezeichneten Ergebnis festlegt.

Prompt-gesteuerte Szene: Ein Prompt mit bis zu 5000 Zeichen beschreibt die Zielszene; zusätzlich kann die Prompt-Erweiterung aktiviert werden, um Beschreibungsdetails automatisch zu ergänzen.

Stil- und Geschwindigkeitsstufen: Der Stil ist wahlweise AUTO, REALISTIC oder FICTION; die Render-Geschwindigkeit ist in TURBO, BALANCED und QUALITY unterteilt, wobei die Stufen den Detailgrad unterscheiden.

Anwendungsfälle

Massenweise Iteration von Seriencharakter-Materialien – Marketing- und Designteams erzeugen mit demselben Referenzbild und unterschiedlichen Masken in großem Umfang Szenenbilder desselben Charakters für Social Media und Aktionsseiten.
Lokaler Szenenwechsel bei Postern und Werbebildern – Hintergrund und Lichtsetzung lassen sich ersetzen, während die Charakterfigur erhalten bleibt, sodass direkt einsetzbare Werbebilder und Materialien mit Textlayout entstehen.
Charakterkonsistenz in Comics und Storyboards – Autoren zeichnen Posen und Szenen in Storyboards anhand eines festen Referenzbildes neu und erhalten fortlaufende, visuell stimmige Bilder für das Storyboard.

Einschränkungen und Auswahlhinweise

Die Charakterkonsistenz ist nicht absolut; bei komplexen Szenen oder extremen Posen und Gesichtsausdrücken können sichtbare Abweichungen auftreten. Das Referenzbild sollte ein klares Gesicht, gute Beleuchtung und möglichst wenig Verdeckung aufweisen, andernfalls leidet die Qualität. Maske und Quellbild müssen dasselbe Seitenverhältnis haben, und es wird nur ein Referenzbild akzeptiert. Wenn die Aufgabe in einer einzelnen, unabhängigen kreativen Generierung besteht und kein fester Charakter fixiert werden muss, ist der Text-zu-Bild-Weg besser geeignet; die Detailstufe QUALITY und höher verlängert die Generierungszeit, sodass zwischen Geschwindigkeit und Qualität abgewogen werden muss.

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/edit

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

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

seedintegerOptionalmin 0max 2147483647

Ganzzahliger Zufallsseed, mit dem sich die Generierungsergebnisse für denselben Prompt reproduzieren lassen; Wert in Form einer Ganzzahl.

stylestringOptionalStandard: "AUTO"

Gibt den für die Generierung verwendeten Stiltyp an, Standard ist AUTO.

Optionen:AUTOREALISTICFICTION

promptstringPflichtminLength 1maxLength 5000

Beschreibt die Szene, in der sich die Referenzfigur befindet, d. h. den in dieser Bearbeitung zu generierenden Bildinhalt, maximal 5000 Zeichen.

mask_urlstringPflichtminLength 1pattern ^https?://

URL des Maskenbilds, das den neu zu zeichnenden Bereich festlegt; die Maske muss dasselbe Seitenverhältnis wie das Quellbild haben.

image_urlstringPflichtminLength 1pattern ^https?://

URL des zu bearbeitenden Quellbilds; dieses Bild muss dasselbe Seitenverhältnis wie die Maske haben.

expand_promptbooleanOptionalStandard: true

Boolescher Schalter, der steuert, ob MagicPrompt zum automatischen Erweitern des Prompts verwendet wird, Standard ist true.

rendering_speedstringOptionalStandard: "BALANCED"

Gibt die Stufe der Rendering-Geschwindigkeit an: TURBO ist am schnellsten und am günstigsten, QUALITY bietet die meisten Details, die Preise unterscheiden sich je nach Stufe; Standard ist BALANCED.

Optionen:TURBOBALANCEDQUALITY

reference_image_urlsarrayPflichtminItems 1maxItems 1

Array von Referenzbildern der Figur; es wird genau ein Referenzbild der Figur benötigt, unterstützt werden 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/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"
}

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