Kling AI Image-à-Vidéo
Présentation
Animez des images statiques en utilisant l'endpoint /v1/videos/image2video. Prend en charge les indications de mouvement, le contrôle de caméra, les masques dynamiques (pinceau de mouvement), les masques statiques et les images de fin pour les transitions début-fin.
Endpoint : POST https://api.klingai.com/v1/videos/image2video
Paramètres de la requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
model_name | chaîne | Oui | kling-v1-5, kling-v2-1, kling-v2-master, etc. |
image | chaîne | Oui | URL de l'image source (JPG, PNG, WebP) |
prompt | chaîne | Non | Description du mouvement pour l'animation |
negative_prompt | chaîne | Non | Ce qu'il faut exclure |
duration | chaîne | Oui | "5" ou "10" secondes |
aspect_ratio | chaîne | Non | "16:9" par défaut |
mode | chaîne | Non | "standard" ou "professional" |
cfg_scale | flottant | Non | Adhérence aux indications (0.0-1.0) |
image_tail | chaîne | Non | URL de l'image de fin (mutuellement exclusif avec masques/caméra) |
camera_control | objet | Non | Mouvement de caméra (mutuellement exclusif avec masques/image_tail) |
static_mask | chaîne | Non | URL de l'image du masque pour les zones figées |
dynamic_masks | tableau | Non | Trajectoires du pinceau de mouvement |
callback_url | chaîne | Non | Webhook pour la notification d'achèvement |
Image-à-Vidéo Basique
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"}
# Animer une photo de paysage
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://example.com/landscape.jpg",
"prompt": "Nuages dérivant lentement dans le ciel, vent doux bruissant dans les arbres",
"negative_prompt": "statique, figé, flou",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# Interroger le résultat
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"Vidéo : {result['data']['task_result']['videos'][0]['url']}")
break
elif result["data"]["task_status"] == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
Transition Début-Fin (image_tail)
Utilisez image_tail pour spécifier à la fois la première et la dernière image. Kling interpole le mouvement entre elles.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/sunrise.jpg", # première image
"image_tail": "https://example.com/sunset.jpg", # dernière image
"prompt": "Accéléré du soleil se déplaçant dans le ciel",
"duration": "5",
"mode": "professional",
})
Pinceau de Mouvement (dynamic_masks)
Dessinez des trajectoires de mouvement pour des éléments spécifiques de l'image. Jusqu'à 6 trajectoires par image en 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": "Personne marchant en avant naturellement",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://example.com/person-mask.png", # blanc = région sélectionnée
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # position de départ (normalisée 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # point médian
{"x": 0.5, "y": 0.3, "t": 1.0}, # position de fin
]
}
],
})
Masque Statique (zones figées)
Gardez des zones spécifiques de l'image statiques tout en animant le reste.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/scene.jpg",
"prompt": "Eau coulant dans la rivière, oiseaux volant",
"duration": "5",
"static_mask": "https://example.com/buildings-mask.png", # blanc = figé
})
Règles d'Exclusivité Mutuelle
Ces fonctionnalités ne peuvent pas être combinées dans une seule requête :
| Ensemble de Fonctionnalités A | Ensemble de Fonctionnalités 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 |
Exigences de l'Image
| Contrainte | Valeur |
|---|---|
| Formats | JPG, PNG, WebP |
| Taille max | 10 Mo |
| Résolution min | 300x300 px |
| Résolution max | 4096x4096 px |
| Format du masque | PNG avec blanc (sélectionné) / noir (exclu) |
Gestion des Erreurs
| Erreur | Cause | Correction |
|---|---|---|
400 image invalide | URL inaccessible ou mauvais format | Vérifiez que l'URL de l'image est accessible publiquement |
400 mutuellement exclusif | Fonctionnalités incompatibles combinées | Utilisez un seul ensemble de fonctionnalités par requête |
task_status: failed | Image trop complexe ou de mauvaise qualité | Utilisez une résolution plus élevée, une source plus claire |
| Mauvais format du masque | Les dimensions du masque diffèrent de la source | Assurez-vous que le masque correspond aux dimensions de l'image source |
Prérequis
- Une clé API Kling stockée dans le gestionnaire de secrets d'exécution, une liste autorisée de modèles et de durées approuvés, et un budget de crédits par tâche.
- Une image source synthétique ou libre de droits, ainsi que toute image de masque ou de fin, avec consentement enregistré pour les personnes identifiables et autorisation de transformer l'actif.
- Un bucket de staging privé et un propriétaire de révision. Les nouvelles générations doivent rester en projet et filigranées jusqu'à ce que l'approbation de la politique, de la qualité et de la publication soient enregistrées.
Instructions
- Résoudre les références source et de masque à partir d'une liste autorisée ; rejeter les données provenant d'URL non fiables, de provenance manquante ou d'actifs contenant une personne identifiable sans consentement documenté.
- Valider le format, les dimensions, l'exclusivité mutuelle des fonctionnalités, la longueur de l'indication et la durée demandée avant de dépenser des crédits. Utiliser une fixture synthétique pour les contrôles automatisés.
- Dédupliquer la requête à l'aide d'une clé de tâche stable, soumettre uniquement après que la vérification de la politique de contenu soit réussie, et conserver la tâche et la source dans le stockage de staging privé.
- Exécuter un canari de bac à sable court et filigrané. Vérifier le mouvement, le résultat de la politique, la fidélité à la source et le budget de crédits avant de demander une approbation du propriétaire pour un rendu plus grand ou public.
- Sur approbation, promouvoir le résultat exact de la tâche par son condensé. En cas d'échec ou de retrait, arrêter la publication en aval, supprimer les médias temporaires et les URL temporaires, et restaurer l'état de l'actif ou de la tâche approuvé précédemment.
- Enregistrer un reçu expurgé contenant uniquement les condensés opaques de la tâche et de l'actif, les résultats de la politique et de l'approbation, le résultat budgétaire, la date limite de conservation et la référence de restauration.
Sortie
Retourner un résultat contenant l'identifiant opaque de la tâche, le modèle et la durée, le statut, le condensé de sortie ou l'URL de staging privé, l'état du canari/de l'approbation, et la référence de nettoyage ou de restauration. Ne pas inclure les images source, les URL de masques, les indications, les données faciales, les identifiants ou les réponses non expurgées des fournisseurs dans les journaux ou les reçus.
Exemples
Pour un contrôle automatisé sûr, utilisez une fixture de paysage synthétique et un canari privé :
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
Ne pas substituer une photographie réelle d'un client ni publier le canari tant que le consentement, la politique, la qualité et l'approbation du propriétaire ne sont pas tous enregistrés.