Wie verwendet man die Ideogram 4.5 API? Generieren, bearbeiten und Aufgaben abfragen

TL;DR

• Ideogram 4.5 ist eine Text-to-Image-Serie mit Priorität auf Textlayout: ideogram-v4.5/text-to-image erzeugt Poster, Logo-Wortmarken und zweisprachige Verpackungen – also Bilder mit Text; ideogram-v4.5/image-to-image nutzt Precise Edit zum präzisen Ändern von Text, Referenzbilder für einen anderen Stil und Masken für lokale Änderungen. Aufgaben lassen sich auf der Modellseite auswählen oder über die unten beschriebene Schnittstelle aufrufen.
• Der Preis wird pro Bild berechnet und hängt von der Qualitätsstufe ab: LOW $0.043, MEDIUM (Standard) $0.086, HIGH $0.3145; Bearbeitungsstufen ab VERY_LOW $0.0115; derzeit liefert jede Anfrage 1 Bild, num_images darf nur 1 sein. Details auf der Preisseite.
• Der Aufruf erfolgt über die HiAPI-Schnittstelle /v1/tasks: nach dem Absenden data.taskId auslesen, dann data.status abfragen; nach Erfolg die Adresse mit type=image aus data.output zum Herunterladen entnehmen.

Was es kann

• Texthierarchie im Bild organisieren: Den gewünschten Text in Anführungszeichen setzen und Positionen für Titel, Untertitel, Datum und Besetzung getrennt angeben; nach der Ausgabe Zeichen für Zeichen prüfen.
• Komposition mit Einzelbild-Aufgaben erkunden: Jede Anfrage liefert 1 Bild; Prompt oder Seed anpassen und mehrere Aufgaben getrennt einreichen, um Richtungen zu vergleichen.
• Passende Bearbeitungsschnittstelle: Precise Edit (edit_precision=high) eignet sich für kleine Änderungen wie Markennamen oder Datum; erhaltene Bereiche gegen das Quellbild prüfen.
• Referenzbilder + Maske: Maximal 4 Referenzbilder (mit Maske 3); Maske Schwarz = neu zeichnen, Weiß = beibehalten.

