So verwendest du die kling-3.0-omni/transformation API: Videorestyle mit curl und Python

kling-3.0-omni/transformation ist das Video-zu-Video-Modell von Kling 3.0 Omni: Du übergibst ein Quellvideo und einen Text-Prompt, und es schreibt das Aussehen dieses Videos neu — Szene, Stil, Motiv —, während die ursprüngliche Bewegung und zeitliche Abfolge erhalten bleiben. Auf hiapi rufst du es über denselben einheitlichen asynchronen Endpunkt auf wie alle anderen generativen Modelle: POST /v1/tasks. Dieser Leitfaden enthält eine praxiserprobte Parametertabelle, direkt kopierbare curl-Anfragen, einen vollständigen Python-Client (der abfragt und Ergebnisse herunterlädt) sowie die Produktionsmuster (Callbacks, Idempotenz, Fehlerbehandlung), die du benötigst, bevor du es in eine echte Anwendung integrierst.

Jeder Feldname, jeder Enum-Wert und jede Antwortstruktur unten wurde gegen die echte API geprüft.

Was du baust + Voraussetzungen

Ein kleines Programm: einen Restyle-Task einreichen, auf dessen Abschluss warten und dann das neu gestylte .mp4 herunterladen. Du brauchst zwei Dinge:

1. Einen hiapi-API-Schlüssel. Erstelle einen in der hiapi-Konsole — er hat das Format sk-.... Jede Anfrage verwendet Authorization: Bearer sk-<your-key>.
2. Eine öffentlich erreichbare Quellvideo-URL. Das Modell lädt dein Video serverseitig herunter, daher muss es eine öffentliche http(s)-URL sein (dein eigener CDN, R2/S3 mit öffentlichen Objekten usw.), kein lokaler Dateipfad. Es ist nur eine URL erlaubt.

Das Modell und seine Parameter

Die äußere Anfragestruktur ist {"model": ..., "input": {...}}. Das Schema von input ist strikt — es akzeptiert nur die folgenden drei Felder, jedes zusätzliche Feld wird mit 400 abgelehnt.

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Beschreibt den Zielstil/die Szene/das Motiv. Auch die Restyle-Stärke wird hier gesteuert — es gibt keinen numerischen Parameter strength/fidelity.
video_urls	array	Ja	Genau eine öffentliche Quellvideo-URL (minItems ist 1, maxItems ist 1).
resolution	string-Enum	Ja	Einer von 720p, 1080p, 4k.

Ein paar Stolperfallen:

• Kein duration-Parameter. Ausgabedauer und Seitenverhältnis folgen dem Quellvideo (3–15,5 Sekunden), und die Abrechnung erfolgt nach der Dauer der endgültigen Ausgabe.
• Die Modell-ID selbst enthält -omni: kling-3.0-omni/transformation (einige andere Omni-Endpunkte verwenden kling-3.0/...). Verwende diese ID direkt als Wert von model.
• Die Restyle-Stärke wird durch den Prompt gesteuert. Für eine leichte Änderung schreibe „leichtes Restyle, Gesichtszüge und Beleuchtung beibehalten“; für eine starke Änderung schreibe „vollständig als 2D-Cel-Animation neu interpretieren“.

Minimales lauffähiges Beispiel (curl)

# 1) Restyle-Task erstellen
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/transformation",
    "input": {
      "prompt": "Style diese Szene als handgezeichnete Aquarellanimation mit sanfter Papiertextur und warmem Abendlicht neu; behalte die ursprüngliche Kamerabewegung und das Motiv bei.",
      "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
      "resolution": "720p"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2) Task abfragen, bis er einen Endzustand erreicht
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01... \
  -H "Authorization: Bearer sk-<your-key>"
# data.status ist nacheinander: queued -> handling -> archiving -> success
# Nach Erfolg ist data.output[0].url die neu gestylte .mp4

Die Task-ID, mit der du abfragst, stammt aus data.taskId in der Erstellungsantwort — nicht aus der obersten id. Die Status-Strings sind queued / handling / archiving / success (Endzustand) oder fail; gehe nicht von succeeded/completed aus.

Vollständiger Python-Client (Erstellen → Abfragen → Herunterladen)

import os
import time
import requests

API_KEY = os.environ["HIAPI_KEY"]            # dein sk-...-Schlüssel
BASE = "https://api.hiapi.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_restyle(source_video_url: str, prompt: str, resolution: str = "720p") -> str:
    body = {
        "model": "kling-3.0-omni/transformation",
        "input": {
            "prompt": prompt,
            "video_urls": [source_video_url],   # genau eine öffentliche URL
            "resolution": resolution,           # "720p" | "1080p" | "4k"
        },
    }
    r = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"Übermittlung abgelehnt: {data}")
    return data["data"]["taskId"]


def wait_for_video(task_id: str, poll_s: int = 10, timeout_s: int = 900) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"Task fehlgeschlagen: {data.get('error')}")
        time.sleep(poll_s)                      # queued / handling / archiving
    raise TimeoutError(f"{task_id} wurde nicht innerhalb von {timeout_s} Sekunden abgeschlossen")


