So verwendest du ideogram-v4 über die hiapi API: curl, Python und eine funktionierende Anfrage

Der Ruf der Ideogram-Modelle beruht auf einer Sache, die die meisten Bildmodelle bis heute nicht hinbekommen: Typografie. Überschriften auf Postern werden korrekt buchstabiert, Buchstaben in Logos sind sauber und klar, und Schildtexte verschwimmen nicht zu einem unleserlichen Zeichensalat. ideogram-v4 ist wie alle anderen Bild- und Videomodelle über dieselbe einheitliche Task-API auf hiapi verfügbar, und dieser Leitfaden führt dich vollständig durch diese Anfrage: eine direkt kopier- und einfügbare curl-Version, ein vollständiges Python-Skript, die Parameter, die das Schema tatsächlich validiert (sie unterscheiden sich von dem, was die native Ideogram-API bereitstellt), sowie die Fehler, auf die du in der Praxis stoßen wirst.

Was du baust und was du vorbereiten musst

Ziel: einen Text-Prompt an POST /v1/tasks senden, auf den Abschluss des Tasks warten und dann ein Bild herunterladen, in dem der Text genau so gerendert ist, wie du es verlangt hast.

Du brauchst nur eine Sache: einen hiapi API-Schlüssel – erstelle ihn in der Konsole. Er wird bei jeder Anfrage als Bearer-Token verwendet. Es gibt keine kostenlose nicht authentifizierte Ebene; alle untenstehenden Aufrufe gehen von Authorization: Bearer sk-... aus.

Wie alle Modelle auf hiapi ist ideogram-v4 asynchron: Du erstellst einen Task, erhältst sofort eine taskId und pollst dann entweder das Ergebnis oder empfängst einen Callback. Es gibt keinen synchronen Modus „40 Sekunden auf einer HTTP-Verbindung warten“ – und bei der Bildgenerierung würdest du das ohnehin nicht wollen.

Minimale Anfrage: curl

Task erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4",
    "input": {
      "prompt": "Ein Jazzfestival-Poster im Stil des Retro-Art-déco. Die Hauptüberschrift \"MIDNIGHT & BRASS\" in fetter goldener Schrift auf dunkelmarineblauem Hintergrund, die Unterzeile \"Live at the Riverside, Fridays\" darunter in einer dünnen serifenlosen Schrift.",
      "rendering_speed": "BALANCED",
      "aspect_ratio": "3:4"
    }
  }'

Die Antwort kommt sofort zurück, die Task-ID befindet sich in data.taskId (Form tk-hiapi-...). Poll sie:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-XXXXXXXX \
  -H "Authorization: Bearer $HIAPI_KEY"

Während der Bildgenerierung durchläuft data.status nacheinander queued und handling. Im Endzustand wird es zu success oder fail. Bei Erfolg befindet sich die Bild-URL in data.output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-XXXXXXXX",
    "status": "success",
    "output": [
      { "url": "https://.../result.png?...expireAt=..." }
    ]
  }
}

Bei dieser URL gibt es einen Punkt zu beachten: Sie ist signiert und läuft ab (expireAt). Lade die Bytes unmittelbar nach dem Erfolg des Tasks herunter und speichere sie in deinem eigenen Speicher. Speichere niemals Hotlinks in einer Datenbank.

Die Parameter, die ideogram-v4 tatsächlich akzeptiert

Dies ist der Teil, den man präzise behandeln sollte. Wenn du die eigene Dokumentation von Ideogram gelesen hast, weißt du, dass die native API Stil-Presets, Magic-Prompt-Schalter, negative Prompts und Batch-Anzahlen bereitstellt. Das Task-Schema von ideogram-v4 auf hiapi ist bewusst kleiner gehalten, und der Validator lehnt alles ab, was außerhalb des Schemas liegt. Hier ist der vollständige Umfang, bestätigt durch die Live-API:

Feld	Erforderlich	Typ / Werte
prompt	Ja	string
rendering_speed	Ja	"TURBO", "BALANCED", "QUALITY"
aspect_ratio	Nein	"1:1", "16:9", "4:3", "9:16", "3:4"
seed	Nein	Ganzzahl

Beide Pflichtfelder werden streng validiert. Wenn du ein leeres input sendest, erhältst du:

invalid input: prompt: missing required field "prompt";
rendering_speed: missing required field "rendering_speed"

Bei falsch geschriebenen Enum-Werten nennt dir der Fehler die gültigen Werte:

invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'

