Wie verwendet man die Ideogram 3.0 Character API? In 5 Minuten zum ersten Charakterbild

TL;DR

• Ideogram 3.0 Character ist ein Modell zur Charaktergenerierung anhand eines Referenzbilds: Lade 1 Charakter-Referenzbild hoch, schreibe einen Szenen-Prompt, und dasselbe Gesicht und dieselbe Kleidung erscheinen in der neuen Szene. Öffne die Modellseite, um es online auszuprobieren – neue Nutzer erhalten bei der Registrierung 200 Credits.
• Der Preis wird pro Bild berechnet: TURBO $0.09, BALANCED $0.13, QUALITY $0.18. Referenzbilder sind kostenlos, Fehlschläge werden nicht berechnet (Details auf der Preisseite).
• Der Aufruf erfolgt über die HiAPI-/v1/tasks-Schnittstelle: Aufgabe einreichen und taskId erhalten, damit das Ergebnis abfragen und nach Erfolg das Bild von output[0].url herunterladen.

Was es kann

• Konsistente Charaktergenerierung: Ein Referenzbild legt den Charakter fest, Gesichtsform und Kleidung bleiben konsistent, die Szene kann beliebig gewechselt werden.
• Illustration und Realismus gleichermaßen: style bietet AUTO / REALISTIC / FICTION – sowohl fotografische Personen als auch Illustrationscharaktere funktionieren.
• Bildformat folgt dem Referenzbild: Hochformat-Referenz ergibt 3:4 (864×1152), Querformat-Referenz ergibt 16:9 (1328×752) – kein Größenparameter nötig.
• Zugehöriger Bearbeitungsendpunkt: ideogram-v3-character/edit zeichnet den Charakter per Maske in einen bestimmten Bereich eines vorhandenen Bildes, der Rest des Bildes bleibt unverändert.

Das folgende Bild ist ein echtes Ergebnis (Referenzbild: ein Querformat-Illustrationscharakter):

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

(Auf Deutsch: Dieser Entdecker-Charakter geht über einen mit Laternen geschmückten Nachtmarkt, hält einen Pappbecher mit heißen Nudeln, links und rechts warm leuchtende Stände, Bilderbuch-Illustrationsstil, kein Text, keine Schilder.)

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

Mit diesem Prompt generieren →

Welchen der beiden Endpunkte wählen

	ideogram-v3-character	ideogram-v3-character/edit
