Tutorial

So verwendest du die krea-2-medium-turbo Text-zu-Bild-API (curl + Python)

Oct 21, 2026

krea-2-medium-turbo ist die schnelle, kostengünstige Text-zu-Bild-Stufe von Krea auf hiapi. Du sendest einfach einen Prompt, wählst ein Seitenverhältnis und erhältst über die asynchrone Task-API ein gerendertes Bild. Dieser Leitfaden enthält direkt kopierbare curl- und Python-Anfragebeispiele für /v1/tasks, das genaue Eingabe-Schema sowie die Laufzeiten und Fehlerverhalten, die ich am 2026-10-21 gemessen habe – darunter ein Ergebnis, das der Dokumentation widerspricht.

Voraussetzungen

Ein hiapi-API-Schlüssel (sk-...). Erstelle ihn in der API-Keys-Konsole. Jede Anfrage wird über Authorization: Bearer sk-<your-key> authentifiziert. Das ist die einzige Voraussetzung – das Modell läuft serverseitig, du musst also außer einem HTTP-Client nichts installieren.

Eingabe-Schema

krea-2-medium-turbo akzeptiert fünf Felder. Davon sind nur prompt und model erforderlich:

Feld	Erforderlich	Typ	Standardwert	Beschreibung
`model`	Ja	string	—	Muss exakt `krea-2-medium-turbo` sein.
`prompt`	Ja	string	—	1–5000 Zeichen.
`aspect_ratio`	Nein	enum	`1:1`	Einer von `1:1`, `4:3`, `3:2`, `16:9`, `2.35:1`, `4:5`, `2:3`, `9:16`.
`creativity`	Nein	enum	`low`	`raw` (am wörtlichsten) → `low` → `medium` → `high` (am kreativsten).
`seed`	Nein	integer	—	Optional. Lies vor dem Verlassen darauf zuerst den Hinweis zu seed weiter unten.

Das input-Objekt ist strikt (additionalProperties: false): Jedes Feld, das nicht in dieser Tabelle steht, wird abgelehnt, bevor die Generierung beginnt. Es gibt kein n / num_images, kein resolution oder size und kein Feld für Negativ-Prompts. Eine Anfrage liefert genau ein Bild, und die Ausgabegröße wird ausschließlich durch aspect_ratio bestimmt. Wenn du auf hiapi andere Bild-APIs verwendet hast, die resolution (Seedream, Qwen-Image) oder size akzeptieren, lasse diese Felder hier weg – sie führen zu einem 400.

Minimal funktionierende Anfrage (curl)

Das Erstellen eines Tasks gibt sofort eine taskId zurück; das Bild wird im Hintergrund gerendert.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Antwort:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" }, "message": "success" }

Anschließend fragst du den Task anhand der ID ab, bis ein Endzustand erreicht ist:

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" \
  -H "Authorization: Bearer sk-<your-key>"

Ein abgeschlossener Task sieht so aus (Felder zur Übersichtlichkeit gekürzt):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

Das Bild befindet sich unter data.output[0].url.

Derselbe Ablauf in Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-<your-key>",
    "Content-Type": "application/json",
}

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Abfragen, bis der Task einen Endzustand erreicht.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Achtung: trotzdem HTTP 200, siehe unten
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

Hinweise für den Produktivbetrieb

Polling oder Callback verwenden. Die obige Schleife fragt alle 3 Sekunden ab, was bei geringer Parallelität in Ordnung ist. In der Produktion kannst du beim Erstellen der Anfrage callback.url mit when: "final" angeben, damit hiapi den abgeschlossenen Task per POST an dich sendet, statt zu pollen – die Callback-Konvention findest du in der Task-API-Dokumentation.
Fehlgeschlagene Generierungen liefern trotzdem HTTP 200. Der HTTP-Statuscode am Polling-Endpunkt gibt an, ob die Anfrage erfolgreich war, nicht ob das Bild erfolgreich war. Ein Render-Fehler wird mit 200 und data.status: "fail" zurückgegeben. Verzweige nach data.status, nicht nach dem HTTP-Statuscode, sonst behandelst du einen Fehler als Erfolg.
Ausgabe-URLs sind temporär. Ergebnisse werden unter "storage": "temp" auf temp.hiapi.ai gespeichert und tragen einen expireAt-Zeitstempel; sie laufen nach etwa sieben Tagen ab (in meinem Lauf 604.800 Sekunden). Lade die Bytes herunter und hoste sie neu (eigener Bucket/CDN), sobald der Task abgeschlossen ist – verlinke temp.hiapi.ai-URLs nicht direkt (Hotlinking) in Produktivseiten.
Die Preisgestaltung ist ein einziger Festpreis pro Bild, unabhängig von Seitenverhältnis oder Kreativitätsstufe – es gibt keine Auflösungsstufen zu berücksichtigen. Schau dir die aktuellen Zahlen auf der Preisseite an, statt sie fest zu codieren.

