Tutorial

So änderst du den Stil von Bildern mit KI: Ein Leitfaden zur Bild-zu-Bild-Stilübertragung mit der hiapi API

Sep 4, 2026

Einem Foto mit KI einen neuen Stil zu geben – ein Schnappschuss wird zum Animationsframe, zum Studio-Produktbild oder zur Aquarellillustration – ist kein spezieller „Style-Transfer"-Endpunkt. Es ist ein ganz normaler Bild-zu-Bild-Aufruf: Du sendest ein Quellbild und eine Textanweisung, die den Zielstil vorgibt, und das Modell gibt ein neues Bild zurück. Was wirklich entscheidet, ob du einen sauberen Stilwechsel oder eine halbe Neugenerierung bekommst, ist die Art, wie du diese Anweisung formulierst, und nicht irgendein einstellbarer Parameter. Dieser Leitfaden beschreibt den Anfragemechanismus auf der einheitlichen Tasks-API von hiapi, die Prompt-Muster, die verhindern, dass der Stilwechsel zu einem neuen Bild entgleist, und wie du zwischen zwei validierten Bild-zu-Bild-Modellen wählst, je nachdem, wie viel kreative Freiheit du willst.

Was du vorbereiten musst

Einen hiapi API-Schlüssel – bekommst du in deinem Dashboard. Er gehört in den Authorization: Bearer sk-...-Header jeder Anfrage.
Eine öffentlich erreichbare URL des Quellbilds. Die hiapi-Server holen das Bild selbst ab, daher funktionieren localhost-Pfade oder private Buckets ohne signierte URL nicht. Vor-signierte S3/R2/GCS-URLs sind in Ordnung.

Jede Modell-ID und jedes Feld unten wurde vor der Veröffentlichung gegen die Live-API erneut verifiziert, einschließlich einer erzwungenen Fehlerprüfung, um die aktuellen Enum-Werte zu bestätigen.

Warum ein Stilwechsel eine „Beibehaltungsklausel" braucht

Keines der beiden Modelle in diesem Leitfaden bietet einen numerischen Intensitäts- oder Stärkeparameter – sendest du einen (strength: 0.5), wird er direkt abgelehnt mit dem Fehler additional properties 'strength' not allowed. Die Stilintensität wird vollständig durch die Prompt-Formulierung gesteuert, was bedeutet, dass eine Anweisung wie "make this a Studio Ghibli anime frame" dem Modell nur sagt, was hinzugefügt werden soll, aber nicht, was unverändert bleiben muss – Subjektidentität, Pose und Komposition können vom Modell frei neu interpretiert werden.

Die Lösung besteht darin, im Prompt immer zwei Teilsätze zu schreiben:

Den Zielstil, ausgedrückt durch einen konkreten visuellen Bezug (ein Medium, eine Kunstrichtung, eine bestimmte Optik – „anime cel-shading", „1970s film photography", „clean studio product shot on white"), nicht durch ein vages Adjektiv wie „cooler".
Eine ausdrückliche Beibehaltungsklausel – benenne, was sich nicht ändern darf: „keep the same subject, pose, and composition", „keep the text and logo unchanged", „keep the camera angle".

Ein Prompt wie "Restyle this photo as a woodblock print. Keep the subject's pose, framing, and the position of every object in the scene." gibt dem Modell in einer einzigen Anweisung ein Ziel und eine Einschränkung – das ist der größte Hebel, um einen Stilwechsel statt einer Neugenerierung zu erhalten.

Minimal funktionierendes Beispiel: curl

Dieses Beispiel nutzt seedream-5.0-pro/image-to-image, das Stilwechsel hervorragend umsetzt und ein striktes, vollständig verifiziertes Schema hat:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Restyle this portrait as a watercolor painting with visible brush texture and soft bleeding edges. Keep the subject'\''s pose, expression, and framing exactly as in the source.",
      "image_urls": ["https://your-bucket.example.com/portrait.jpg"],
      "aspect_ratio": "3:4",
      "resolution": "2K"
    }
  }'

aspect_ratio ist ein Pflichtfeld aus einem festen Enum – derzeit 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9. Dieser Endpunkt hat keine Option „Quellbild übernehmen", wähle also den Wert, der dem tatsächlichen Seitenverhältnis des Quellbilds am nächsten kommt (Hochformatfoto → 3:4 oder 9:16, nicht 16:9), damit das Modell die Komposition nicht mit Rändern auffüllt oder zuschneidet, um sie anzupassen.

Nach erfolgreicher Erstellung wird die Task-ID in data.taskId zurückgegeben:

{ "data": { "taskId": "<your-task-id>" } }

Polling, bis ein Endzustand erreicht ist:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status wird schließlich success (Ausgabe unter data.output[0].url) oder fail (Details unter data.error).

Vollständiges Python-Skript: Erstellen, Polling, Herunterladen

Nur mit der Standardbibliothek:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the restyle task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": (
            "Restyle this street photo as a 1980s film-grain photograph with warm, "
            "faded colors. Keep the same subject, pose, and every object in the "
            "same position in the frame."
        ),
        "image_urls": ["https://your-bucket.example.com/street.jpg"],
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "restyled.png")
print("saved restyled.png")

Wähle das Modell nach der gewünschten kreativen Freiheit

Beide Modelle wurden online erneut verifiziert und keines akzeptiert einen strength-Parameter, aber sie unterscheiden sich darin, wie stark du den Einfluss des Quellbilds kontrollieren kannst:

	`seedream-5.0-pro/image-to-image`	`grok-imagine-quality/image-to-image`
