Kling V3.0 Motion Control API – Schnellstart

Kling V3.0 Motion Control ermöglicht es Ihnen, ein statisches Charakterbild zu animieren, indem die Bewegung aus einem Referenzvideo extrahiert und Bild für Bild angewendet wird. Die Ausgabe bewahrt das Aussehen des Charakters aus Ihrem Bild und reproduziert gleichzeitig die Bewegung aus dem Video – eine Technik namens Bewegungstransfer. Dieser Leitfaden behandelt den Novita AI-Endpunkt, die erforderlichen Eingaben, die wichtigsten Parameter sowie funktionierende Python- und curl-Beispiele, die Sie mit einem echten API-Schlüssel ausführen können.

Wann Motion Control das richtige Werkzeug ist

Motion Control ist das richtige Werkzeug, wenn Sie zwei Dinge haben: ein statisches Charakterbild, das Sie animieren möchten, und ein Referenzvideo, dessen Bewegung Sie reproduzieren möchten. Es unterscheidet sich von Image-to-Video (I2V), das Bewegung aus einem Prompt generiert. Bei Motion Control wird die Bewegung präzise aus dem Referenzvideo kopiert – der Ausgabe-Charakter folgt demselben Bewegungsbogen wie die Person im Referenzvideo.

Verwenden Sie es, wenn:

• Sie einen bestimmten Tanz, Gehzyklus oder eine bestimmte Geste auf eine Charakterillustration oder ein Foto anwenden möchten
• Sie eine konsistente, wiederholbare Bewegung über verschiedene Charaktere hinweg benötigen (gleiches Referenzvideo, verschiedene Bilder)
• Sie Inhalte erstellen, bei denen die Bewegungsqualität wichtig ist und offene I2V-Prompt-Ergebnisse zu unvorhersehbar sind

Verwenden Sie es nicht, wenn die Bewegung selbst noch nicht definiert ist – in diesem Fall bietet I2V mit einem beschreibenden Prompt mehr Flexibilität zu geringeren Kosten.

Schritt 1: Holen Sie sich Ihren Novita-API-Schlüssel

Melden Sie sich unter novita.ai an und generieren Sie einen API-Schlüssel im Dashboard. Neue Konten erhalten kostenlose Credits, mit denen Sie Motion Control testen können, bevor Sie sich für die Produktion entscheiden.

Schritt 2: Endpunkt und Modell-ID bestätigen

Kling V3.0 Motion Control auf Novita AI verwendet das standardmäßige asynchrone Video-Muster:

Aufgabe einreichen:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Ergebnis abfragen:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

Alle Anfragen erfordern:

Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json

Vollständige Dokumentation: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Schritt 3: Bereiten Sie Ihre Eingaben vor

Motion Control erfordert zwei Eingaben: ein Referenzbild und ein Referenzvideo. Die korrekte Vorbereitung ist der wichtigste Faktor für die Ausgabequalität.

Referenzbild

Dies ist der Charakter, dessen Aussehen in der Ausgabe erhalten bleibt. Anforderungen:

• Formate: JPEG, PNG, JPG
• Maximale Größe: 10 MB
• Mindestauflösung: 340px auf jeder Seite
• Seitenverhältnis: zwischen 2:5 und 5:2
• Der Charakter sollte deutlich sichtbar sein, mehr als 5 % der Bildfläche einnehmen und keine starke Verdeckung aufweisen (Kopf oder Körper nicht abschneiden)

Für beste Ergebnisse verwenden Sie ein Bild, bei dem die Körperproportionen des Charakters grob dem entsprechen, was im Referenzvideo sichtbar ist. Wenn das Referenzvideo einen Ganzkörpertänzer zeigt, verwenden Sie ein Ganzkörper-Charakterbild und keine Porträtansicht.

Referenzvideo

Dies ist die Bewegungsquelle. Der Charakter in der Ausgabe wiederholt die Bewegungen aus diesem Video:

• Formate: MP4, MOV
• Maximale Größe: 10 MB
• Dauer: 3–30 Sekunden
• Mindestauflösung: 340px auf jeder Seite
• Seitenverhältnis: zwischen 2:5 und 5:2
• Die Person im Referenzvideo sollte mit sichtbarem und unverdecktem vollständigem oder oberem Körper (einschließlich Kopf) zu sehen sein

Klares, gut beleuchtetes Filmmaterial mit minimalem Hintergrundunschärfe überträgt Bewegungen genauer als verrauschte oder überfüllte Aufnahmen.

