So erhöhen Sie die Bildauflösung mit der hiapi-API: Ein 4K-Upscaling-Workflow

Wenn Sie ein niedrig aufgelöstes Produktfoto, ein kleines KI-generiertes Vorschaubild oder einen alten Scan haben und eine gestochen scharfe 2K/4K-Version benötigen, brauchen Sie dafür keinen dedizierten Super-Resolution-Dienst. Der einheitliche /v1/tasks-Endpunkt von hiapi ermöglicht es Ihnen, dieselbe Anfrage an mehrere Bildmodelle zu richten – Modelle, die ein vorhandenes Bild annehmen und es in einer höheren Auflösungsstufe neu zeichnen. Diese Anleitung zeigt den vollständigen, lauffähigen Ablauf: Aufgabe übermitteln, per Polling (oder Callback) auf das Ergebnis warten und anschließend die hochskalierte Datei herunterladen.

Eine ehrliche Vorabinformation: hiapi bietet derzeit (noch) kein dediziertes, pixelgenaues Super-Resolution-Modell an. Was Sie hier erhalten, ist generatives Upscaling – das Modell zeichnet Ihr Quellbild in der höheren Zielauflösung neu und folgt dabei einem Prompt, der es anweist, die Komposition beizubehalten und Details zu ergänzen. Bei Fotos und Illustrationen ist das meist genau das, was gemeint ist, wenn von „Bildauflösung erhöhen“ die Rede ist. Es handelt sich jedoch nicht um verlustfreie Interpolation. Wenn Sie also beispielsweise einen Screenshot mit kleiner Schrift bitgenau skalieren müssen, ist dies nicht das richtige Werkzeug.

Was Sie erstellen und was Sie vorab vorbereiten müssen

Sie erstellen ein kleines Skript, das:

1. eine Referenz auf Ihr vorhandenes Bild hochlädt (jede öffentliche URL ist möglich – Ihr eigenes CDN, R2, S3 usw.)
2. eine Image-to-Image-Aufgabe übermittelt, die eine 4K-Neuzeichnung anfordert
3. abfragt, bis die Aufgabe abgeschlossen ist, und das Ergebnis mit höherer Auflösung herunterlädt

Vor dem Start:

• Ein hiapi-Konto und ein API-Schlüssel, den Sie auf der Seite API Keys im Dashboard erstellen. Jede Anfrage unten benötigt Authorization: Bearer sk-<your-key> – ohne Schlüssel können diese Endpunkte nicht aufgerufen werden.
• Eine öffentlich erreichbare URL, die auf das Bild verweist, das Sie hochskalieren möchten. Die Task-Worker von hiapi laden das Bild serverseitig ab, daher funktionieren localhost-Pfade oder private Buckets nicht – laden Sie es zuerst auf einen beliebigen öffentlichen Host hoch.
• Python 3.8+ mit installiertem requests (pip install requests), oder curl, wenn Sie lieber in der Shell testen möchten.

Minimales lauffähiges Beispiel