Referenzbilder	1–10 öffentliche URLs	1–3 öffentliche URLs
`resolution`	`1K` / `2K` (Großbuchstaben)	`1k` / `2k` (Kleinbuchstaben) – optional
Kompositionskontrolle	Festes Enum mit 8 Werten für `aspect_ratio`, kein Auto-Matching	`aspect_ratio: "auto"` folgt dem Eingabebild
Am besten geeignet für	Präzise Stilwechsel mit einer Referenz, wenn du das Zielverhältnis kennst	Schnelle Stilwechsel, bei denen die Ausgabe die exakte Komposition des Quellbilds erben soll, ohne dass du das Verhältnis selbst wählen musst

Wenn deine Beibehaltungsklausel „same framing" enthält und du das Seitenverhältnis des Quellbilds nicht manuell berechnen willst, ist grok-imagine-quality/image-to-image mit aspect_ratio: "auto" der direktere Weg – ersetze es in der obigen Anfrage, image_urls bis zu 3, resolution auf kleingeschriebenes 2k gesetzt.

Hinweise für den Produktivbetrieb

Bevorzuge auf dem Server Callbacks statt Polling. Füge bei der Anfrage ein callback-Objekt hinzu, und hiapi sendet im Endzustand genau ein POST, statt dass du pollen musst:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Behandle die Callback-Nutzlast als Signal und nicht als Wahrheitsquelle – entnimm ihr die Task-ID und rufe vor dem Handeln selbst erneut GET /v1/tasks/<id> ab. Für Skripte und Notebooks reicht Polling alle 5 Sekunden.

Mache Wiederholungen idempotent. Speichere beim Erstellen der Task deine eigene Zuordnung Quellbild → taskId. Stürzt dein Prozess mitten im Polling ab, solltest du nach dem Neustart die gespeicherte taskId wiederverwenden statt neu einzureichen – eine erneute Einreichung ist eine zweite abgerechnete Task.

Fehler, die dir tatsächlich begegnen werden:

401 permission_denied – Schlüssel falsch formatiert oder fehlend. Der Header muss exakt Authorization: Bearer sk-... sein.
400 INVALID_REQUEST – Schema-Verstoß, z. B. aspect_ratio: value must be one of '1:1', '4:3', ... oder additional properties 'strength' not allowed. Die Schemata beider Modelle sind strikt – übertrage keine Parameter zwischen Modellfamilien.
image_urls must be an array – ein nackter String statt einer Liste wurde übergeben, selbst bei nur einem Referenzbild.

Häufig gestellte Fragen

Gibt es einen Intensitäts- oder Stärkeregler für die Stilübertragung? Nein. Keines der beiden Modelle in diesem Leitfaden akzeptiert das Feld strength – sendest du es, wird es als unbekanntes Attribut abgelehnt. Die Stilintensität wird vollständig dadurch gesteuert, wie konkret und stark die Stilbeschreibung im Prompt ist.

Wie verhindere ich, dass das Modell die Pose oder Identität meines Motivs ändert? Füge dem Prompt eine ausdrückliche Beibehaltungsklausel hinzu, die benennt, was unverändert bleiben muss – Pose, Ausdruck, Komposition, Objektpositionen. Wenn Einschränkungen ausdrücklich geschrieben statt nur angedeutet werden, wechselt das Modell den Stil konservativer.

Kann ich das exakte Seitenverhältnis des Quellbilds automatisch beibehalten? Bei grok-imagine-quality/image-to-image ja – setze aspect_ratio: "auto". Bei seedream-5.0-pro/image-to-image gibt es keine Auto-Option; wähle aus dem festen Enum den Wert, der dem tatsächlichen Seitenverhältnis des Quellbilds am nächsten kommt.

Müssen meine Quellbilder öffentliche URLs sein? Sie müssen von den hiapi-Servern über HTTPS abrufbar sein. Vor-signierte URLs privater Buckets funktionieren; localhost oder nicht authentifizierte und nicht erreichbare Pfade nicht.

Kann ich aus einem Foto mehrere Stilvarianten parallel erzeugen? Ja – jede Variante ist eine eigene Task. Starte mehrere POST /v1/tasks-Aufrufe mit denselben image_urls und unterschiedlichen Stilanweisungen und polle dann jede taskId separat oder nutze Callbacks.

Was ist der Unterschied zwischen Stilwechsel und Inpainting bzw. Objektentfernung? Ein Stilwechsel ändert die Darstellung des gesamten Bildes, während der Inhalt gleich bleibt; Inpainting/Objektentfernung ändert bestimmte Bereiche, während der Darstellungsstil gleich bleibt. Es sind unterschiedliche Prompt-Muster auf derselben Art von Bild-zu-Bild-Endpunkt – wenn du eigentlich Inpainting und Objektentfernung brauchst, siehe den Leitfaden zu Inpainting und Objektentfernung.

Wichtigste Erkenntnisse

Schreibe Stilwechsel-Prompts in zwei Teilen: zuerst den Zielstil, dann eine ausdrückliche Beibehaltungsklausel, die benennt, was sich nicht ändern darf (Pose, Komposition, Objektpositionen).
Keines der beiden verifizierten Modelle hat einen Intensitäts-/Stärkeparameter – die Stilintensität kommt allein aus der Stärke der Stilbeschreibung im Prompt.
seedream-5.0-pro/image-to-image hat für aspect_ratio ein festes Enum mit 8 Werten und keine Auto-Match-Option; wähle selbst das Verhältnis, das dem Quellbild am nächsten kommt.
grok-imagine-quality/image-to-image unterstützt aspect_ratio: "auto" und folgt damit der Komposition des Eingabebilds – nützlich, wenn du das Verhältnis nicht manuell berechnen willst.
Nutze auf Servern callback.url mit when:"final" statt Polling und speichere deine eigene Zuordnung Quellbild → taskId, damit ein Neustart nach einem Absturz die Task wiederverwendet statt sie neu einzureichen.