Tutorial

So verwendest du seedream-5.0-flash über die hiapi API: curl, Python und ausführbare Anfragen

Oct 8, 2026

Was du baust

Eine lauffähige Integration, die das Bildmodell seedream-5.0-flash von hiapi aus curl und Python aufruft: Text-zu-Bild-Anfrage (oder Bildbearbeitung) einreichen, das Ergebnis abfragen und die Ausgabe-URL herunterladen. Am Ende hast du ein Skript, das du direkt in dein eigenes Projekt übernehmen kannst.

Voraussetzungen

Ein hiapi-Konto und ein API-Schlüssel. Zu erhalten in der hiapi-Konsole — der Schlüssel hat die Form sk-....
curl oder Python 3.8+ (pip install requests).
Keine Bildbearbeitungsbibliothek nötig — seedream-5.0-flash akzeptiert reine Prompts oder einen Prompt plus eine Eingabebild-URL zum Bearbeiten.

Vollständige Modellreferenz: seedream-5.0-flash auf hiapi und die API-Dokumentationsseite.

Minimales ausführbares Beispiel

hiapi stellt alle Generierungsmodelle über einen einheitlichen Endpunkt bereit: Du erstellst zuerst eine Aufgabe und fragst sie dann ab (oder empfängst einen Callback), bis sie abgeschlossen ist.

curl

# 1. Aufgabe erstellen
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. Abfragen bis zum Abschluss
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

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


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

Hinweise zum input-Objekt:

prompt (erforderlich, 1–5000 Zeichen) — was generiert werden soll, bzw. was geändert werden soll, wenn du zusätzlich image übergibst.
image (optional, String oder Array mit bis zu 10 URL/base64-data:image/...-URIs) — übergib diesen Parameter, um ein vorhandenes Bild zu bearbeiten/referenzieren, statt von Grund auf zu generieren. Bei reiner Text-zu-Bild-Generierung weglassen.
size (optional, Standard "2K") — einer der Presets 1K / 1.5K / 2K oder ein benutzerdefinierter WIDTHxHEIGHT-String wie "1536x1024" (Gesamtpixel 921.600–4.624.220, Seitenverhältnis zwischen 1:16 und 16:1).
output_format (optional) — "jpeg" oder "png".
background (optional, Standard "opaque") — setze es nur dann auf "transparent", wenn du ein Bild mit Alphakanal bearbeitest.

Die output[].url in der Antwort ist ein signierter, ablaufender Link (Feld expireAt) — lade ihn rechtzeitig herunter oder hoste ihn neu, statt diesen Hotlink langfristig zu speichern.

Produktionsmuster

Callbacks statt Polling verwenden

Bei Server-zu-Server-Integrationen überspringst du das Polling und lässt hiapi dich benachrichtigen, wenn die Aufgabe abgeschlossen ist. Füge neben model/input ein Objekt callback auf oberster Ebene hinzu (nicht in input verschachtelt):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" ist derzeit der einzige unterstützte Wert — wenn die Aufgabe einen Endzustand erreicht (success oder fail), erhält dein Endpunkt genau ein POST. Um Zustellwiederholungen zu vermeiden, dedupliziere nach taskId und bestätige, dass dein Endpunkt über HTTPS erreichbar ist, bevor du dich in der Produktion darauf verlässt.

Polling vs. Callback

Nutze Polling, wenn du prototypst, kurzlebige Skripte ausführst oder noch keinen öffentlichen HTTPS-Endpunkt hast. Einfach, erhöht aber die Latenz und das Anfragevolumen bei langsamen Aufgaben.
Nutze Callbacks, wenn du einen Dienst betreibst — keine verschwendeten Polling-Anfragen, du erfährst sofort, wenn eine Aufgabe abgeschlossen ist. Erfordert eine öffentlich erreichbare HTTPS-URL.

Idempotenz

Die Bildgenerierung selbst ist nicht idempotent (derselbe Prompt liefert nicht zweimal dasselbe Bild). Wenn dein Workflow also die Semantik "Wiederholen ohne doppelte Abrechnung" benötigt, verfolge taskId auf deiner Seite und prüfe nach einem Timeout den Aufgabenstatus, bevor du dieselbe Anfrage erneut einreichst, statt blind zu wiederholen.