Die sauberste Wahl ist seedream-5.0-lite/image-to-image. Sein Eingabeschema verlangt genau vier Felder – prompt, image_urls, aspect_ratio und resolution – wobei resolution nur 2K oder 4K akzeptiert (auf dieser Route gibt es keine 1K-Stufe, was genau bedeutet, dass Sie Ihr Bild nicht versehentlich verkleinern können).

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_upscale_task(source_image_url: str) -> str:
    payload = {
        "model": "seedream-5.0-lite/image-to-image",
        "input": {
            "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
            "image_urls": [source_image_url],
            "aspect_ratio": "1:1",   # match your source image's ratio
            "resolution": "4K",
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    task_id = body["data"]["taskId"]
    return task_id

def wait_for_result(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_upscale_task("https://your-cdn.example.com/product-photo-small.jpg")
    result_url = wait_for_result(task_id)
    print("4K result:", result_url)

Wenn Sie nur sehen möchten, wie die Anfrage aussieht, hier der äquivalente Aufruf zur Aufgabenerstellung mit curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-hiapi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Same image, preserved composition and colors, sharp fine detail, no artifacts",
      "image_urls": ["https://your-cdn.example.com/product-photo-small.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "4K"
    }
  }'

Ein paar Hinweise zu dieser Anfrage:

• image_urls ist ein Array, auch wenn dieses Modell nur das erste Element liest. Einen reinen String statt einer Liste zu übergeben, ist eine häufige Ursache für 400.
• Ausgabe-URLs laufen ab. Sobald wait_for_result() zurückkehrt, laden Sie die Bytes sofort herunter und speichern Sie sie selbst – betrachten Sie von hiapi gehostete Links nicht als Ihre dauerhafte Asset-URL.
• Wenn Ihr Quellbild nicht quadratisch ist, setzen Sie aspect_ratio passend (4:3, 16:9, 9:16, 3:2, 2:3 oder 21:9), damit das Modell Ihr Motiv nicht zuschneidet oder auffüllt.

Vorgehen im Produktivbetrieb

Bei Skalierung Callbacks statt Polling bevorzugen. Wenn Sie mehr als nur ein paar Bilder hochskalieren, hämmern Sie nicht in einer Schleife auf GET /v1/tasks/<id> für jede Aufgabe ein – übergeben Sie stattdessen ein callback-Objekt, damit hiapi Ihnen die Ergebnisse zustellt:

payload = {
    "model": "seedream-5.0-lite/image-to-image",
    "input": {...},
    "callback": {
        "url": "https://your-service.example.com/hooks/hiapi-task",
        "when": "final",
    },
}

Ihr Webhook empfängt dasselbe Aufgabenobjekt wie beim Polling (status, output, error) – validieren Sie dessen Struktur defensiv, da Netzwerk-Wiederholungen es mehr als einmal zustellen können.

Halten Sie auf Ihrer Seite einen idempotenzfreundlichen Schlüssel pro Aufgabe bereit. Die Task-API akzeptiert derzeit keine vom Client bereitgestellten Idempotenzschlüssel. Wenn Ihr Task-Runner fehlgeschlagene HTTP-Aufrufe wiederholen kann, prüfen Sie daher, ob für dieses Quellbild bereits eine taskId gespeichert wurde, bevor Sie eine doppelte Aufgabe übermitteln – andernfalls kann aus einem kurzen Timeout auf Ihrer Seite ein doppelt abgerechnetes Upscaling derselben Datei werden.

Behandeln Sie zwei grundlegend verschiedene Fehlerformen. Ein fehlerhafter Request-Body liefert HTTP 400 mit einem flachen {"code": 400, "error_code": "INVALID_REQUEST", "message": "..."}. Ein fehlender oder falscher API-Schlüssel liefert HTTP 401 mit einem verschachtelten {"error": {"code": "permission_denied", "message": "..."}}. Prüfen Sie zuerst den Statuscode und verzweigen Sie dann:

if resp.status_code == 401:
    raise RuntimeError(f"auth error: {resp.json()['error']['message']}")
if resp.status_code == 400:
    raise RuntimeError(f"bad request: {resp.json()['message']}")
resp.raise_for_status()

Wählen Sie das Modell danach, welche Eingabe Sie haben. Die drei folgenden Routen liegen alle auf demselben /v1/tasks-Endpunkt – nur der model-String und die input-Felder unterscheiden sich:

Was Sie haben	Modell	Pflicht-Eingabefelder
Ein vorhandenes Bild, Sie möchten eine saubere 2K/4K-Neuzeichnung	seedream-5.0-lite/image-to-image	prompt, image_urls, aspect_ratio, resolution (2K|4K)
Ein vorhandenes Bild, Sie möchten zwischen Qualität und Kosten abwägen	gpt-image-2/image-to-image@ext	prompt, image_urls, quality (low|medium|high), resolution (1K|2K|4K)
Kein Quellbild – neue hochauflösende Assets aus einer Textbeschreibung generieren	wan2.7-image/text-to-image	prompt (plus optional resolution und aspect_ratio)

Beachten Sie das @ext-Suffix in der zweiten Zeile – es ist eine Routenvariante des Basis-Modells gpt-image-2 (hiapi stellt bestimmte Modelle unter mehr als einer Route mit leicht abweichenden Preis-/Qualitätsstufen bereit) und keine eigenständige Modellfamilie. Die exakten Kosten pro Anfrage für jedes dieser Modelle hängen von der gewählten Auflösungs- und Qualitätsstufe ab. Prüfen Sie daher die aktuellen Zahlen auf der Seite Preise, statt Werte in Ihrer Budgetlogik fest zu verdrahten.

Vor dem Übermitteln validieren. Alle drei Modelle lehnen unbekannte Eingabefelder direkt ab (additional properties 'x' not allowed), statt sie stillschweigend zu ignorieren, und Enum-Felder wie resolution und aspect_ratio reagieren empfindlich auf Groß-/Kleinschreibung und Werte. Wenn Sie eine Wrapper-Schicht bauen, validieren Sie clientseitig anhand der oben genannten exakten Enum-Werte, damit Tippfehler schnell fehlschlagen, statt eine Anfrage zu verbrauchen.

Weiterführende Lektüre

• Wan 2.7 Image — Text-to-Image-API, um allein aus einem Prompt neue hochauflösende Bilder zu generieren.
• GPT Image 2 API, die in der Tabelle oben verwendete Alternative mit Qualitäts-/Auflösungsstufen.
• hiapi API-Preise, um die aktuellen Kosten pro Anfrage für jedes Modell und jede Stufe einzusehen.
• hiapi-Dokumentation, um die vollständige Referenz zum Task-Lebenszyklus inklusive aller Callback-Optionen zu erhalten.

Häufig gestellte Fragen

Hat hiapi ein dediziertes Bild-Upscaling- oder Super-Resolution-Modell? Es gibt kein dediziertes pixelgenaues Modell. Der obige Workflow verwendet allgemeine Image-to-Image-Modelle, die Ihr Bild in einer höheren Auflösungsstufe neu generieren. Das funktioniert bei Fotos und Illustrationen gut, ist aber kein verlustfreies Upscaling.

Kann ich die Auflösung erhöhen, ohne den Bildinhalt zu verändern? Sie können sehr nahe herankommen, indem Sie das Modell anweisen, Komposition, Farben und Motiv exakt beizubehalten („dasselbe Bild, Komposition nicht verändern, keine Elemente hinzufügen oder entfernen, nur Details und Schärfe erhöhen“). Da es sich jedoch um generative Neuzeichnung und nicht um Interpolation handelt, bleiben bei feinen Texturen im Vergleich zu einem echten verlustfreien Upscaler geringfügige Unterschiede.

Was ist die maximale Auflösung, die ich erzeugen kann? Die Obergrenze aller drei oben genannten Modelle ist die Auflösungsstufe 4K. Wenn Sie eine größere Größe benötigen, müssen Sie das Quellbild in Kacheln aufteilen, die einzelnen Bereiche separat hochskalieren oder nach dem API-Aufruf einen clientseitigen Skalierungsschritt ergänzen.

Brauche ich einen API-Schlüssel, um das auszuprobieren? Ja – jeder Aufruf von /v1/tasks erfordert Authorization: Bearer sk-<your-key>. Es gibt keine Sandbox ohne Schlüssel für das Erstellen von Aufgaben; holen Sie sich zuerst einen Schlüssel vom Dashboard.

Kann ich einen ganzen Ordner voller Bilder im Batch hochskalieren? Ja – iterieren Sie über Ihre Bild-URLs, übermitteln Sie pro Bild eine Aufgabe und fragen Sie dann entweder jede taskId ab oder (bei größeren Mengen besser) registrieren Sie eine Callback-URL und ordnen Sie Ergebnisse über die beim Erstellen jeder Aufgabe gespeicherte taskId Ihren Aufgaben zu.

Warum schlägt meine Anfrage mit „additional properties not allowed“ fehl? Sie haben ein Feld gesendet, das das Modell-Schema nicht kennt – zum Beispiel size statt resolution + aspect_ratio, oder Sie haben einen überflüssigen Parameter aus dem Beispiel eines anderen Modells übernommen. Prüfen Sie die obige Tabelle der Pflichtfelder, um die exakten Feldnamen zu sehen, die jedes Modell akzeptiert.