Was ich tatsächlich getestet habe (2026-10-21)

Alles Folgende stammt aus Live-Aufrufen, nicht aus der Dokumentation:

Laufzeit und Auflösung. Eine 2.35:1-Anfrage war in etwa 26 Sekunden abgeschlossen (Differenz created → completed) und lieferte ein PNG mit 1568 × 672 px – 2.35:1 ist also tatsächlich ein Cinemascope-Zuschnitt und nicht annähernd quadratisch. Der Task durchläuft beim Rendern und Verschieben der Datei in den temporären Speicher die Zwischenzustände handling → archiving → success.
Enum-Validierung wird serverseitig erzwungen. Das Senden von "aspect_ratio": "21:9" (ein plausibler, aber nicht unterstützter Wert) liefert sofort 400: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. Die Fehlermeldung nennt das Feld und listet die gültigen Werte auf, was die programmatische Verarbeitung erleichtert.
Unbekannte Felder liefern 400, sie werden nicht ignoriert. "resolution": "2K" liefert invalid input: <root>: additional properties 'resolution' not allowed; "n": 2 liefert denselben Fehler für n. Hier greift die additionalProperties: false-Regel – kopierst du den Request-Body von anderen Modellen, verhindern die überzähligen Felder den gesamten Aufruf.
In meinem Test konnte seed nicht dasselbe Bild reproduzieren. Ich habe zweimal hintereinander denselben Prompt, seed: 42, aspect_ratio: 2.35:1 und creativity: medium gesendet. Beide Male kam ein gültiges 1568 × 672-Bild zurück, aber es waren deutlich unterschiedliche Szenen (einmal ein weißer Turm, einmal ein rot-weiß gestreifter Turm), die Dateigrößen unterschieden sich (1,30 MB vs. 1,51 MB) und auch die Hashes waren verschieden. Das Feld wird akzeptiert und in der Dokumentation als reproduzierbar beschrieben, aber betrachte die exakte Pixel-Reproduktion als Best-Effort und nicht als Garantie – wenn du eine bestimmte Darstellung brauchst, speichere das Ergebnis, das du erhältst, und frage nicht mit seed erneut an.

FAQ

Welche Seitenverhältnisse kann ich anfordern? Acht: 1:1 (Standard), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 und 9:16. Jeder andere Wert liefert 400.

Kann ein Aufruf mehrere Bilder generieren? Nein. Es gibt kein n-Feld, und das Schema lehnt unbekannte Eigenschaften ab, sodass jede Anfrage genau ein Bild erzeugt. Für die Stapelgenerierung sendest du Anfragen in einer Schleife (optional mit unterschiedlichen Seeds).

Wofür ist creativity zuständig? Es steuert, wie wörtlich das Modell dem Prompt folgt: raw bleibt am engsten am Wortlaut, high erlaubt die größte Interpretationsfreiheit, low (Standard) und medium liegen dazwischen.

Unterstützt krea-2-medium-turbo Bild-zu-Bild oder Bearbeitung? Nein – es unterstützt nur Text-zu-Bild. Das Schema enthält kein Feld image_urls / für Eingabebilder. Wenn du ein vorhandenes Bild umwandeln musst, verwende ein spezielles Bearbeitungs-/Bild-zu-Bild-Modell auf hiapi.

Wie lange sind die Ausgabe-URLs gültig? Sie werden aus dem temporären Speicher bereitgestellt und laufen ab (in meinem Test nach etwa sieben Tagen). Lade die Bilder direkt nach Abschluss des Tasks herunter und hoste sie neu.