Fehlerbehandlung

401 mit permission_denied — dein API-Schlüssel fehlt, ist falsch formatiert oder wurde widerrufen:
```
{"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
```
Prüfe genau, ob du Authorization: Bearer sk-... sendest (nicht nur den rohen Schlüssel) und ob der Schlüssel nicht rotiert wurde.
400 mit INVALID_REQUEST — ein Feld hat die Validierung nicht bestanden. Die message sagt dir genau, welches Feld und warum, z. B. ein size außerhalb des gültigen Bereichs. Korrigiere das Feld und reiche erneut ein; nicht unverändert wiederholen.
Fehler auf Aufgabenebene — der HTTP-Aufruf kann erfolgreich sein (200), während die Aufgabe nach Abschluss der Verarbeitung dennoch mit status: "fail" endet. Prüfe immer data.status in der Polling-/Callback-Antwort und nicht nur den HTTP-Statuscode des Erstellungsaufrufs.

Häufige Fragen

Ist seedream-5.0-flash kostenlos? Nein — es wird über deinen hiapi-API-Schlüssel pro Bild abgerechnet. Aktuelle Tarife findest du auf der Preisseite; ohne gültigen Schlüssel ist kein Produktivzugriff möglich.

Unterstützt seedream-5.0-flash Bild-zu-Bild-Bearbeitung und nicht nur Text-zu-Bild? Ja. Füge neben prompt das Feld image hinzu (URL oder base64-data:image/...-String oder ein Array mit bis zu 10), und das Modell bearbeitet/verschmilzt auf Basis des Referenzbilds, statt von Grund auf zu generieren.

Warum liefert meine Anfrage 200, aber kein Bild? Ein 200 von POST /v1/tasks bedeutet nur, dass die Aufgabe angenommen wurde — die Generierung ist asynchron. Frage GET /v1/tasks/<id> ab (oder warte auf den Callback) und prüfe data.status; die Bild-URL erscheint erst, wenn status gleich "success" ist.

Kann ich eine benutzerdefinierte Auflösung statt 1K/1.5K/2K anfordern? Ja — übergib size als "WIDTHxHEIGHT" (z. B. "1536x1024") statt eines Presets. Die Gesamtpixel müssen zwischen 921.600 und 4.624.220 liegen und das Seitenverhältnis zwischen 1:16 und 16:1, sonst gibt die Anfrage 400 zurück.

Was passiert nach einiger Zeit mit der Ausgabe-URL? Die zurückgegebene output[].url ist eine signierte URL mit expireAt-Zeitstempel — sie ist kein dauerhafter Speicher. Lade die Bytes nach erfolgreicher Aufgabe so bald wie möglich herunter oder kopiere sie in deinen eigenen Speicher.

Mein Callback wurde nie ausgelöst — was sollte ich zuerst prüfen? Stelle sicher, dass deine callback.url ein öffentlich erreichbarer HTTPS-Endpunkt ist (nicht localhost oder eine rein interne Adresse) und dass callback ein Feld auf oberster Ebene im Anfragetext ist — nicht in input verschachtelt.

Wichtigste Erkenntnisse

seedream-5.0-flash wird wie alle anderen Generierungsmodelle über den einheitlichen Endpunkt POST /v1/tasks von hiapi aufgerufen.
Übergib bei reiner Text-zu-Bild-Generierung nur den Prompt oder füge das Feld `image` hinzu (URL oder base64, bis zu 10), um ein vorhandenes Bild zu bearbeiten/referenzieren.
Skripte und Prototypen pollen GET /v1/tasks/<id>; Produktivdienste verwenden `callback.url` auf oberster Ebene zusammen mit `when:"final"`.
401 permission_denied bedeutet, dass der API-Schlüssel ungültig oder widerrufen ist; 400 INVALID_REQUEST bedeutet, dass ein Feld (meist `size`) die Validierung nicht bestanden hat.
Ausgabe-URLs sind signiert und laufen ab — lade sie rechtzeitig herunter oder hoste sie neu, statt den Hotlink zu speichern.