Kling AI Image-to-Video
Überblick
Animieren Sie statische Bilder über den Endpunkt /v1/videos/image2video. Unterstützt Bewegungs-Prompts, Kamerasteuerung, dynamische Masken (Bewegungs-Pinsel), statische Masken und Tail-Bilder für Start-zu-Ende-Übergänge.
Endpunkt: POST https://api.klingai.com/v1/videos/image2video
Anforderungsparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
model_name | string | Ja | kling-v1-5, kling-v2-1, kling-v2-master usw. |
image | string | Ja | URL des Quellbilds (JPG, PNG, WebP) |
prompt | string | Nein | Bewegungsbeschreibung für die Animation |
negative_prompt | string | Nein | Was ausgeschlossen werden soll |
duration | string | Ja | "5" oder "10" Sekunden |
aspect_ratio | string | Nein | "16:9" Standard |
mode | string | Nein | "standard" oder "professional" |
cfg_scale | float | Nein | Prompt-Treue (0.0-1.0) |
image_tail | string | Nein | URL des Endbilds (schließt sich gegenseitig mit Masken/Kamera aus) |
camera_control | object | Nein | Kamerabewegung (schließt sich gegenseitig mit Masken/image_tail aus) |
static_mask | string | Nein | URL der Maske für fixierte Bereiche |
dynamic_masks | array | Nein | Bewegungspinsel-Trajektorien |
callback_url | string | Nein | Webhook für den Abschluss |
Basis-Bild-zu-Video
import jwt, time, os, requests
BASE = "https://api.klingai.com/v1"
def get_headers():
ak, sk = os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{"iss": ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5},
sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}
)
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# Ein Landschaftsfoto animieren
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://example.com/landscape.jpg",
"prompt": "Wolken ziehen langsam über den Himmel, sanfter Wind raschelt durch Bäume",
"negative_prompt": "statisch, eingefroren, verschwommen",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# Auf Ergebnis warten
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/image2video/{task_id}", headers=get_headers()
).json()
if result["data"]["task_status"] == "succeed":
print(f"Video: {result['data']['task_result']['videos'][0]['url']}")
break
elif result["data"]["task_status"] == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
Start-zu-Ende-Übergang (image_tail)
Verwenden Sie image_tail, um sowohl den ersten als auch den letzten Frame anzugeben. Kling interpoliert die Bewegung zwischen ihnen.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/sunrise.jpg", # erster Frame
"image_tail": "https://example.com/sunset.jpg", # letzter Frame
"prompt": "Zeitraffer der Sonne, die sich über den Himmel bewegt",
"duration": "5",
"mode": "professional",
})
Bewegungspinsel (dynamic_masks)
Zeichnen Sie Bewegungspfade für bestimmte Elemente im Bild. Bis zu 6 Bewegungspfade pro Bild in v2.6.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"image": "https://example.com/person-standing.jpg",
"prompt": "Person geht natürlich vorwärts",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://example.com/person-mask.png", # weiß = ausgewählter Bereich
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # Startposition (normalisiert 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # Mittelpunkt
{"x": 0.5, "y": 0.3, "t": 1.0}, # Endposition
]
}
],
})
Statische Maske (Bereiche einfrieren)
Halten Sie bestimmte Bereiche des Bildes statisch, während der Rest animiert wird.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/scene.jpg",
"prompt": "Wasser fließt im Fluss, Vögel fliegen",
"duration": "5",
"static_mask": "https://example.com/buildings-mask.png", # weiß = eingefroren
})
Regeln zur gegenseitigen Ausschließlichkeit
Diese Funktionen können nicht in einer einzigen Anfrage kombiniert werden:
| Funktionssatz A | Funktionssatz B |
|---|---|
image_tail | dynamic_masks, static_mask, camera_control |
dynamic_masks / static_mask | image_tail, camera_control |
camera_control | image_tail, dynamic_masks, static_mask |
Bildanforderungen
| Einschränkung | Wert |
|---|---|
| Formate | JPG, PNG, WebP |
| Maximale Größe | 10 MB |
| Minimale Auflösung | 300x300 px |
| Maximale Auflösung | 4096x4096 px |
| Maskenformat | PNG mit weiß (ausgewählt) / schwarz (ausgeschlossen) |
Fehlerbehandlung
| Fehler | Ursache | Behebung |
|---|---|---|
400 ungültiges Bild | URL nicht erreichbar oder falsches Format | Überprüfen, ob die Bild-URL öffentlich zugänglich ist |
400 gegenseitige Ausschließlichkeit | Inkompatible Funktionen kombiniert | Nur einen Funktionssatz pro Anfrage verwenden |
task_status: failed | Bild zu komplex oder geringe Qualität | Höhere Auflösung, klareres Quellbild verwenden |
| Maskenkonflikt | Maskenabmessungen weichen vom Quellbild ab | Sicherstellen, dass die Maske den Abmessungen des Quellbilds entspricht |
Voraussetzungen
- Ein Kling-API-Anmeldedatensatz, der im Laufzeit-Geheimnisverwaltung gespeichert ist, eine genehmigte Modell- und Dauer-Erlaubnisliste sowie ein Budget für Credits pro Job.
- Ein synthetisches oder lizenzfreies Quellbild und ggf. ein Masken- oder Tail-Bild, mit dokumentierter Einwilligung für identifizierbare Personen und der Erlaubnis, das Asset zu transformieren.
- Ein privater Staging-Bucket und ein Review-Besitzer. Neue Generierungen müssen bis zur Freigabe durch Richtlinien, Qualitäts- und Veröffentlichungsgenehmigung als Entwurf und mit Wasserzeichen versehen bleiben.
Anweisungen
- Lösen Sie die Quell- und Maskenverweise aus einer genehmigten Erlaubnisliste auf; lehnen Sie Daten von nicht vertrauenswürdigen URLs, fehlender Herkunft oder Assets ab, die eine identifizierbare Person ohne dokumentierte Einwilligung enthalten.
- Validieren Sie Format, Abmessungen, gegenseitige Ausschließlichkeit von Funktionen, Promptlänge und die angeforderte Dauer, bevor Sie Credits ausgeben. Verwenden Sie eine synthetische Testumgebung für automatisierte Prüfungen.
- Deduplizieren Sie die Anfrage mit einem stabilen Job-Key, senden Sie sie erst ab, nachdem die Content-Policy-Prüfung bestanden wurde, und bewahren Sie die Aufgabe und die Quelle im privaten Staging-Speicher auf.
- Führen Sie einen kurzen, mit Wasserzeichen versehenen Sandbox-Canary aus. Überprüfen Sie Bewegung, Policy-Ergebnis, Quelltreue und das Credit-Budget, bevor Sie eine Besitzerfreigabe für einen größeren oder öffentlichen Render anfordern.
- Bei Freigabe das genaue Aufgabenergebnis über den Digest veröffentlichen. Bei Fehler oder Rückzug die nachgelagerte Veröffentlichung stoppen, gestagte Medien und temporäre URLs entfernen und den vorherigen genehmigten Asset- oder Job-Zustand wiederherstellen.
- Zeichnen Sie eine geschwärzte Quittung auf, die nur undurchsichtige Job- und Asset-Digests, Policy- und Genehmigungsergebnisse, Budgetergebnis, Aufbewahrungsfrist und Rollback-Referenz enthält.
Ausgabe
Geben Sie ein Ergebnis zurück, das die undurchsichtige Aufgabenkennung, das Modell und die Dauer, den Status, den Ausgabe-Digest oder die private Staging-URL, den Canary/Genehmigungsstatus sowie die Bereinigungs- oder Rollback-Referenz enthält. Geben Sie keine Quellbilder, Masken-URLs, Prompts, Gesichtsdaten, Anmeldeinformationen oder ungeschwärzte Anbieterantworten in Protokollen oder Quittungen aus.
Beispiele
Für eine sichere automatisierte Prüfung verwenden Sie eine synthetische Landschaftsvorlage und einen privaten Canary:
source=fixture:synthetic-landscape-v3; rights=cleared; mode=standard;
duration=5; canary=watermarked-sandbox; policy=pass; approval=pending;
publish=false; contacts_exported=0; receipt=asset-sha256:opaque
Ersetzen Sie kein echtes Kundenfoto und veröffentlichen Sie den Canary erst, wenn Einwilligung, Richtlinie, Qualität und Besitzerfreigabe dokumentiert sind.