Schritt 4: Senden Sie Ihre erste Anfrage

Minimale curl-Anfrage:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

Die Antwort gibt sofort eine task_id zurück:

{
  "task_id": "abc123xyz"
}

Schritt 5: Ergebnis abfragen

Kling V3.0 Motion Control ist asynchron. Reichen Sie die Aufgabe ein und fragen Sie dann ab, bis der Status succeed ist:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

Wenn abgeschlossen, enthält die Antwort ein videos-Array mit der Ausgabe-URL:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

Die typische Generierungszeit beträgt 30–120 Sekunden, abhängig von Videodauer und Modus. Fragen Sie alle 5–10 Sekunden ab, anstatt den Endpunkt zu überlasten.

Vollständiges Python-Integrationsbeispiel

Dieses Skript sendet eine Motion-Control-Aufgabe und fragt ab, bis sie abgeschlossen ist:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

API-Parameter-Referenz

Parameter	Typ	Erforderlich	Beschreibung
image	string	Ja	URL des zu animierenden Charakterbilds. Siehe Eingabeanforderungen oben.
video	string	Ja	URL des Referenzvideos, dessen Bewegung übertragen wird.
model_name	string	Ja	Auf kling-v3.0-motion-control setzen.
prompt	string	Nein	Textbeschreibung des gewünschten Bewegungsstils oder Szenenkontexts. Optional, kann aber die Ausgabequalität verbessern.
character_orientation	string	Nein	Steuert die Pose-Ausrichtung und die Ausgabedauer. "video" entspricht der Ausrichtung des Referenzvideos – besser für komplexe Ganzkörperbewegungen, unterstützt bis zu 30s. "image" entspricht der Ausrichtung des Charakterbilds – besser für kamerarelative Bewegungen, fest auf 5s.

character_orientation in der Praxis

Wenn Ihr Referenzvideo einen frontal tanzenden Tänzer zeigt und Ihr Charakterbild ebenfalls frontal ist, liefert "video" einen besseren Bewegungstransfer und unterstützt bis zu 30 Sekunden. Wenn das Referenzvideo eine Kamera hat, die sich um das Motiv bewegt, und Ihr Bild ein Porträt mit festem Winkel ist, neigt "image" dazu, unerwünschte perspektivische Verzerrungen zu reduzieren – beachten Sie jedoch, dass es einen festen 5-Sekunden-Clip generiert.

Standard vs. Pro: Welche Qualitätsstufe wählen

Kling V3.0 Motion Control ist in zwei Qualitätsstufen verfügbar:

Standard gibt in 720p aus. Es ist die richtige Wahl für Iterationen, Tests der Bewegungskompatibilität oder das Erstellen von Entwürfen, bevor Sie sich für eine finale Version entscheiden.

Pro gibt in 1080p aus mit verbesserter Bewegungstreue und Motivkonsistenz. Verwenden Sie Pro, wenn:

• Die Ausgabe in eine fertige Produktion eingeht (Social-Media-Beitrag, Kurzfilm, Produktdemo)
• Feine Details im Gesicht oder der Kleidung des Charakters wichtig sind
• Sie längere Clips (10s+) generieren, bei denen Qualitätsverluste im Laufe der Zeit sichtbarer werden

Für die meisten Entwicklungs-Workflows beginnen Sie mit Standard, um die Eingabekompatibilität und Bewegungsqualität zu bestätigen, und wechseln Sie dann für den finalen Durchlauf zu Pro.

Preise, Dauer und Kostenschätzung

Novita AI berechnet Motion Control pro Sekunde des generierten Videos. Standard- und Pro-Stufen haben separate Preise pro Sekunde. Aktuelle Preise finden Sie auf der Novita AI-Modellseite.

Dauerbeschränkungen:

• character_orientation: "video" – bis zu 30 Sekunden
• character_orientation: "image" – feste 5 Sekunden

Die Kosten skalieren mit der Dauer im "video"-Modus. Der "image"-Modus generiert immer einen 5-Sekunden-Clip.

Fehlerbehebung bei häufigen Fehlern

Aufgabe schlägt sofort mit einem 422- oder Validierungsfehler fehl Überprüfen Sie, ob sowohl image als auch video öffentlich zugängliche URLs sind (nicht hinter einer Authentifizierung oder einer kurzlebigen, abgelaufenen Presigned-URL). Das Novita-Backend muss beide Dateien zum Zeitpunkt der Aufgabenausführung abrufen können.