Und alles, was in der nativen Ideogram-Schnittstelle nicht in der obigen Tabelle aufgeführt ist, wird als unbekanntes Attribut abgelehnt – style_type, magic_prompt, negative_prompt, num_images, size sowie Bildeingaben geben alle 400 zurück, zum Beispiel:

invalid input: <root>: additional properties 'style_type' not allowed

Praktische Auswirkungen:

• Die Typografie-Kontrolle hängt vollständig vom Prompt ab. Setze den exakten Text, den du rendern möchtest, in doppelte Anführungszeichen in den Prompt und beschreibe die Schrift („fette Art-déco-Schrift“, „dünne geometrische serifenlose Schrift“, „handgezeichnete Schilderschrift“). So erzielst du die Poster-/Logo-/Schild-Effekte, für die Ideogram bekannt ist – es gibt keinen separaten Stilparameter, auf den du dich verlassen kannst.
• Ein Bild pro Task. Es gibt kein n oder num_images. Wenn du vier Kandidaten möchtest, reiche vier Tasks ein und polle jede taskId separat.
• seed ist dein Regler für Reproduzierbarkeit. Gleicher Prompt + gleicher Seed ergeben einen stabilen Ausgangspunkt, um Formulierungen zu iterieren.
• Nur Text-zu-Bild. Das Modell-Schema akzeptiert keine Referenzbilder. Wenn dein Workflow Bild-zu-Bild erfordert, wähle ein Modell, das dies unterstützt – siehe wie man mehrere Bildmodelle mit einem API-Schlüssel aufruft, um Modelle zu wechseln, ohne den Integrationscode zu ändern.

Zu rendering_speed: TURBO ist die schnelle Stufe, geeignet für Entwürfe, während du die Prompt-Formulierung iterierst; QUALITY ist die langsame, feine Stufe für das finale Rendering; BALANCED ist ein sinnvoller Standardwert. Die Abrechnung erfolgt nutzungsbasiert pro Bild – aktuelle Preise findest du auf der Preisseite.

Das vollständige Python-Skript