if __name__ == "__main__":
    task_id = create_restyle(
        source_video_url="https://your-cdn.example.com/source-clip.mp4",
        prompt=(
            "Style diese Szene als handgezeichnete Aquarellanimation mit sanfter Papiertextur "
            "und warmem Abendlicht neu; behalte die ursprüngliche Kamerabewegung und das Motiv bei."
        ),
        resolution="720p",
    )
    print("Task:", task_id)

    url = wait_for_video(task_id)
    print("Video-URL:", url)

    # Die Ausgabedatei liegt auf temp.hiapi.ai und läuft ab (ca. 7 Tage). Lade sie jetzt sofort herunter.
    clip = requests.get(url, timeout=120).content
    with open("restyled.mp4", "wb") as f:
        f.write(clip)
    print("restyled.mp4 gespeichert", len(clip), "Bytes")

Setze den Schlüssel in eine Umgebungsvariable und führe es aus:

export HIAPI_KEY=sk-<your-key>
python restyle.py

Produktionsmuster

Callbacks statt häufiges Polling

Für alles, was über ein Skript hinausgeht, registriere einen Webhook, damit du keine Polling-Schleife aufrechterhalten musst. callback ist ein oberstes Feld — auf derselben Ebene wie model und input, niemals innerhalb von input:

{
  "model": "kling-3.0-omni/transformation",
  "input": {
    "prompt": "Style diese Szene als 2D-Cel-Animation mit kräftigen Konturen neu; behalte die ursprüngliche Bewegung bei.",
    "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
    "resolution": "1080p"
  },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

• callback.when akzeptiert nur final (Standardwert). Wenn der Task einen Endzustand erreicht, wird er einmal in die Warteschlange gestellt, und zwar sowohl bei Erfolg als auch bei Fehler. Die Zustellungs-Semantik ist At-Least-Once, daher kann derselbe Callback mehrfach eintreffen (siehe unten).
• Der zugestellte POST-Request-Body ist identisch mit dem data-Objekt, das du über GET /v1/tasks/<id> erhältst — dein Handler kann also status, output[].url und error lesen, ohne erneut abzufragen.
• Wenn du callback in input platzierst, schlägt die Übermittlung mit dem Fehler additional properties 'callback' not allowed fehl (das input-Schema jedes Modells ist strikt).

Idempotenz und Zustellungs-Semantik

Callbacks sind At-Least-Once und nicht Exactly-Once — dieselbe taskId kann mehrfach eintreffen. Verwende taskId als Schlüssel deines Handlers und gestalte den Schritt „als abgeschlossen markieren + Video speichern“ idempotent. hiapi wiederholt Callbacks, die nicht 2xx sind oder die ein Timeout hatten, im Rhythmus sofort → +1 Minute → +5 Minuten → +20 Minuten, maximal 4 Versuche; dein Endpunkt muss HTTP 2xx zurückgeben, damit die Wiederholungen aufhören.

Ausgabe sofort herunterladen

data.output[0].url zeigt auf temp.hiapi.ai und enthält ein expireAt (Unix-Zeitstempel, ca. 7 Tage TTL). Nach Ablauf werden die Objekte gelöscht und die URL liefert 404 — ein erneutes Abfragen des Tasks liefert dieselbe URL, generiert die Datei aber nicht neu. Kopiere die Bytes sofort in deinen eigenen Speicher, sobald der Task erfolgreich ist.

Fehlerbehandlung

Drei Fehlerformen, die du in deinem Code unterscheiden musst:

• Anfragefehler (HTTP 400) — flache Struktur, kein Task erstellt: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: resolution: value must be one of '720p', '1080p', '4k'"}
• Authentifizierungsfehler (HTTP 401) — verschachtelte Struktur: {"error":{"code":"permission_denied","type":"hiapi_error", ...}}
• Task-Fehler — die Übermittlung gibt 200 und eine taskId zurück, aber eine spätere Abfrage zeigt data.status == "fail" mit data.error. Fehlgeschlagene Tasks werden nicht berechnet (der vorab belastete Betrag wird zurückerstattet, wenn der Task endgültig fehlschlägt). Fälle, in denen die Quell-URL nicht erreichbar oder nicht herunterladbar ist, zeigen sich hier.

Kosten

kling-3.0-omni/transformation wird nach Ausgabesekunden abgerechnet, wobei der Tarif von der angefragten Auflösung abhängt (720p $0,143 pro Sekunde, 1080p $0,193 pro Sekunde, 4k $0,479 pro Sekunde, geprüft am 21. Oktober 2026). Bevor du Videos in Massen verarbeitest, prüfe die aktuelle hiapi-Preisseite auf die gegenwärtigen Sekundentarife — die Kosten von Video-Tasks summieren sich viel schneller als bei Bild-Tasks.

Weiterführende Lektüre

• Modellseite und Spezifikationen: kling-3.0-omni/transformation auf hiapi
• Endpunkt-Referenz: Task erstellen — einheitliche asynchrone API
• Tutorial zur gleichen Modellfamilie am selben Endpunkt: Kling AI Image-to-Video-API in Python

Häufige Fragen

Wie steuere ich die Restyle-Stärke? Über den Prompt, nicht über Parameter. Es gibt kein Feld strength, fidelity oder creativity. Eine leichte Bearbeitung schreibst du als „leichtes Restyle, Gesicht und Beleuchtung beibehalten“, eine starke Bearbeitung als „vollständig neu interpretieren als