Tutorial
So verwendest du kling-3.0/motion-control über die HiAPI API: curl- und Python-Beispiele
Auf dieser Seite
Wofür kling-3.0/motion-control gedacht ist und wann du es wählen solltest
Motion Control ist eine Fähigkeit in der Videogenerierung: Du übergibst dem Modell ein Referenzvideo, und es steuert Bewegung, Rhythmus und Bildkomposition der Ausgabe – statt dass allein ein Text-Prompt die Aktion beschreibt. Wenn du kling-3.0/motion-control über die HiAPI API verwendest, ist das Referenzvideo die Haupt-Eingabe: Es verankert, wie sich Objekte bewegen, und die übrigen Parameter formen den Inhalt, der rund um diese Bewegung generiert wird.
Wähle dieses Modell, wenn die Bewegung selbst die schwierige Angelegenheit ist. Typische passende Szenarien:
- Du hast ein kurzes Video und möchtest dessen Kamerabewegung oder Subjektaktion mit anderen Inhalten reproduzieren.
- Du brauchst vorhersehbare Bewegung statt Text-zu-Video-Ergebnissen, die auf gut Glück aus Text-Prompts entstehen.
- Du baust eine Pipeline, in der Bewegung ein über mehrere Generierungen wiederverwendbares Asset ist und daher als Eingabe statt als Satz von Beschreibungen vorliegen sollte.
Wenn du nur Text-zu-Video brauchst und keine Bewegungsreferenz hast, fügt Motion Control nur einen Upload-Schritt und strengere Eingabebeschränkungen hinzu, ohne Nutzen. Ebenso solltest du mehr Wiederholungsversuche einplanen, wenn das Referenzvideo lang oder die Komposition instabil ist. Der Rest dieses Leitfadens setzt voraus, dass du entschieden hast, dass Motion Control das richtige Werkzeug ist, und eine zuverlässige, reproduzierbare Integration wünschst.
Voraussetzungen und Endpunkt-Einrichtung
Bevor du den ersten Aufruf machst, bereite drei Dinge vor.
1. API-Schlüssel
Erstelle einen Schlüssel in der Kontokonsole von HiAPI.ai und lege ihn in einer Umgebungsvariable ab, statt ihn in den Quellcode zu schreiben:
export HIAPI_API_KEY="your_api_key_here"
Bei jeder Anfrage sendest du ihn als Bearer-Token: Authorization: Bearer $HIAPI_API_KEY.
2. Basis-URL-Konvention
Alle HiAPI-Aufrufe teilen dieselbe Basis-URL und ein versioniertes Pfadpräfix. Lege die Basis-URL in der Konfiguration ab, sodass du beim Umgebungswechsel keine Aufrufstellen ändern musst:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. Modellkennung
Das Modell wird pro Anfrage über das Feld model im Request ausgewählt; verwende die exakte Kennung kling-3.0/motion-control. Hardcode sie nicht an mehreren Stellen – übergib sie als Konstante, sodass ein künftiger Modellwechsel nur eine Zeile ändert.
Du brauchst außerdem einen gehosteten Ort, von dem die API das Referenzvideo abrufen kann. Üblich ist eine signierte, zeitlich begrenzte URL; stelle sicher, dass sie ohne benutzerdefinierte Header oder Cookies erreichbar ist.
Sobald diese drei Punkte bereit sind, geht es im weiteren Verlauf nur noch um die Request-Struktur und den Task-Lebenszyklus.
Referenzvideo und Bewegungsparameter bereitstellen
Eine Motion-Control-Anfrage zerfällt konzeptionell in zwei Hälften: die Bewegungsquelle (dein Referenzvideo) und die Generierungseinstellungen (was das Modell erzeugen soll).
Referenzvideo
Das Referenzvideo wird als URL im Request-Body übergeben, nicht als Rohbytes im JSON-Payload. Zwei praktische Regeln:
- Verwende eine URL, die während der gesamten Warte- und Verarbeitungszeit des Tasks gültig bleibt. Vorzeitig ablaufende signierte URLs sind eine häufige Ursache dafür, dass ein Task wenige Minuten nach dem Absenden fehlschlägt.
- Halte das Video kurz und das Bild stabil. Zu langes, stark verwackeltes oder häufig geschnittenes Referenzmaterial liefert dem Modell ein unklares Bewegungssignal.
Wenn das Material in einem privaten Speicher liegt, erzeuge die signierte URL erst beim Absenden mit ausreichender Gültigkeit, nicht bereits beim Upload.
Bewegungs- und Ausgabeparameter
Parameter, die üblicherweise zusammen mit dem Referenzvideo gesetzt werden:
- Ein Text-Prompt, der den Zielinhalt beschreibt, der durch die Referenzbewegung angetrieben werden soll.
- Einstellungen für Seitenverhältnis und Dauer der Ausgabe, damit das generierte Video zu deinem Anzeigeplatz passt.
- Alle vom Modell angebotenen Einstellungen für Bewegungsstärke oder Treue, um zwischen Referenztreue und Prompt-Freiheit abzuwägen.
Fasse diese Parameter als kleines, explizites Konfigurationsobjekt in deinem Client zusammen, statt sie über Funktionsargumente zu verteilen. So lässt sich genau protokollieren, was übermittelt wurde – und das ist das nützlichste Debug-Material für dieses Modell.
Validiere abschließend vor dem Absenden: Die Referenz-URL liefert einen Medien-Content-Type, der Prompt ist nicht leer, alle numerischen Einstellungen liegen im dokumentierten Bereich. Eine lokale Prüfung dauert nur Millisekunden; ein abgelehnter asynchroner Task kostet einen Roundtrip und Verwirrung.
Asynchrone Tasks: absenden, pollen und Ergebnisse lesen
Motion Control liefert das Video nicht in der Antwort auf das Absenden zurück, sondern einen Task, den du verfolgen musst. Baue deinen Client von Anfang an um diesen Lebenszyklus herum.
Schritt 1 – Absenden
POSTe den Task an den Modell-Endpunkt. Ein erfolgreiches Absenden liefert eine Task-ID. Persistiere diese ID sofort – sie ist dein einziger Handle für den Task, den du beim Polling und bei Support-Anfragen benötigst.
Schritt 2 – Pollen
GETte den Task-Status mit dieser ID. Das Status-Feld sagt dir, in welchem von drei Zuständen du dich befindest:
- Ausstehend oder in der Warteschlange: akzeptiert, noch nicht gestartet. Weiter warten.
- In Bearbeitung oder laufend: läuft gerade. Weiter warten, aber mit Backoff-Strategie.
- Endzustand: erfolgreich oder fehlgeschlagen. Polling beenden.
Die Polling-Schleife sollte explizit auf Endzustände prüfen und nicht nur darauf, ob das Ausgabefeld vorhanden ist. Ein fehlgeschlagener Task hat kein Ergebnis; „noch kein Ergebnis“ als „läuft noch“ zu behandeln, führt zu einer Endlosschleife.
Schritt 3 – Ergebnis lesen
Bei Erfolg enthält die Antwort den Ausgabeort, üblicherweise eine URL zum generierten Video. Lade sie zeitnah in deinen eigenen Speicher herunter – generierte Assets hinter temporären URLs solltest du nicht als dauerhaft verfügbar ansehen.
Polling-Regeln
Zwei Regeln halten das in der Produktion zuverlässig:
- Verwende Backoff zwischen den Abfragen (beginne mit ein bis zwei Sekunden und erhöhe dann), statt den Endpunkt zu hämmern.
- Begrenze die Gesamtwartezeit und gib einen Timeout als wiederholbaren Fehler aus, statt einen Worker-Thread dauerhaft zu blockieren.
Protokolliere pro Lauf die Task-ID, die übermittelten Parameter und den Endstatus. Wenn etwas schiefgeht, beantwortet dieses Log die meisten Fragen, bevor du überhaupt jemanden fragen musst.
Ausführbare curl-Anfrage
Im Folgenden der vollständige Ablauf in der Shell. Er sendet den Task ab, extrahiert die Task-ID und pollt dann, bis der Task einen Endzustand erreicht.
#!/usr/bin/env bash
set -euo pipefail
BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"
# 1) Task absenden
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0/motion-control",
"prompt": "Ein Papierboot treibt durch eine regnerische Stadtstraße, filmisch",
"reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
"duration": 5,
"aspect_ratio": "16:9"
}')
echo "$SUBMIT"
TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"
# 2) Pollen bis zum Endzustand
while true; do
STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY")
STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
echo "status: $STATUS"
case "$STATUS" in
succeeded) echo "$STATUS_JSON"; break ;;
failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
esac
sleep 3
done
Zwei Hinweise zur Anpassung dieses Skripts. Erstens: Halte Modellkennung und Endpunktpfad in Variablen, damit das Skript lesbar bleibt. Zweitens: Das obige Parsing verwendet kein jq, sondern nur Python, weil Python fast überall verfügbar ist; wenn du jq bevorzugst, kannst du es ersetzen. So oder so ist das entscheidende Verhalten gleich: aus der Absendeantwort die Task-ID extrahieren und dann ihren Status pollen, bis ein Endzustandswert erscheint.
Dieselbe Anfrage (Python-Version)
Der folgende Python-Client entspricht dem curl-Ablauf, aber die Polling-Schleife ist robuster: annähernd exponentieller Backoff, ein Gesamt-Timeout und explizite Behandlung jedes Endzustands.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
TERMINAL = {"succeeded", "failed", "cancelled"}
def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
payload = {
"model": MODEL,
"prompt": prompt,
"reference_video_url": reference_video_url,
"duration": duration,
"aspect_ratio": "16:9",
}
r = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
r.raise_for_status()
return r.json()["id"]
def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/videos/generations/{task_id}",
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in TERMINAL:
return data
time.sleep(delay)
delay = min(delay * 1.5, 15.0)
raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task_id = submit_job(
prompt="Ein Papierboot treibt durch eine regnerische Stadtstraße, filmisch",
reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
)
print("submitted:", task_id)
result = wait_for_job(task_id)
if result["status"] == "succeeded":
print("output:", result.get("output"))
else:
print("job did not succeed:", result)
Was sich beim Anpassen zu behalten lohnt: das Endzustands-Set, der begrenzte Backoff und die getrennten Funktionen für Absenden und Warten. In einem echten Service würdest du sie auf zwei Prozesse aufteilen – im Request-Handler absenden, Task-ID speichern, einen Worker pollen lassen –, damit langsame Tasks niemals die HTTP-Antwort blockieren.
Häufige Fehlerquellen und wie du sie debugst
Die meisten Integrationsprobleme mit kling-3.0/motion-control fallen in wenige Kategorien. Prüfe sie der Reihe nach.
Authentifizierungs- und Modellfehler
401 bedeutet fast immer, dass der Bearer-Token fehlt, abgeschnitten ist oder aus der falschen Umgebung stammt. Ein Modell-nicht-gefunden-Fehler bedeutet, dass der model-String nicht exakt übereinstimmt – es ist eine durch Schrägstrich getrennte Kennung, sodass eine falsche Zeichenreihenfolge oder überflüssige Leerzeichen in der Konfiguration still fehlschlagen und an der API lautstark einen Fehler melden.
Referenzvideo nicht verfügbar
Der Task wird akzeptiert und schlägt Minuten später fehl, weil die Referenz-URL nicht abgerufen werden kann. Ursachen nach Häufigkeit sortiert: Die signierte URL läuft vor der Verarbeitung ab; die URL erfordert einen Auth-Header, den der Dienst nicht sendet; die URL liefert HTML (Anmeldeseite oder Fehlerseite) statt Video. Teste die URL von außerhalb deines Netzwerks mit einem einfachen curl und prüfe den Content-Type.
Parameterformat falsch oder außerhalb des Bereichs
Einstellungen für Dauer und Seitenverhältnis außerhalb des dokumentierten Bereichs werden beim Absenden abgelehnt – das ist gut, denn du erhältst sofort einen Fehler. Validiere lokal, damit ein Tippfehler keinen Roundtrip braucht, um entdeckt zu werden.
Polling-Fehler
Zwei Klassiker: Die Schleife prüft nur das Ausgabefeld und nie failed, was zu einer Endlosschleife führt; und das Pollen in einer engen Schleife ohne Schlaf führt dazu, dass du selbst rate-limitiert wirst. Füge explizite Endzustandsprüfungen und Backoff hinzu und hänge in Fehlerberichten immer die Task-ID an, damit du den Task abfragen statt neu aufbauen kannst.
Abgelaufene Ergebnis-URL
Du hast das Video generiert, aber nur die temporäre Ausgabe-URL gespeichert. Lade die Ausgabe sofort nach erfolgreichem Task in deinen eigenen Speicher herunter; behandle die zurückgegebene URL als Abruf-Handle, nicht als dauerhaften Speicher.
Beginne jede Debug-Sitzung damit, den exakten Request-Body und das rohe Antwort-JSON zu protokollieren. Nahezu alle oben genannten Probleme sind in diesen beiden Materialien sichtbar. Wenn du tiefer einsteigen möchtest, schau in der HiAPI.ai-Dokumentation nach weiteren Videomodellen und der Endpunkt-Referenz und behalte dieselbe Client-Form „zuerst absenden, dann pollen“ bei.
Ä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