Kling V3.0 Motion Control API Schnellstart

Mit Kling V3.0 Motion Control können Sie ein statisches Charakterbild animieren, indem Sie die Bewegung aus einem Referenzvideo extrahieren und Bild für Bild anwenden. Das Ausgabeergebnis bewahrt das Aussehen des Charakters aus Ihrem Bild, während die Bewegung aus dem Video reproduziert wird – eine Technik namens Motion Transfer. Dieser Leitfaden behandelt den Novita-AI-Endpunkt, die erforderlichen Eingaben, wichtige Parameter und 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. Mit Motion Control wird die Bewegung präzise aus dem Referenzvideo kopiert – der ausgegebene Charakter folgt demselben Bewegungsablauf wie die Person im Referenzvideo.

Verwenden Sie es, wenn:

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

Verwenden Sie es nicht, wenn die Bewegung selbst noch undefiniert ist – in diesem Fall bietet Ihnen 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 im Dashboard einen API-Schlüssel. Neue Konten erhalten kostenloses Guthaben, mit dem Sie Motion Control testen können, bevor Sie in die Produktion gehen.

Schritt 2: Bestätigen Sie den Endpunkt und die Modell-ID

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 benötigen:

Authorization: Bearer IHR_NOVITA_API_SCHLUESSEL
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 benötigt zwei Eingaben: ein Referenzbild und ein Referenzvideo. Diese richtig zu wählen, ist der größte Einzelfaktor 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)

Verwenden Sie für beste Ergebnisse ein Bild, bei dem die Körperproportionen des Charakters in etwa dem entsprechen, was im Referenzvideo sichtbar ist. Wenn das Referenzvideo einen Ganzkörpertänzer zeigt, verwenden Sie ein Ganzkörper-Charakterbild anstelle eines Porträtausschnitts.

Referenzvideo

Dies ist die Bewegungsquelle. Der Charakter in der Ausgabe repliziert 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 ihrem ganzen Körper oder Oberkörper sichtbar und unverdeckt sein, einschließlich des Kopfes

Klares, gut beleuchtetes Filmmaterial mit minimalem Hintergrundrauschen ü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: Fragen Sie das Ergebnis ab

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 sie abgeschlossen ist, 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 Charakterbildes. 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 Ausgabedauer. "video" entspricht der Ausrichtung des Referenzvideos – besser für komplexe Ganzkörperbewegungen, unterstützt bis zu 30s. "image" entspricht der Ausrichtung des Charakterbildes – besser für kamerarelevante Bewegungen, fest auf 5s eingestellt.

character_orientation in der Praxis

Wenn Ihr Referenzvideo einen frontal stehenden Tänzer zeigt und Ihr Charakterbild ebenfalls frontal ist, liefert "video" einen besseren Motion Transfer 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 ein fester 5-Sekunden-Clip generiert wird.

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

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

Standard gibt Ausgaben 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 endgültige Version entscheiden.

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

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

Beginnen Sie für die meisten Entwicklungsworkflows 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 Kostenabschätzung

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

Dauerlimits:

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

Die Kosten skalieren mit der Dauer für den "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 in der Lage sein, beide Dateien zum Zeitpunkt der Aufgabenausführung abzurufen.

Die Ausgabebewegung wirkt falsch oder der Charakter verzerrt sich Die häufigste Ursache ist ein Missverhältnis zwischen der Charakterausrichtung im Bild und dem Referenzvideo. Versuchen Sie, character_orientation zwischen "video" und "image" zu wechseln, um zu sehen, welche Einstellung eine bessere Ausrichtung erzeugt.

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

Die Bewegung des Referenzvideos wird nicht sauber übertragen Verrauschtes oder überfülltes Referenzmaterial verschlechtert die Bewegungsextraktion. Verwenden Sie Filmmaterial, bei dem der Darsteller das Hauptmotiv vor einem einigermaßen sauberen Hintergrund ist. Vermeiden Sie verwackelte Handaufnahmen, wenn das Ziel eine flüssige Bewegungsübertragung ist.

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

Was Entwickler mit Kling Motion Control bauen

Charakteranimation für Spiel-Assets: Nehmen Sie eine Charakterillustration und wenden Sie einen Referenz-Bewegungsclip (Gehen, Laufen, Angriff) an, ohne auf Rigging oder Animationssoftware angewiesen zu sein.

Social-Media-Inhalte mit konsistenter Bewegung: Wenden Sie dasselbe Tanz-Referenzvideo auf mehrere Charakterbilder an, um eine Serie von Clips mit identischer Choreographie, 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-Produktdarstellung: Wenden Sie subtile Posenänderungen oder Kleidungsbewegungen auf Produktbilder an, indem Sie ein sorgfältig ausgewähltes Referenzvideo mit Stoffbewegungen verwenden.

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 liefert Ihnen präzise, reproduzierbare Bewegungen; I2V gibt Ihnen kreative Flexibilität, ohne dass Sie einen Referenzclip benötigen.

Muss der Charakter im Referenzvideo dem Aussehen des Bildcharakters entsprechen?

Nein. Das Referenzvideo wird nur zur Bewegungsextraktion verwendet – der ausgegebene Charakter stammt aus dem Bild, nicht aus dem Video. Das ist die Kernfähigkeit: 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 beste Ü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, bei dem das Motiv deutlich sichtbar ist und nur minimale Verdeckung aufweist. Komplexe Szenen mit mehreren Personen oder stark bearbeitetes Filmmaterial (Schnitte, Zooms) kann die Genauigkeit verringern.

Wie lange dauert die Generierung?

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

Empfohlene Artikel

• Kling 3.0 jetzt auf Novita AI: Filmische KI-Videogenerierung in großem Maßstab
• Kling V3.0 4K API Schnellstart
• Kling V2.5 Turbo API auf Novita AI