Hier ein echtes Ergebnis in der LOW-Stufe:

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(Deutsche Bedeutung: minimalistisches, modernes Markenposter für eine Designkonferenz, zentrierte, riesige fette Überschrift „DESIGN FORWARD“, darunter kleinerer Untertitel „Typography Summit 2026“, klares Schweizer Rasterlayout, warme Orange- und tiefe Marineblau-Palette, geometrische Formen, gestochen scharfe Buchstaben. Format landscape_16_9 wählen.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, $0.043.

Mit diesem Prompt generieren →

Welche der beiden Schnittstellen wählen

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
Aufgabe	Aus Text ein Bild mit Layout erzeugen	Ein vorhandenes Bild bearbeiten
Pflichteingabe	prompt	image_url + prompt
Qualitätsstufen	low / medium / high	very_low / low / medium / high
Besondere Parameter	num_images: 1, enable_prompt_expansion	edit_precision (Precise), reference_image_urls, mask_url
Größe	6 Voreinstellungen, Standard square_hd	auto (Standard) oder 6 Voreinstellungen; mit Maske / Precise nur auto
Geeignet für	Neuentwürfe für Poster, Logo, Verpackung, Schild	Text ändern, Farben tauschen, Saisonvarianten, lokales Neuzeichnen

Typische Pipeline: Ein Markenposter generieren und dann mit Edit den Markennamen oder das Datum auf die Kundenvariante ändern. Generieren LOW für $0.043 plus Precise LOW für eine Textänderung $0.043 ergibt $0.086 pro Satz.

Zwei Einstiegswege

Browser in 3 Schritten: Modellseite öffnen → Prompt einfügen, Qualitätsstufe wählen → Generieren klicken.

API in 3 Schritten: POST /v1/tasks absenden → data.taskId auslesen → mit GET /v1/tasks/<taskId> den data.status abfragen und nach success herunterladen.

curl: Das erste Bild

Im Terminal zuerst HIAPI_IDEMPOTENCY_KEY als eindeutige Kennung für diesen Geschäftsvorgang setzen und beim Wiederholen derselben Anfrage diesen Wert beibehalten. Das Beispiel verwendet explizit LOW, ein Querformat und aktivierte Prompt-Erweiterung.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

Bearbeitungsschnittstelle: model durch ideogram-v4.5/image-to-image ersetzen und Quellbild plus Anweisung übergeben. Das folgende Beispiel fordert mit Precise Edit eine Textänderung an und verlangt, das Layout beizubehalten; das Ergebnis muss dennoch gegen das Quellbild geprüft werden:

Für diese Bearbeitungsaufgabe zusätzlich HIAPI_EDIT_IDEMPOTENCY_KEY setzen und nicht den Schlüssel der Generierungsaufgabe wiederverwenden.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python: Absenden, Abfragen, Herunterladen

Zuerst requests installieren und HIAPI_API_KEY setzen; beim ersten Absenden außerdem HIAPI_IDEMPOTENCY_KEY setzen, für jeden neuen Vorgang einen eigenen Wert verwenden und bei Wiederholung derselben Einreichung unverändert beibehalten. Das Programm gibt zuerst die Aufgaben-ID aus; nach einer Unterbrechung kann mit gesetztem HIAPI_TASK_ID die Abfrage und der Download fortgesetzt werden, ohne die Generierung erneut abzusenden.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

Bei Netzwerkfehlern beim Abfragen oder Herunterladen die bereits ausgegebene Aufgaben-ID behalten und dann fortsetzen; das Skript sendet die Erstellungsanfrage nicht automatisch erneut. Das Beispiel fragt maximal 600 Sekunden lang alle 3 Sekunden ab und schreibt den Download zuerst in eine .part-Datei, die erst nach Abschluss in den endgültigen Dateinamen umbenannt wird.

Parametertabelle

Generieren ideogram-v4.5/text-to-image

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	1–10000 Zeichen	Vier Abschnitte: welches Bild → Text und Farben → Layout → Textur und Einschränkungen
quality	Nein	low / medium / high, Standard medium	low zum massenhaften Erkunden, medium für den Alltag, high für Endfassungen mit viel kleinformatigem Text
image_size	Nein	6 Voreinstellungen, Standard square_hd	Keine benutzerdefinierte Breite/Höhe
num_images	Nein	Fest auf 1	Jede Aufgabe liefert 1 Bild
enable_prompt_expansion	Nein	Standard true	Prompt-Erweiterung; false deaktiviert sie, den Text im Ergebnis trotzdem prüfen
seed	Nein	Ganzzahl	Reproduzierbar mit gleichen Parametern

Bearbeiten ideogram-v4.5/image-to-image

Feld	Pflicht	Werte	Beschreibung
image_url	Ja	Bildadresse	Quellbild
prompt	Ja	1–10000 Zeichen	Bearbeitungsanweisung; klar angeben, was geändert und was beibehalten wird
edit_precision	Nein	regular / high, Standard regular	high = Precise Edit, geeignet für kleine Textänderungen
quality	Nein	very_low / low / medium / high, Standard medium	very_low nur mit regular kombinierbar
image_size	Nein	auto oder 6 Voreinstellungen, Standard auto	Mit Maske oder Precise nur auto
reference_image_urls	Nein	Maximal 4 Bilder	Mit Maske maximal 3 Bilder
mask_url	Nein	Bildadresse	Schwarz = neu zeichnen, Weiß = beibehalten
num_images	Nein	Fest auf 1	Jede Aufgabe liefert 1 Bild
seed	Nein	Ganzzahl

Felder in input, die nicht in der Parametertabelle dieses Modells stehen, führen zu 400; model, callback usw. auf oberster Ebene entsprechend dem Format der Aufgaben-Schnittstelle ausfüllen.

Fehler, die auftreten können

Statuscode	Bedeutung	Vorgehen
400 INVALID_REQUEST	Ungültiger Anfragekörper (fehlendes prompt oder image_url, falscher Enum-Wert, Feld außerhalb der Tabelle)	Anfragekörper anhand der Parametertabelle korrigieren
402 INSUFFICIENT_QUOTA	Guthaben reicht nicht (keine Abbuchung)	Nach Aufladen erneut versuchen
429 RATE_LIMITED	Ratenlimit erreicht	Einreichungsfrequenz reduzieren
409 IDEMPOTENCY_KEY_PROCESSING	Aufgabe mit demselben Schlüssel wird gerade erstellt	Warten und dann mit gleichem Schlüssel und gleichem Anfragekörper erneut versuchen
422 IDEMPOTENCY_KEY_MISMATCH	Gleicher Schlüssel mit anderem Anfragekörper	Ursprünglichen Anfragekörper wiederherstellen; nur neue Geschäftsvorgänge erhalten einen neuen Schlüssel

Ein endgültiges Scheitern einer Aufgabe kann Fehlercodes wie CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT enthalten. taskId und Fehlermeldung behalten und Abrechnung anhand des finalen Aufgabenstatus und der Kontoeinträge prüfen; ein fehlgeschlagenes Abfragen oder Herunterladen nicht als fehlgeschlagene Generierung behandeln.

Vor dem Produktivstart beachten

• Callback: Auf oberster Ebene im Anfragekörper "callback": {"url": "https://..."} übergeben; der Endstatus wird automatisch benachrichtigt.
• Rechtzeitig sichern: Ergebnislinks in data.output haben eine begrenzte Gültigkeit; nach Erfolg sofort herunterladen.
• Einzelbild-Aufgaben und Idempotenz: Jedes Mal 1 Bild; beim erneuten Versuch derselben Geschäftsanfrage nach Timeout denselben Idempotenzschlüssel beibehalten, nur neue Geschäftsvorgänge erhalten einen neuen Schlüssel.
• Kleiner chinesischer Text: Qualitätsstufen anhand des tatsächlichen Textes vergleichen; vor der Lieferung Zeichen für Zeichen prüfen – auch medium oder high ersetzt die Prüfung nicht.

Häufige Fragen

Wie viele Bilder werden pro Anfrage maximal erzeugt?

Generieren und Bearbeiten liefern derzeit jeweils 1 Bild, num_images darf nur 1 sein. Mehrere Richtungen als separate Aufgaben einreichen.

Ist die Standardqualitätsstufe LOW?

Nein. Standard ist MEDIUM mit $0.086 pro Bild; für LOW mit $0.043 pro Bild explizit quality: "low" übergeben.

Welcher Modus eignet sich, um nur Markenname und Datum zu ändern?

Precise Edit wählen und explizit edit_precision: "high", quality: "low", image_size: "auto" übergeben; $0.043 pro Bild.

Was bedeuten die schwarzen und weißen Bereiche der Maske?

Schwarze Bereiche werden neu gezeichnet, weiße Bereiche beibehalten. Die Maske hat dieselbe Größe wie das Quellbild; bei Verwendung einer Maske image_size auf auto setzen.

Muss nach einem Timeout beim Absenden der Idempotenzschlüssel gewechselt werden?

Beim erneuten Versuch derselben Geschäftsanfrage den Schlüssel nicht wechseln, sondern denselben Idempotency-Key und denselben Anfragekörper beibehalten; nur bei einer tatsächlich neuen Aufgabe einen neuen Schlüssel verwenden.

Nächster Schritt: Den Prompt für das DESIGN FORWARD-Poster nehmen und auf der Modellseite ein Bild erzeugen, dann mit einer Precise-Anweisung die Überschrift durch den eigenen Veranstaltungsnamen ersetzen. Weiterführende Lektüre: Drei Preisstufen und Budget · 4 Beispiele für Bearbeitungs-Prompts.

Wer direkt mit einer Wortmarke oder einem Event-Poster beginnen möchte, kann diese Prompt-Beispiele kopieren.