So verwendest du die Recraft Creative Upscale API: curl, Python und ein echter Lauf

TL;DR

• recraft/creative-upscale vergrößert Bilder und zeichnet dabei deren Texturen und Details neu. Der Request-Body hat nur ein einziges Feld: image_url. Kein Prompt, keine Skalierungseinstellungen.
• Es nutzt den einheitlichen /v1/tasks-Ablauf: POST für die taskId, dann GET /v1/tasks/<taskId> abfragen und schließlich von data.output[0].url herunterladen.
• In unserem Lauf kam eine 1254×1254-PNG nach etwa 60 Sekunden als 4096×4096-WebP mit ca. 19,8 MB zurück. Plane Wartezeit und Dateigröße entsprechend ein.

Was du vorbereiten musst

Einen hiapi API-Key aus der Konsole sowie eine öffentlich erreichbare Bild-URL. Die Modellseite nennt die Eingabegrenzen: PNG empfohlen, maximal 20 MB, 256–4096 px pro Kante, maximal 16 MP.

Wenn Text, Logos oder Produktdetails unverändert bleiben müssen, verwende stattdessen Recraft Crisp Upscale. Creative Upscale zeichnet neu, daher können sich kleine Elemente verändern.

Minimaler curl-Request

export HIAPI_KEY=sk-your-key

curl -s https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft/creative-upscale",
    "input": { "image_url": "https://example.com/old-illustration.png" }
  }'

Die Antwort ist ein Task-Handle:

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

Frage es ab, bis data.status gleich success ist:

curl -s https://www.hiapi.ai/v1/tasks/tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: absenden, abfragen, speichern

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def upscale(image_url: str, out_path: str) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30, json={
        "model": "recraft/creative-upscale",
        "input": {"image_url": image_url},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        time.sleep(5)
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # vorübergehender Netzwerkfehler: dieselbe taskId weiter abfragen
        if d["status"] == "success":
            url = d["output"][0]["url"]
            with open(out_path, "wb") as f:
                f.write(requests.get(url, timeout=120).content)
            return task_id
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(f"task {task_id} still running; re-poll it, do not resubmit")

upscale("https://example.com/old-illustration.png", "upscaled.webp")

Zwei Details sind im Produktivbetrieb wichtig. Erstens: Nach einem Timeout niemals neu absenden – jede Übermittlung erzeugt eine neue, abgerechnete Aufgabe. Behalte also die taskId und frage sie erneut ab. Zweitens: Speichere die Datei sofort; die Ausgabe-URL trägt ein expireAt und der Host ist temporär.

Hinweise für den Produktivbetrieb

• Für Batch-Aufgaben Callbacks verwenden. Statt zu pollen kannst du im Task-Body callback: {"url": "...", "when": "final"} übergeben, damit hiapi dich am Ende der Aufgabe aufruft. Behandle die taskId als Deduplizierungsschlüssel.
• Ein Abfrageintervall von 5 Sekunden reicht. Eine Aufgabe dauert etwa eine Minute, daher erzeugt häufigeres Abfragen nur mehr Requests.
• URL vor dem Absenden prüfen. Die Plattform weist fehlerhafte URLs vorab zurück (siehe unten), aber eine nicht erreichbare https://-URL ist ein anderer Fehlerfall – den fängst du am besten auf deiner Seite mit einem kurzen HEAD-Request ab.

Was wir in einem echten Lauf gesehen haben

Wir haben einen echten Request mit dem Beispiel-Eingabebild von der Modellseite ausgeführt (eine PNG einer Berghütte mit 1254×1254).

Punkt	Beobachtung
Antwort auf das Absenden	{"code":200,"data":{"taskId":"tk-hiapi-01M5K8J899THH6XJK99TAZ4VSD"}}
Statusfolge	handling → archiving → success
Zeit von created bis completed	61 Sekunden (1792721625 → 1792721686)
Ausgabe	ein Bild, WebP, https://temp.hiapi.ai/.../...-0.webp, mit einem expireAt nach etwa 7 Tagen
Eingabegröße	1254×1254 PNG, 2,7 MB
Ausgabegröße	4096×4096 WebP, ca. 19,8 MB

Wissenswertes aus diesem Lauf:

1. In der Phase archiving gibt es noch kein output. Die Aufgabe meldet über mehrere Abfragen hinweg completed und status: "archiving", bevor das Ergebnis in den Speicher verschoben wird. Nur status == "success" enthält output[0].url, lies die URL also nicht schon beim ersten completed-Zeitstempel aus.
2. Das Ergebnis ist kein sauberes 2-fach. Aus 1254 px Eingabe wurden 4096 px, also etwa 3,3-fach pro Kante. Die Modellseite zeigt dieselbe Paarung und bietet kein Skalierungsfeld, rechne also damit, dass die Ausgabegröße vom Modell und nicht von dir bestimmt wird. Wenn du genau 2-fach brauchst, ist Crisp Upscale der Endpunkt, der diese Zusage einhält.
3. Die Ausgabedateien sind groß. 19,8 MB für ein Bild liegen über der Eingabegrenze von 20 MB, die es erlauben würde, die Datei direkt wieder einzuspeisen – führe also keine zweite Runde ohne Größenanpassung auf der Ausgabe aus.
4. Details werden neu gezeichnet, nicht nur geschärft. Die Beschreibung der Modellseite zu diesem Bildpaar lautet: Komposition, Licht und Farbe bleiben weitgehend erhalten, während Holz, Steinmauerwerk und Geländer neu gezeichnet werden und sich einige kleine Elemente (etwa ein Baum neben der Veranda) verändern. Prüfe die Ausgabe, bevor du Markenassets ersetzt.
5. Fehlerhafte URLs schlagen schnell fehl. Sendet man "image_url": "not-a-url", kommt sofort HTTP 400 zurück: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: 'not-a-url' does not match pattern '^https?://'"}. Dieses Muster ist die einzige Prüfung, die wir verifiziert haben; das Minimum von 256 px oder die Obergrenze von 16 MP haben wir nicht getestet.

Wir haben nur eine Aufgabe ausgeführt, die 61 Sekunden sind also eine einzelne Stichprobe und kein Benchmark.

Creative Upscale oder Crisp Upscale?

Beide akzeptieren nur eine image_url und brauchen keinen Prompt. Der Unterschied liegt in der Art der Pixelverarbeitung und im Preis.

	Creative Upscale	Crisp Upscale
Modell-ID	recraft/creative-upscale	recraft/crisp-upscale
Verhalten	Vergrößert und zeichnet Texturen und Details neu	Verdoppelt Breite und Höhe, behält Inhalte und Text
Am besten geeignet für	Alte Illustrationen, kleine oder niedrig aufgelöste Grafiken	Produktfotos, Poster mit Text, Design-Assets
Preis	Deutlich höher pro Bild; siehe Preise	Siehe Crisp-Preisartikel

Creative Upscale ist pro Bild deutlich teurer als Crisp (vergleiche die aktuellen Zahlen auf der Preisseite), setze es also nur ein, wenn du wirklich möchtest, dass Details neu erzeugt werden. Für modellübergreifende Workflows zur generellen Auflösungserhöhung siehe Bildauflösung mit hiapi erhöhen.

Verwandtes

• Modellseite von Recraft Creative Upscale
• API-Leitfaden zu Recraft Crisp Upscale
• API-Leitfaden zu Recraft Remove Background: erst hochskalieren, dann das Motiv freistellen
• Bildauflösung mit der hiapi API erhöhen
• hiapi-Preise

FAQ

Brauche ich einen Prompt? Nein. Die Modellseite beschreibt eine einzelne Bildeingabe ohne Prompt oder andere Einstellungen, und unser Request verwendete nur image_url.

Kann ich die Ausgabegröße wählen? Über die API nicht. Es gibt kein Skalierungsfeld; unsere 1254-px-Eingabe kam als 4096 px zurück.

Bleiben Text und Logos erhalten? Nicht garantiert. Details werden neu erzeugt, kleine Elemente können sich ändern, verwende für Assets mit Text daher Crisp Upscale.

Welches Ausgabeformat bekomme ich? In unserem Lauf WebP, ausgeliefert über eine temporäre URL, die abläuft – lade die Datei also sofort herunter.

Wie lange dauert es? Unser einzelner Lauf dauerte etwa eine Minute; baue deinen Client auf Wartezeiten in dieser Größenordnung aus.