Derselbe Ablauf – erstellen, pollen, herunterladen – mit Timeout und Behandlung von Endzuständen. Die einzige Abhängigkeit ist requests (pip install requests).

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, rendering_speed: str = "BALANCED",
                aspect_ratio: str = "1:1", seed: int | None = None) -> str:
    input_obj = {
        "prompt": prompt,
        "rendering_speed": rendering_speed,
        "aspect_ratio": aspect_ratio,
    }
    if seed is not None:
        input_obj["seed"] = seed
    resp = requests.post(API_BASE, headers=HEADERS,
                         json={"model": "ideogram-v4", "input": input_obj},
                         timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: HTTP {resp.status_code} {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt=('Entwirf ein minimalistisches Logo für eine Kaffeemarke namens "Driftwood", '
                'das Wort Driftwood als Wortmarke in einer warmen Serifenschrift, einfarbig, '
                'cremefarbener Hintergrund'),
        rendering_speed="QUALITY",
        aspect_ratio="1:1",
        seed=42,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    png = requests.get(url, timeout=120).content   # Signierte URL läuft ab - sofort herunterladen
    with open("driftwood-logo.png", "wb") as f:
        f.write(png)
    print("saved driftwood-logo.png,", len(png), "bytes")

Hinweise für die Produktion: Callbacks, Idempotenz und Fehler

Polling vs. Callback. Für interaktive Tools, die ein Bild nach dem anderen generieren, ist Polling alle paar Sekunden einfacher und völlig ausreichend. Für Batch- oder Server-Workloads füge der Erstellungsanfrage einen Callback hinzu, damit hiapi dir das Endergebnis per POST zustellt:

{
  "model": "ideogram-v4",
  "input": { "prompt": "...", "rendering_speed": "BALANCED" },
  "callback": { "url": "https://your.domain.example/hiapi/hook", "when": "final" }
}

Es gibt zwei Einschränkungen, die beide bei der Erstellung erzwungen werden: Die URL muss https:// sein und öffentlich erreichbar; when akzeptiert nur "final" – wenn du einen anderen Wert versuchst, gibt die API direkt invalid callback.when: only 'final' is supported zurück. Mache deinen Handler idempotent bezüglich der taskId, antworte schnell mit 2xx und behalte einen Polling-Fallback für Tasks, deren Callback nie ankommt. Falls der Callback nicht ankommt, untersuche zuerst gemäß warum dein hiapi Task-Callback nicht ausgelöst wird, bevor du die Queue verantwortlich machst.

Idempotenz. Das Erstellen von Tasks ist nicht idempotent – jeder erfolgreiche POST /v1/tasks ist ein neuer Task und eine neue Abrechnung. Speichere die taskId sofort nach Erhalt zusammen mit deiner eigenen Task-ID, und bei allen späteren Wiederholungen pollst du die gespeicherte taskId, statt neu einzureichen.

Fehler, die du tatsächlich sehen wirst.

• 401 mit "code": "permission_denied" – der Schlüssel ist ungültig oder kann dieses Modell nicht verwenden. Die Meldung sagt es klar: „This API key cannot use the selected model. Please check permissions or use another key.“ Behebe das in der Konsole, versuche es nicht erneut.
• 400 mit "error_code": "INVALID_REQUEST" – die Validierung ist fehlgeschlagen. Die message nennt das konkrete Feld und die gültigen Werte; lies sie und korrigiere den Request-Body. Ein erneuter Versuch mit demselben Body wird immer fehlschlagen.
• 404 "task not found" bei GET /v1/tasks/{id} – die Task-ID ist falsch oder der Task wurde mit einem anderen Schlüssel erstellt.
• fail-Status bei einem bereits akzeptierten Task – prüfe data.error.code / data.error.message in der Polling-Antwort. Diese können sicher als neuer Task erneut versucht werden.

Weiterführende Lektüre

• ideogram-v4 Modellseite – Fähigkeiten und aktuelle Preisstufen
• Warum dein hiapi Task-Callback nicht ausgelöst wird – Checkliste zur Fehlersuche bei Callbacks
• Wie man mehrere Bildmodelle mit einem API-Schlüssel aufruft – dieselbe Task-API, andere model-Strings
• Die günstigste Bildgenerierungs-API – wie man die tatsächlichen Kosten pro Bild über Modelle hinweg vergleicht
• API-Dokumentation – die vollständige Referenz zu POST /v1/tasks / GET /v1/tasks/{id}

Häufig gestellte Fragen

Unterstützt ideogram-v4 auf hiapi Bild-zu-Bild oder Referenzbilder? Nein. Das Task-Schema des Modells akzeptiert nur prompt, rendering_speed, aspect_ratio und seed – jedes Bildeingabefeld wird mit 400 abgelehnt. Wenn du ein vorhandenes Bild bearbeiten oder neu zeichnen möchtest, verwende ein Modell, das Bild-zu-Bild unterstützt (zum Beispiel die gpt-image-2-Serie).

Welches rendering_speed sollte ich verwenden? Iteriere mit TURBO, während du den Prompt und die exakte Formulierung des Textes optimierst, und rendere dann die finale Gewinnerversion mit QUALITY und demselben seed neu. Wenn du nur einmal renderst, ist BALANCED ein guter Standardwert.

Wie bringe ich ideogram-v4 dazu, den exakten Text zu rendern? Setze den wörtlichen Text in doppelte Anführungszeichen in den Prompt und beschreibe die Typografie drumherum: Hauptüberschrift "SUMMER SALE" in fetter, komprimierter serifenloser Schrift. Kürzere Strings werden zuverlässiger gerendert als vollständige Sätze; wenn eine lange Zeile unleserlich gerendert wird, teile sie in Hauptüberschrift und Unterzeile auf.

Kann ich mehrere Bilder in einer Anfrage generieren? Nein – ein Task generiert ein Bild. Reiche stattdessen mehrere Tasks parallel ein; jeder Task hat seine eigene taskId und wird unabhängig eingereiht.

Warum erhalte ich 401 permission_denied, obwohl mein Schlüssel bei anderen Modellen funktioniert? Der Modellzugriff wird pro Schlüssel konfiguriert. Prüfe die Modellberechtigungen dieses Schlüssels in der Konsole oder erstelle einen neuen Schlüssel mit Zugriff auf ideogram-v4.

Wie lange ist die Ausgabe-URL gültig? Es ist eine signierte URL mit einem expireAt-Zeitstempel. Behandle sie eher als Minuten- statt Tagesangelegenheit: Lade das Bild herunter, sobald der Task success erreicht, und speichere die Datei selbst.

Welche Seitenverhältnisse sind verfügbar? Genau fünf: 1:1, 16:9, 4:3, 9:16 und 3:4. Es gibt keinen freien size-Parameter – Anfragen mit size werden als unbekanntes Attribut abgelehnt.