Ausgabebewegung wirkt falsch oder der Charakter verzerrt sich Die häufigste Ursache ist eine Diskrepanz zwischen der Ausrichtung des Charakters im Bild und im Referenzvideo. Versuchen Sie, character_orientation zwischen "video" und "image" umzuschalten, um zu sehen, welche Option eine bessere Ausrichtung liefert.

Charakter verliert mitten im Clip die Gesichtsidentität Stellen Sie sicher, dass der Charakter im Referenzbild ein klares, unverdecktes Gesicht und einen klaren Körper hat. Bei längeren Clips erhält die Pro-Stufe die Motivkonsistenz besser als Standard.

Bewegung des Referenzvideos wird nicht sauber übertragen Verrauschtes oder überfülltes Referenzmaterial verschlechtert die Bewegungsextraktion. Verwenden Sie Filmmaterial, in dem der Darsteller das Hauptmotiv vor einem einigermaßen sauberen Hintergrund ist. Vermeiden Sie wackelige Handkameraaufnahmen, wenn das Ziel ein sanfter Bewegungstransfer ist.

Status bleibt länger als 3 Minuten in processing hängen Gelegentliche Warteschlangenverzögerungen sind möglich. Warten Sie bis zu 5 Minuten, bevor Sie es als hängend betrachten. Wenn es hängen bleibt, reichen Sie eine neue Aufgabe ein – verwenden Sie nicht die alte task_id wieder.

Was Entwickler mit Kling Motion Control bauen

Charakteranimation für Spiel-Assets: Nehmen Sie eine Charakterillustration und wenden Sie einen Referenzbewegungsclip (Gehen, Laufen, Angriff) an, ohne Rigging- oder Animationssoftware.

Social-Media-Inhalte mit konsistenter Bewegung: Wenden Sie dasselbe Tanzreferenzvideo auf mehrere Charakterbilder an, um eine Serie von Clips mit identischer Choreografie, aber unterschiedlichem Aussehen zu erstellen.

Pre-Visualisierung: Testen Sie, wie eine bestimmte Bewegungssequenz auf einem Charakterdesign aussieht, bevor Sie in die vollständige Produktionsanimation investieren.

E-Commerce-Produktanzeige: Wenden Sie subtile Posenänderungen oder Kleidungsbewegungen auf Produktbilder an, indem Sie ein sorgfältig ausgewähltes Referenzvideo verwenden, das Stoffbewegungen zeigt.

FAQ

Was ist der Unterschied zwischen Motion Control und Image-to-Video auf Novita AI?

Image-to-Video (I2V) animiert ein Bild basierend auf einem Text-Prompt – die Bewegung wird vom Modell aus Ihrer Beschreibung generiert. Motion Control überträgt eine bestimmte Bewegung aus einem Referenzvideo auf den Charakter in Ihrem Bild. Motion Control bietet präzise, reproduzierbare Bewegung; I2V bietet kreative Flexibilität ohne die Notwendigkeit eines Referenzclips.

Muss der Charakter im Referenzvideo dem Aussehen des Bildcharakters entsprechen?

Nein. Das Referenzvideo wird nur zur Bewegungsextraktion verwendet – der Ausgabe-Charakter stammt aus dem Bild, nicht aus dem Video. Das ist die Kernfunktion: Bewegung von einer Quelle, Aussehen von einer anderen. Die Proportionen sollten grob übereinstimmen (Ganzkörperbild für Ganzkörpervideo, Porträt für Oberkörpervideo) für eine optimale Übertragungsqualität.

Kann ich jedes öffentlich verfügbare Video als Referenz verwenden?

Sie können jedes Video verwenden, das die Format- und Größenanforderungen erfüllt. Die Bewegung wird am besten aus Filmmaterial übertragen, in dem das Motiv klar sichtbar und minimal verdeckt ist. Komplexe Szenen mit mehreren Personen oder stark bearbeitetes Filmmaterial (Schnitte, Zooms) können die Genauigkeit verringern.

Wie lange dauert die Generierung?

Typischerweise 30–120 Sekunden, abhängig von der Ausgabedauer und der gewählten Qualitätsstufe (Standard oder Pro). Fragen Sie alle 8–10 Sekunden ab, anstatt in einer engen Schleife.

Empfohlene Artikel

• Kling O1 auf Novita AI: T2V, I2V, Ref2V und Video-Edit-Modi
• Kling 3.0 jetzt auf Novita AI: Kinoreife KI-Videogenerierung im großen Stil
• Kling V2.5 Turbo API auf Novita AI