Tutorial
So rufen Sie kling-3.0-omni/transformation über die HiAPI-API auf: curl- und Python-Leitfaden
Ein vollständiger Durchlauf funktionierender Anfragen zur Videostiltransformation auf HiAPI
Auf dieser Seite
Funktion und Einsatzszenarien des transformation-Endpunkts
kling-3.0-omni/transformation ist ein Endpunkt zur Videostiltransformation auf HiAPI. Sie übergeben ihm zwei Dinge: ein Quellvideo und eine Stilanweisung in natürlicher Sprache. Er liefert ein neues Video zurück, in dem der Inhalt des Quellvideos erhalten bleibt, aber im gewünschten visuellen Stil erscheint.
Man kann ihn sich als Postproduktionsschritt vorstellen, der hinter einem HTTP-Aufruf verborgen ist. Sie müssen kein Modell trainieren, keinen GPU-Cluster betreiben und keine Checkpoint-Dateien verwalten. Sie beschreiben den gewünschten visuellen Effekt, verweisen auf ein Video, und der Endpunkt erzeugt das gerenderte Ergebnis.
Szenarien, für die sich der Endpunkt eignet
- Vorhandenem Material einen Stil verleihen. Sie haben bereits eine Aufnahme und möchten, dass sie als Animation, Aquarell, Filmkorn, Knetanimation oder ein anderer Effekt erscheint. Inhalt und Bewegung stammen aus Ihrem Video; der Endpunkt verändert die Oberflächenbeschaffenheit.
- Einen Stil konsistent über Batches hinweg halten. Da der Stil als Anweisung ausgedrückt wird, können Sie denselben Prompt auf vielen Quellvideos wiederverwenden und ein stilistisch stimmiges Set erhalten.
- Stilentwicklung prototypisch erproben. Kreativteams können Stilrichtungen kostengünstig durchspielen, bevor sie in aufwändigere Produktionsprozesse investieren.
Szenarien, für die er nicht geeignet ist
- Sie müssen ein Video von Grund auf generieren (Text-zu-Video ist eine andere Aufgabe).
- Sie benötigen frame-genaue Bearbeitung, Schnitt oder Compositing. Die Transformation formt nur den Stil um, sie schneidet nicht.
- Ihr Quellmaterial besteht nur aus Audio oder einem statischen Bild.
Der Rest dieses Leitfadens erklärt schrittweise die Anforderungsstruktur, einen direkt ausführbaren curl-Aufruf, die entsprechende Python-Version sowie operative Details rund um 4K-Ausgaben und lang laufende Aufgaben.
Anfrageanalyse: Quellvideo, Stilanweisung und Ausgabeoptionen
Eine Transformationsanfrage ist nicht kompliziert. Bevor Sie Code schreiben, unterteilen Sie sie in drei Gruppen von Feldern: Quellvideo, Anweisung und Ausgabeeinstellungen.
Quellvideo
Der Endpunkt benötigt Zugriff auf Ihre Eingabe. In der Praxis übergeben Sie entweder eine URL, die die Plattform abrufen kann, oder eine Kennung, die ein HiAPI-Dateiupload-Schritt zurückgegeben hat. Die praktische Regel lautet: Die Quelldatei muss vom Server aus erreichbar sein, nicht von Ihrem Laptop aus. Ein localhost-Pfad oder eine Datei hinter Ihrem VPN funktioniert nicht.
Halten Sie das Quellformat konservativ – verwenden Sie weit verbreitete Container und Codecs. Wenn Ihr Video von einer speziellen Pipeline erzeugt wurde und die Validierung nicht besteht, kodieren Sie es zunächst in Standard-H.264-MP4 neu. Dieser eine Schritt behebt einen großen Teil der Eingabefehler.
Stilanweisung
Dies ist die Beschreibung des gewünschten visuellen Effekts in natürlicher Sprache. Sie ist das einflussreichste Feld der Anfrage und dasjenige, das am meisten Feinschliff verdient.
- Beschreiben Sie die visuelle Verarbeitung, nicht den Inhalt. Der Inhalt stammt aus dem Video; dem Modell zu sagen, was bereits auf dem Bildschirm zu sehen ist, verschwendet nur Prompt-Budget.
- Seien Sie konkret in Bezug auf Medium und Textur: „Stop-Motion-Knetanimation mit sichtbaren Fingerabdruckspuren“ vermittelt mehr Informationen als „Animation“.
- Machen Sie explizit, was erhalten bleiben soll, wenn es wichtig ist: „Gesichter erkennbar halten, Kamerabewegung unverändert“.
- Bleiben Sie bei einem fokussierten Absatz. Lange, widersprüchliche Prompts mitteln sich oft zu nichtssagenden Ergebnissen aus.
Ausgabeoptionen
Die Ausgabeeinstellungen steuern Auflösung und weitere Ausgabedetails. Die wichtigste Entscheidung ist, ob 4K oder Standardauflösung angefordert wird. Höhere Auflösung verbraucht mehr Rechenleistung und dauert länger, daher sollte sie als bewusste Entscheidung und nicht als Standard behandelt werden. Der Endpunkt läuft im Allgemeinen als asynchrone Aufgabe, sodass Ihre Anfrage typischerweise eine Aufgabenreferenz zurückgibt, die Sie abfragen oder abwarten müssen, statt direkt die fertige Datei zu liefern.
Sobald Sie Ihre Eingaben diesen drei Feldgruppen zugeordnet haben, wird der eigentliche JSON-Anfragetext klar ersichtlich.
Ein funktionierender curl-Aufruf von Grund auf
Der schnellste Weg, das Verständnis zu bestätigen, ist ein minimaler Aufruf. Die folgende Form sendet eine Quellvideo-URL und eine Stilanweisung und fordert ein Ergebnis in Standardauflösung an. Ersetzen Sie die Platzhalterwerte durch Ihre eigenen.
curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": "In handgezeichnete Aquarellanimation umwandeln, weiche verlaufende Ränder, sichtbare Papiertextur, warme begrenzte Farbpalette. Gesichter und Kamerabewegung beibehalten.",
"resolution": "1080p"
}'
Welche Rolle die einzelnen Teile spielen
- Der URL-Pfad gibt den Endpunkt an. Er muss exakt stimmen; ein Tippfehler hier liefert einen Routing-Fehler statt eines Validierungsfehlers.
- Der
Authorization-Header trägt Ihren HiAPI-Schlüssel. Exportieren Sie ihn als Umgebungsvariable, statt ihn in die Shell-Historie einzufügen. video_urlist das Quellvideo. Es muss serverseitig abrufbar sein.promptist die Stilanweisung. Dies ist das Feld, das Sie am häufigsten ändern werden.resolutionist die Ausgabeeinstellung. Beginnen Sie beim Iterieren mit niedriger Auflösung und erhöhen Sie sie erst, wenn das Ergebnis feststeht.
Die Antwort interpretieren
Eine erfolgreiche Antwort liefert Ihnen ein Aufgabenobjekt. Notieren Sie die Aufgabenkennung und alle Statusfelder:
{
"id": "job_abc123",
"status": "queued"
}
Die genauen Feldnamen sollten Sie aus der Live-Antwort ablesen, nicht annehmen. Eine wichtige Gewohnheit ist in jeder Sprache dieselbe: JSON parsen, die Aufgaben-ID extrahieren und das fertige Video als etwas betrachten, das später eintrifft. Schreiben Sie keinen Code, der annimmt, die erste Antwort enthalte bereits eine abspielbare Datei.
Dieselbe Anfrage in Python
Die Python-Version ist der curl-Aufruf, wobei der JSON-Anfragetext als Dictionary ausgedrückt wird. Mit requests bleibt der Code lesbar und die Abhängigkeit leichtgewichtig.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": (
"In handgezeichnete Aquarellanimation umwandeln, weiche verlaufende Ränder, "
"sichtbare Papiertextur, warme begrenzte Farbpalette. Gesichter und Kamerabewegung beibehalten."
),
"resolution": "1080p",
}
resp = requests.post(
f"{BASE}/kling-3.0-omni/transformation",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))
Abpollen, bis die Aufgabe abgeschlossen ist
Da das Rendering asynchron ist, verpacken Sie das Warten in eine Schleife mit begrenzter Versuchszahl und einer Pause zwischen den Prüfungen. Wählen Sie die Pause großzügig genug, um die API nicht häufig anzufragen, und setzen Sie eine Obergrenze für die Gesamtwartezeit, damit eine hängende Aufgabe Ihren Worker nicht blockiert.
def wait_for_job(job_id, max_attempts=60, interval=10):
for _ in range(max_attempts):
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status == "failed":
raise RuntimeError(data.get("error") or "job failed")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish in time")
result = wait_for_job(job_id)
print(result.get("output") or result)
Produktionstauglich machen
- Lesen Sie Endpunktpfad und Polling-Route aus der API-Antwortdokumentation, statt Annahmen fest zu codieren, die sich ändern könnten.
- Protokollieren Sie die Aufgaben-ID beim Absenden. Wenn nachgelagerte Probleme auftreten, ist dies Ihr einziger Anhaltspunkt.
- Behandeln Sie
failedund Timeouts als unterschiedliche Ergebnisse. Fehlgeschlagene Aufgaben sind meist Parameterprobleme; Timeouts sind meist Kapazitäts- oder Dauerprobleme.
Umgang mit 4K-Ausgaben und lang laufenden Aufgaben
Zwei Variablen bestimmen das Betriebsverhalten dieses Endpunkts: die Ausgabeauflösung und die Eingabedauer. Planen Sie beides bewusst ein.
4K-Ausgabe
4K ist eine Lieferentscheidung, kein Standardwert. Jedes Ausgabepixel verbraucht Rechenleistung, und der relative Sprung von Standardauflösung auf 4K ist groß. Ein sinnvoller Workflow:
- Iterieren Sie die Stilanweisung bei niedrigerer Auflösung. Die Prompt-Qualität ist unabhängig von der Auflösung, also stimmen Sie den Effekt kostengünstig ab.
- Fixieren Sie Prompt und Quellvideo.
- Führen Sie für die Lieferung einmalig eine Neuausführung in 4K durch.
Vermeiden Sie es, 4K-Varianten in einer engen Schleife zu erzeugen, während Sie Formulierungen anpassen – das ist die häufigste Art, Budget für Renderings zu verschwenden, die am Ende verworfen werden.
Lang laufende Aufgaben
Längere Quellvideos brauchen länger für die Transformation, und der Endpunkt gibt eine Aufgabenreferenz statt einer fertigen Datei zurück. Bauen Sie Ihren Client um diese Realität herum:
- Lassen Sie niemals einen Web-Request auf das Rendering warten. Senden Sie ab, speichern Sie die Aufgaben-ID und geben Sie sofort an den Aufrufer zurück.
- Trennen Sie Absenden und Abrufen. Ein Worker mit Queue und Polling ist robuster als Inline-Warten und übersteht Prozessneustarts.
- Persistieren Sie den Aufgabenstatus. Wenn der Worker mitten im Polling stirbt, verschwindet die Aufgabe nicht; Sie können mit der gespeicherten ID wieder aufnehmen.
- Nutzen Sie Webhooks, wenn Ihr Account sie unterstützt, und behalten Sie Polling als Fallback bei.
- Setzen Sie ein Gesamt-Wartebudget, das Ihre erwartete längste Videodauer widerspiegelt, statt einer willkürlichen Zahl.
Ein praktisches Muster
Teilen Sie Quellvideos, die länger als die typische Dauer sind, in Segmente auf, transformieren Sie sie einzeln und setzen Sie die Ergebnisse zusammen. Das verkürzt die einzelne Wartezeit, lässt Sie nur ein Segment statt des gesamten Renderings erneut versuchen und macht Fehler günstig. Achten Sie darauf, dass die Segmentgrenzen keine schnellen Bewegungen durchschneiden, sonst fallen die Übergänge sichtbar auf.
Fehlerbehebung bei häufigen Störungen
Die meisten Störungen fallen in drei Kategorien: Quellvideo nicht lesbar, Parameter abgelehnt oder Aufgabe wird nie fertig. Isolieren Sie zuerst die Problemkategorie, bevor Sie irgendetwas ändern.
Upload- und Quellzugriffsfehler
Symptom: Das Absenden schlägt fehl, oder die Aufgabe scheitert fast sofort mit einem Eingabefehler.
- Die URL ist nicht öffentlich erreichbar. Testen Sie sie von einem Rechner außerhalb Ihres Netzwerks. Ablaufende signierte URLs zwischen Absenden und Abruf sind ein typischer Auslöser.
- Format nicht unterstützt. Kodieren Sie in Standard-H.264-MP4 neu und versuchen Sie es erneut.
- Datei abgeschnitten oder beschädigt. Laden Sie sie selbst herunter und spielen Sie sie vollständig ab.
- Anfrage zu groß. Wenn Sie Dateibytes inline statt per URL senden, verwenden Sie stattdessen den Upload-Workflow und übergeben die zurückgegebene Kennung.
Parameterfehler
Symptom: Beim Absenden kommt eine 4xx-Antwort zurück.
- Fehlerhaftes JSON. Prüfen Sie den Anfragetext mit einem Lint-Werkzeug. Nachgestellte Kommas und nicht maskierte Anführungszeichen sind häufige Fehler bei handgeschriebenen curl-Aufrufen.
- Falscher Feldname oder falscher Typ. Gleichen Sie mit dem aktuellen Anfrageschema ab; eine Auflösung als Zahl zu senden, wo ein String erwartet wird, schlägt fehl.
- Prompt leer oder widersprüchlich. Wenn die Anweisung nichts beschreibt oder sich gegenseitig ausschließende Stile verlangt, ist die erwartete Ausgabe schwach oder wird abgelehnt. Schreiben Sie sie um eine klare visuelle Richtung herum neu.
- API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Header-Wert und ob der Schlüssel für diesen Endpunkt gültig ist.
Timeouts und hängende Aufgaben
Symptom: Die Aufgabe bleibt nach Ablauf Ihres Wartebudgets im Status „queued“ oder „running“, oder Ihr Client gibt auf.
- Unterscheiden Sie Client-Timeout und Aufgabenfehler. Ein kurzes HTTP-Timeout beim Absenden bedeutet nicht, dass die Aufgabe nicht gestartet wurde; prüfen Sie vor einem erneuten Absenden, ob eine Aufgaben-ID existiert, sonst rendern Sie möglicherweise doppelt.
- Lange Eingaben und 4K-Ausgaben verlängern die Laufzeit. Wenn Sie wiederholt Timeouts bekommen, senken Sie die Auflösung oder kürzen Sie das Video, um zu bestätigen, dass der Ablauf funktioniert, und erhöhen Sie dann schrittweise wieder.
- Wenn die Aufgabe
failedmeldet, lesen Sie die Fehlermeldung, bevor Sie es erneut versuchen. Blindes Wiederholen bei deterministischen Parameterfehlern vervielfacht nur die Kosten.
Effektive Debug-Reihenfolge
Beginnen Sie mit der kleinstmöglichen Anfrage: ein kurzes Video in Standardauflösung und ein Prompt-Satz. Wenn das gelingt, führen Sie nacheinander den echten Prompt, die echte Dauer und zuletzt 4K wieder ein – jeweils nur eine Variable auf einmal. Der Schritt, an dem es scheitert, sagt Ihnen, welche Variable die Ursache ist.
Kosten- und Latenzabwägungen, die Sie planen sollten
Sobald die Anfrage funktioniert, sind die verbleibenden Entscheidungen operativer Natur. Drei Hebel beeinflussen Kosten und Latenz gleichzeitig und wirken zusammen.
Auflösung
Die Ausgabeauflösung ist der größte einzelne Hebel. Die Abrechnung hängt vom Arbeitsaufwand für das Rendering ab, und höhere Ausgabeauflösung bedeutet mehr Arbeit. Faustregel: bei niedriger Auflösung iterieren, in hoher Auflösung liefern. Lassen Sie Style-Experimente niemals in 4K laufen.
Eingabedauer
Längere Quellvideos bedeuten mehr zu transformierende Frames, also mehr Rechenleistung und mehr reale Wartezeit. Wenn Ihr Anwendungsfall es erlaubt, transformieren Sie einen kürzeren Highlight-Clip statt des vollständigen Schnitts, oder teilen Sie langes Material auf und transformieren Sie nur die Teile, die bearbeitet werden müssen.
Wiederholungen
Jeder erneute Versuch ist ein vollständiges Rendering, es sei denn, der Fehler tritt vor dem Start der Aufgabe auf. Deshalb ist die Debug-Reihenfolge wichtig: Validieren Sie Parameter kostengünstig, bevor Sie Geld für das Rendering ausgeben. Verhindern Sie doppelte Einreichungen, indem Sie die Aufgaben-ID protokollieren und vor einem erneuten Absenden nach einem Client-Timeout prüfen.
Batch-Verarbeitung und Parallelität
Parallele Aufgaben verkürzen die reale Wartezeit, nicht aber die Gesamtkosten – und sie können Parallelitätslimits erreichen. Für Batch-Arbeiten ist eine moderate Queue mit kontrollierter Parallelität meist besser als ein breites Fan-out. Sie bleiben unter den Rate-Limits, machen Fehler einzeln wiederholbar und erhalten eine vorhersehbare Ausgabenkurve.
Budget-Checkliste
- Legen Sie den Prompt bei niedriger Auflösung fest, bevor Sie ein Liefer-Rendering durchführen.
- Cachen Sie fertige Ausgaben; rendern Sie identische Eingaben nicht erneut.
- Setzen Sie Kostenerwartungen pro Aufgabe und pro Batch und alarmieren Sie, wenn ein Batch sie überschreitet.
- Verfolgen Sie die Aufgabendauer in Abhängigkeit von Auflösung und Eingabedauer, um neue Arbeiten aus vergangenen Läufen abzuschätzen.
- Behandeln Sie 4K als letzten Schritt im Prozess, nicht als interaktiven Modus.
Die Preise für diesen Endpunkt sind auf der HiAPI-Website aufgeführt; prüfen Sie dort die aktuellen Tarife, bevor Sie die Batch-Größe planen. Bringen Sie zuerst die minimale Anfrage zum Laufen und skalieren Sie dann bewusst Auflösung und Dauer – diese Reihenfolge hält sowohl Ihre Latenz als auch Ihre Rechnung vorhersehbar.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen