Benutzerhandbuch

So erstellst du Kurzvideos mit kling-3.0/motion-control auf der hiapi API

Oct 8, 2026

Wenn du jemals versucht hast, eine Figur in einem generierten Video eine bestimmte Bewegung ausführen zu lassen – nicht „tanzen“, sondern genau diesen Tanz aus genau diesem Clip –, dann weißt du, dass die üblichen Optionen alle schlecht sind: manuelles Rotoscoping Bild für Bild, das Neutraining eines Bewegungsmodells oder einfach aufgeben und akzeptieren, was der Text-Prompt liefert. kling-3.0/motion-control überspringt all das. Du gibst ihm ein Bild einer Figur und ein Referenzvideo, und es überträgt die Bewegung und Mimik aus der Referenz auf deine Figur – kein Rigging, keine Keyframes, kein Motion-Capture-Anzug.

Dieser Artikel geht einen echten Kurzvideo-Workflow durch: zuerst wird aus einem Fahrerfoto ein kurzer Referenzclip erzeugt, dann wird dieser Clip verwendet, um über motion-control ein völlig anderes Figurenbild anzutreiben. Jede Anfrage unten ist ein echter Aufruf der /v1/tasks-API von hiapi, jedes Asset wurde während des Schreibens dieses Artikels erzeugt (nichts aus einer Hersteller-Demo-Galerie ausgeliehen), und jeder Preis wurde live vom Preis-Endpunkt von hiapi abgerufen.

Was kling-3.0/motion-control eigentlich macht

Das Modell nimmt zwei Eingaben entgegen:

image_url – ein einzelnes Porträt einer Figur (das „Ziel“). Dies bestimmt, wer im Output erscheint.
video_url – der Bewegungsreferenzclip, 3–30 Sekunden. Dies bestimmt, was sie tun.

Der Output ist ein Video, in dem die Zielfigur die Bewegungen und Gesichtsausdrücke des Referenzvideos ausführt, gerendert in 720p oder 1080p. Es akzeptiert keinen Text-Prompt, keine Dauer und kein Seitenverhältnis – die Bildkomposition des Outputs folgt direkt dem Referenzclip, und die Länge des Outputs folgt der Länge des Eingabeclips (unsere 3-Sekunden-Referenz ergab einen 3,03-Sekunden-Output).

Genau dieser enge Vertrag mit nur zwei Eingaben macht es für Kurzvideo-Inhalte nützlich: Du brauchst keine Motion-Capture-Ausrüstung, um einem Marken-Maskottchen, einer Produktfigur oder einem stilisierten Avatar eine glaubwürdige Performance zu verleihen – du brauchst nur irgendein Video eines Menschen, der die gewünschte Bewegung ausführt.

Was du vorbereiten musst

Einen hiapi-API-Schlüssel (Authorization: Bearer <key>)
Ein öffentlich über HTTPS erreichbares Figurenbild (nicht dein Ziel – sondern deine Treiberfigur)
Ein zweites Figurenbild als das eigentliche Ziel, das du animieren willst
ffmpeg/ffprobe, falls du lokal ein Cover-Frame extrahieren oder die Clip-Länge prüfen willst, wie in diesem Artikel

Echte Demo: ein Bewegungsclip, zwei verschiedene Figuren

Der Kern von motion-control ist, dass Referenzvideo und endgültige Figur nicht übereinstimmen müssen. Um das zu beweisen, verwendet diese Demo drei Generierungsschritte:

1. Ein Fahrerporträt, animiert zu einem kurzen Referenzclip:

Dieses Porträt wurde über grok-imagine-1.5/image-to-video in einen 3-sekündigen Bewegungsclip in 480p verwandelt – eine schnelle, günstige Methode, um aus einem Standbild einen Referenzclip zu machen, statt einen fertigen Clip zu suchen:

2. Eine völlig andere Zielfigur – dieselbe Bewegung, ganz anderes Aussehen:

3. Beides in motion-control einspeisen. Der Imbissbetreiber führt exakt dieselbe Dreh-und-Zurückschau-Bewegung aus wie der Kurier:

Das ist der gesamte Workflow: Erzeuge (oder besorge) einen beliebigen Bewegungsclip, richte motion-control auf ein völlig unabhängiges Figurenbild und erhalte diese Figur bei der Ausführung der Bewegung. Für Kurzvideo-Pipelines bedeutet das: Eine Bibliothek mit Referenzbewegungen kann unbegrenzt viele Figuren antreiben, ohne dass jedes Mal neu gedreht oder die Referenzanimation neu erstellt werden muss.