Aufgabe	Neue Szene für den Charakter von Grund auf generieren	Den Charakter in den maskierten Bereich eines vorhandenen Bildes zeichnen
Pflichteingaben	prompt + 1 Referenzbild	prompt + Originalbild + Maske + 1 Referenzbild
Preis (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
Ausgabe	WebP, Bildformat folgt dem Referenzbild	WebP, Größe folgt dem Originalbild
Geeignet für	Poster, Serien, Szenenbilder für Bildfolgen	Charakter in einem fertigen Bild austauschen oder ergänzen

Maskenkonvention: Schwarz = neu zeichnen, Weiß = beibehalten; das Seitenverhältnis von Maske und Originalbild muss übereinstimmen. Der Bearbeitungsendpunkt akzeptiert kein negative_prompt – wird es übergeben, folgt ein 400-Fehler.

Zwei Wege zum Einstieg

3 Schritte im Browser: Modellseite öffnen → Charakter-Referenzbild hochladen, Prompt einfügen → auf Generieren klicken, ein TURBO-Bild kostet $0.09.

3 Schritte per API: POST /v1/tasks einreichen → taskId erhalten → mit GET /v1/tasks/<taskId> bis success abfragen und dann herunterladen.

curl: das erste Bild

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

Beim Bearbeitungsendpunkt model durch ideogram-v3-character/edit ersetzen und in input image_url (Originalbild) und mask_url (Maske) ergänzen:

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

Die taskId in der Antwort ist der Nachweis für die Abfrage.

Python: Einreichen, Abfragen, Herunterladen

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

# Einreichen: mit Idempotency-Key, Netzwerk-Wiederholungen legen keine doppelten Aufgaben an
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Abfragen: 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"]   # temporäre Adresse, schnell herunterladen und speichern
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Parametertabelle (ideogram-v3-character)

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	1–5000 Zeichen	Beschreibt die Szene, in der der Charakter erscheinen soll, nicht das Aussehen des Charakters (Aussehen siehe Referenzbild)
reference_image_urls	Ja	Genau 1 Bild, JPEG / PNG / WebP, ≤10 MB	Charakter-Referenzbild; sein Format bestimmt das Ausgabeformat
rendering_speed	Nein	TURBO / BALANCED / QUALITY, Standard BALANCED	Bestimmt Stufe und Preis
style	Nein	AUTO / REALISTIC / FICTION, Standard AUTO	REALISTIC tendiert zu Fototextur, FICTION behält den Illustrationslook
seed	Nein	Ganzzahl 0–2147483647	Gleiche Parameter und gleicher Seed reproduzieren das Bild
expand_prompt	Nein	Standard true	Erweitert den Prompt automatisch; für strikte Befolgung des Originaltexts false übergeben
negative_prompt	Nein	≤5000 Zeichen	Inhalte, die nicht erscheinen sollen

Der Bearbeitungsendpunkt hat zusätzlich zwei Pflichtfelder außerhalb der Tabelle: image_url und mask_url, und unterstützt kein negative_prompt. Felder außerhalb der Tabelle im Request-Body führen direkt zu 400 (additional properties ... not allowed).

Fehler, die dir begegnen werden (Originaltexte der Schnittstelle)

Was du getan hast	Antwort
prompt nicht übergeben	400 invalid input: prompt: missing required field "prompt"
2 Referenzbilder übergeben	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed falsch geschrieben	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Ein Feld übergeben, das die Schnittstelle nicht kennt	400 invalid input: <root>: additional properties 'foo' not allowed
negative_prompt an den Bearbeitungsendpunkt übergeben	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Guthaben nicht ausreichend	402 insufficient account balance; top up and retry

Wiederholtes Einreichen mit demselben Idempotency-Key liefert 409 (in Bearbeitung) oder 422 (Parameter weichen ab) – dann einen neuen Key verwenden und erneut versuchen.

Hinweise vor dem Go-live

• Callback: Auf oberster Ebene des Request-Bodys "callback": {"url": "https://..."} übergeben; erreicht die Aufgabe einen Endzustand, wird dein Dienst benachrichtigt, und du sparst dir das Polling.
• Rechtzeitig kopieren: output[0].url ist eine temporäre Adresse – sobald du sie hast, herunterladen und im eigenen Speicher ablegen; nicht als dauerhaften Link verwenden.
• Stufe und Bildformat explizit angeben: rendering_speed bei jedem Aufruf explizit übergeben (ohne Angabe wird nach BALANCED abgerechnet); das Ausgabeformat bestimmt das Referenzbild – für Hochformat-Szenen also ein Hochformat-Referenzbild vorbereiten.
• Batch-Aufgaben jeweils mit eigenem Idempotenzschlüssel: Jede Einreichung erhält einen eindeutigen Idempotency-Key; bei Netzwerk-Wiederholungen mit demselben Key wird nur dieselbe Aufgabe getroffen – keine doppelten Aufgaben, keine doppelten Credit-Abbuchungen.

Häufige Fragen

Kann das Referenzbild eine URL sein?

Ja. Solange es eine erreichbare http/https-Adresse ist – JPEG, PNG, WebP sind alle möglich, maximal 10 MB.

Wie viele Referenzbilder können übergeben werden?

Genau 1 – das ist eine harte Regel; zwei Bilder führen direkt zu einem 400-Fehler. Für einen anderen Charakter einfach das Referenzbild austauschen.

Muss ein Größenparameter übergeben werden?

Nein. Das Ausgabeformat folgt dem Referenzbild: Hochformat-Referenz ergibt 864×1152, Querformat-Referenz ergibt 1328×752.

Ist der Aufruf bei beiden Endpunkten gleich?

Ja. Nur model und die Felder in input ändern sich.

Wird bei einem Fehlschlag abgerechnet?

Nein, vorab einbehaltene Credits werden nach dem Endzustand „fail“ vollständig zurückerstattet.

Nächster Schritt: Probiere mit dem obigen Nachtmarkt-Prompt auf der Modellseite ein Bild aus und wähle dann je nach Szene Prompts aus der Prompt-Sammlung; die drei Preisstufen und eine Budgettabelle findest du auf der Preisseite.