Kling AI Imagen a Video
Resumen
Anima imágenes estáticas usando el endpoint /v1/videos/image2video. Soporta prompts de movimiento, control de cámara, máscaras dinámicas (pincel de movimiento), máscaras estáticas e imágenes de cola para transiciones de inicio a fin.
Endpoint: POST https://api.klingai.com/v1/videos/image2video
Parámetros de Solicitud
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model_name | string | Sí | kling-v1-5, kling-v2-1, kling-v2-master, etc. |
image | string | Sí | URL de la imagen fuente (JPG, PNG, WebP) |
prompt | string | No | Descripción del movimiento para la animación |
negative_prompt | string | No | Qué excluir |
duration | string | Sí | "5" o "10" segundos |
aspect_ratio | string | No | "16:9" por defecto |
mode | string | No | "standard" o "professional" |
cfg_scale | float | No | Adherencia al prompt (0.0-1.0) |
image_tail | string | No | URL de la imagen del fotograma final (mutuamente excluyente con máscaras/cámara) |
camera_control | object | No | Movimiento de cámara (mutuamente excluyente con máscaras/image_tail) |
static_mask | string | No | URL de la imagen de máscara para regiones fijas |
dynamic_masks | array | No | Trayectorias del pincel de movimiento |
callback_url | string | No | Webhook para notificación de finalización |
Imagen a Video Básico
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"}
# Animar una foto de paisaje
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://example.com/landscape.jpg",
"prompt": "Nubes derivando lentamente por el cielo, viento suave moviendo los árboles",
"negative_prompt": "estático, congelado, borroso",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# Consultar el resultado
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"])
Transición Inicio-Fin (image_tail)
Usa image_tail para especificar tanto el primer como el último fotograma. Kling interpola el movimiento entre ellos.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/sunrise.jpg", # primer fotograma
"image_tail": "https://example.com/sunset.jpg", # último fotograma
"prompt": "Time-lapse del sol moviéndose por el cielo",
"duration": "5",
"mode": "professional",
})
Pincel de Movimiento (dynamic_masks)
Dibuja trayectorias de movimiento para elementos específicos de la imagen. Hasta 6 trayectorias por imagen 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": "Persona caminando hacia adelante de forma natural",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://example.com/person-mask.png", # blanco = región seleccionada
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # posición inicial (normalizada 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # punto medio
{"x": 0.5, "y": 0.3, "t": 1.0}, # posición final
]
}
],
})
Máscara Estática (congelar regiones)
Mantén áreas específicas de la imagen estáticas mientras se anima el resto.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/scene.jpg",
"prompt": "Agua fluyendo en el río, pájaros volando",
"duration": "5",
"static_mask": "https://example.com/buildings-mask.png", # blanco = congelado
})
Reglas de Exclusividad Mutua
Estas características no se pueden combinar en una sola solicitud:
| Conjunto de Características A | Conjunto de Características 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 |
Requisitos de Imagen
| Restricción | Valor |
|---|---|
| Formatos | JPG, PNG, WebP |
| Tamaño máximo | 10 MB |
| Resolución mínima | 300x300 px |
| Resolución máxima | 4096x4096 px |
| Formato de máscara | PNG con blanco (seleccionado) / negro (excluido) |
Manejo de Errores
| Error | Causa | Solución |
|---|---|---|
400 imagen inválida | URL inaccesible o formato incorrecto | Verifica que la URL de la imagen sea de acceso público |
400 exclusividad mutua | Características incompatibles combinadas | Usa solo un conjunto de características por solicitud |
task_status: failed | Imagen demasiado compleja o de baja calidad | Usa una resolución más alta, fuente más clara |
| Desajuste de máscara | Las dimensiones de la máscara difieren de la fuente | Asegúrate de que la máscara coincida con las dimensiones de la imagen fuente |
Requisitos Previos
- Una credencial de API de Kling almacenada en el gestor de secretos en tiempo de ejecución, una lista blanca de modelos y duraciones aprobados, y un presupuesto de crédito por trabajo.
- Una imagen fuente sintética o con derechos autorizados liberados, y cualquier máscara o imagen de cola, con consentimiento documentado para personas identificables y permiso para transformar el activo.
- Un depósito de almacenamiento privado para preparación y un revisor de propiedad. Las nuevas generaciones deben permanecer solo como borrador y con marca de agua hasta que se registre la aprobación de política, calidad y publicación.
Instrucciones
- Resuelve las referencias de fuente y máscara de una lista blanca aprobada; rechaza datos de URLs no confiables, sin procedencia documentada, o activos que contengan una persona identificable sin consentimiento documentado.
- Valida el formato, dimensiones, exclusividad mutua de características, longitud del prompt y la duración solicitada antes de gastar créditos. Usa un fixture sintético para comprobaciones automatizadas.
- Desduplica la solicitud usando una clave de trabajo estable, envía solo después de que pase la verificación de política de contenido, y mantén la tarea y la fuente en almacenamiento privado de preparación.
- Ejecuta un canario de prueba corto con marca de agua en entorno sandbox. Verifica el movimiento, el resultado de la política, la fidelidad de la fuente y el presupuesto de crédito antes de solicitar una aprobación del propietario para una representación más grande o pública.
- Tras la aprobación, promociona el resultado exacto de la tarea mediante su resumen digital. En caso de fallo o retirada, detén la publicación posterior, elimina los medios preparados y las URLs temporales, y restaura el activo aprobado anterior o el estado del trabajo.
- Registra un recibo con información reducida que contenga solo identificadores opacos de trabajos y activos, resultados de política y aprobación, resultado del presupuesto, fecha límite de retención y referencia de reversión.
Salida
Devuelve un resultado que contenga el identificador de tarea opaco, el modelo y la duración, el estado, el resumen digital de salida o la URL de almacenamiento privado de preparación, el estado de canario/aprobación, y la referencia de limpieza o reversión. No incluyas imágenes fuente, URLs de máscara, prompts, datos faciales, credenciales o respuestas no redactadas del proveedor en registros o recibos.
Ejemplos
Para una comprobación automatizada segura, usa un fixture sintético de paisaje y un canario privado:
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
No sustituyas una fotografía real de un cliente ni publiques el canario hasta que el consentimiento, la política, la calidad y la aprobación del propietario estén documentados.