Minimal funktionierende Anfrage (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

Antwort (Task erstellt, noch in Bearbeitung):

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

Abpollern bis zur Fertigstellung:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

In unserem Lauf dauerte ein 3-Sekunden-720p-Clip von Anfang bis Ende etwa 2,3 Minuten (der Status wechselte etwa ein Dutzend Mal zu handling, bevor er auf success sprang) – plane bei deiner Polling-Schleife Minuten statt Sekunden ein. Die endgültige Antwort:

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

Diese output[0].url ist ein temporärer Link – expireAt ist ein Unix-Zeitstempel, und in unserem Test lag die Gültigkeit bei etwa 24 Stunden. Lade ihn sofort herunter und hoste ihn erneut; verlinke nicht direkt darauf aus irgendetwas, das du veröffentlichst.

Derselbe Ablauf in Python

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

Nichts Kompliziertes – Task erstellen, in Intervallen GET /v1/tasks/{taskId} abpollern, in dem Moment, in dem success erreicht wird, output[0].url herunterladen und selbst neu hosten, bevor der temporäre Link abläuft.

Welche Parameter motion-control tatsächlich prüft

Das Schema ist streng – alles außerhalb dieser drei Felder wird abgelehnt, und das im Voraus zu wissen ist nützlich, statt es durch Trial and Error herauszufinden:

Feld	Erforderlich	Beschreibung
`image_url`	Ja	Öffentliche HTTPS-URL, Zielfigur
`video_url`	Ja	Öffentliche HTTPS-URL, 3–30 Sekunden Bewegungsreferenz
`resolution`	Nein (hat einen Standardwert, ist aber das Setzen wert)	`"720p"` oder `"1080p"` – dies bestimmt auch die Preisstufe

Felder, die du von anderen Videomodellen erwarten würdest – duration, aspect_ratio, prompt – werden mit einem Schemafehler abgelehnt:

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

Das ist beabsichtigt: Länge und Komposition des Outputs erben vollständig vom Referenzvideo, also gibt es für duration/aspect_ratio nichts zu steuern. Wenn du einen längeren Output oder eine andere Komposition willst, schneide oder reframe den Referenzclip vor dem Senden, statt die Anfrage zu ändern.

Preisgestaltung: Abrechnung pro Output-Sekunde, nicht pro Anfrage

Direkt vom Preis-Endpunkt von hiapi:

Auflösung	Preis
720p	$0.10 / Output-Sekunde
1080p	$0.172 / Output-Sekunde

Die Abrechnung richtet sich nach der tatsächlichen Output-Dauer (estimated_seconds), die die Länge deines Referenzclips widerspiegelt – nicht nach einer festen Gebühr pro Anfrage. Unsere 3-Sekunden-Referenz ergab in 720p einen 3,03-Sekunden-Output und kostete etwa $0.30. Ein 10-Sekunden-1080p-Referenzclip liegt bei knapp $1.72. Wenn du dies in großem Umfang in einem Content-Kalender einsetzt, ist der praktisch verstellbare Hebel die Länge des Referenzclips: Kürzere Referenzclips sind günstiger und tragen dennoch eine vollständige Bewegungsperformance für Kurzvideo-Formate (Reels, TikTok, Shorts), bei denen 3–8 Sekunden oft schon der ganze Clip sind.

Hinweise für den Produktionseinsatz

Wähle die Komposition des Treiberclips bewusst. Der Output erbt Seitenverhältnis, Kameradistanz und Tempo des Referenzvideos – eine Nahaufnahme als Referenz bleibt eine Nahaufnahme im Output, unabhängig davon, wie das Zielfigurenbild zugeschnitten ist.
Deutliche Ausdrücke werden besser übertragen als subtile. Eine klare Drehung, ein Winke oder ein Kopfneigen in der Referenz erscheint zuverlässig auf der Zielfigur; sehr feine, natürliche Mikroausdrücke sind für das Modell schwerer zu erkennen und zu übertragen.
Einen Referenzclip für viele Figuren wiederverwenden. Da video_url und image_url völlig unabhängig sind, ist das effizienteste Muster in einer Content-Pipeline: zuerst eine kleine Bibliothek an Referenzbewegungen aufbauen und dann mit demselben Clip viele verschiedene Figurenbilder durchlaufen lassen.
Temporäre Output-URLs sind kurzlebig. expireAt liegt typischerweise bei etwa einem Tag – lade sofort herunter und hoste erneut, statt den Download auf später zu verschieben.
Die Verarbeitung ist nicht sofort. In diesem Test dauerte ein 3-Sekunden-720p-Clip von Anfang bis Ende über zwei Minuten; plane deine Polling-Schleife und jede nachgelagerte Automatisierung in Minuten (nicht in den Sekunden, die Text-zu-Bild-Aufrufe üblicherweise brauchen).

Häufig gestellte Fragen

Kann ich irgendein Video als Bewegungsreferenz verwenden? Jedes Video mit einem klaren menschlichen (oder humano-id-artigen) Darsteller funktioniert, solange es öffentlich über HTTPS erreichbar ist und 3–30 Sekunden lang ist. Es muss deine Zielfigur nicht enthalten – genau darum geht es bei diesem Modell.

Übernimmt der Output den Hintergrund des Referenzvideos? Nein – das Aussehen der Figur, einschließlich der durch das Zielbild angedeuteten Umgebung, bleibt erhalten; das Referenzvideo liefert Bewegung und Mimik, nicht den Szeneninhalt.

Warum wurde meine Anfrage mit „unexpected additional properties“ abgelehnt? Das Schema akzeptiert nur image_url, video_url und resolution. Felder wie duration, aspect_ratio oder prompt gehören nicht zu den Eingaben dieses Modells und führen sofort zu einem 400 – entferne sie aus dem Payload.

Wie lange dauert ein motion-control-Task? Plane einige Minuten pro Clip ein. Unser 3-Sekunden-720p-Beispiel brauchte von der Task-Erstellung bis zu einem herunterladbaren success-Output etwa 2,3 Minuten.

Kann ich die Output-Auflösung unabhängig vom Preis steuern? Nein – resolution ist sowohl eine Einstellung der Output-Qualität als auch ein Preisstufen-Selektor: "720p" wird mit $0.10/Output-Sekunde abgerechnet, "1080p" mit $0.172/Output-Sekunde.