Kling Imagen a video
Usa el endpoint de imagen a video para crear una tarea asíncrona.
Descripción general
Usa el endpoint de imagen a video con un modelo compatible. Usa el ID de tarea devuelto para recuperar su estado, o proporciona callback_url para las entregas documentadas a continuación.
Inicio rápido
- Cree una Clave de API y establézcala como RUNAPI_API_KEY.
- Elija un modelo compatible y envíe una solicitud POST cuyo cuerpo coincida con el esquema de ese modelo.
- Almacena el ID de tarea devuelto, luego sondea hasta alcanzar un estado terminal o gestiona las devoluciones de llamada documentadas a continuación.
Endpoint
- URL base
https://runapi.ai- Versión de la API
v1- Autenticación
Authorization: Bearer YOUR_API_TOKEN
Modelos compatibles
Abra una página de modelo para conocer los precios actuales, los límites de velocidad y los detalles de uso comercial.
Esquema de solicitud
Los campos y los valores permitidos dependen del modelo seleccionado. Cuando se proporciona, callback_url recibe las entregas de tareas documentadas a continuación.
kling-o113 campos
aspect_ratiostringRelación de aspecto de salida.
Valores permitidos:16:9, 9:16, 1:1
Valor predeterminado: 16:9
callback_urlstringURL de webhook para notificaciones asíncronas.
duration_secondsintegerDuración en segundos.
Valores permitidos:5
Valor predeterminado: 5
enable_soundbooleanLa generación de sonido debe permanecer desactivada.
Valor predeterminado:false
first_frame_image_urlstringURL pública HTTP(S) de imagen JPG, JPEG o PNG del primer fotograma.
last_frame_image_urlstringURL pública HTTP(S) de imagen JPG, JPEG o PNG del fotograma final; no se puede combinar con reference_image_urls ni reference_video_url.
modestringModo de generación.
Valores permitidos:std, pro
Valor predeterminado: std
modelstringIdentificador del modelo.
preserve_reference_video_audiobooleanConservar el audio original del vídeo de referencia.
Valor predeterminado:false
promptstringDescripción del video; referencia a medios con marcadores numerados correspondientes.
Rango:1 - 2500
reference_image_urlsarrayURL de imágenes de referencia JPG, JPEG o PNG públicas HTTP(S) ordenadas; no se puede combinar con last_frame_image_url.
Rango de elementos:1 - 7
reference_video_typestringUsa el video como base de edición o referencia de características.
Valores permitidos:base, feature
Valor predeterminado: base
reference_video_urlstringURL pública HTTP(S) de vídeo de referencia en formato MP4 o MOV; no se puede combinar con last_frame_image_url.
kling-v2.1-master-image-to-video9 campos
aspect_ratiostringRelación de aspecto de salida.
callback_urlstringURL de webhook para notificaciones asíncronas.
cfg_scalenumberEscala de guía (0-1).
duration_secondsintegerDuración en segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final para los modelos de imagen a video compatibles.
modelstringIdentificador del modelo.
negative_promptstringIndicación negativa.
promptstringDescripción del video.
kling-v2.1-pro9 campos
aspect_ratiostringRelación de aspecto de salida.
callback_urlstringURL de webhook para notificaciones asíncronas.
cfg_scalenumberEscala de guía (0-1).
duration_secondsintegerDuración en segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final para los modelos de imagen a video compatibles.
modelstringIdentificador del modelo.
negative_promptstringIndicación negativa.
promptstringDescripción del video.
kling-v2.1-standard9 campos
aspect_ratiostringRelación de aspecto de salida.
callback_urlstringURL de webhook para notificaciones asíncronas.
cfg_scalenumberEscala de guía (0-1).
duration_secondsintegerDuración en segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final para los modelos de imagen a video compatibles.
modelstringIdentificador del modelo.
negative_promptstringIndicación negativa.
promptstringDescripción del video.
kling-v2.5-turbo-image-to-video-pro9 campos
aspect_ratiostringRelación de aspecto de salida.
callback_urlstringURL de webhook para notificaciones asíncronas.
cfg_scalenumberEscala de guía (0-1).
duration_secondsintegerDuración en segundos.
Valores permitidos:5, 10
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final para los modelos de imagen a video compatibles.
modelstringIdentificador del modelo.
negative_promptstringIndicación negativa.
promptstringDescripción del video.
kling-v2.69 campos
aspect_ratiostringRelación de aspecto de salida.
Valores permitidos:16:9, 9:16, 1:1
Valor predeterminado: 16:9
callback_urlstringURL de webhook para notificaciones asíncronas.
duration_secondsintegerDuración en segundos.
Valores permitidos:5, 10
Valor predeterminado: 5
enable_soundbooleanActivar la generación de sonido; requiere el modo pro.
Valor predeterminado:false
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final; requiere el modo pro y 5 segundos.
modestringModo de generación.
Valores permitidos:std, pro
Valor predeterminado: std
modelstringIdentificador del modelo.
promptstringDescripción del video.
Rango:1 - 2500
kling-v3-omni9 campos
aspect_ratiostringRelación de aspecto de salida.
Valores permitidos:16:9, 9:16, 1:1
Valor predeterminado: 16:9
callback_urlstringURL de webhook para notificaciones asíncronas.
duration_secondsintegerDuración en segundos.
Valores permitidos:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Valor predeterminado: 5
enable_soundbooleanActivar la generación de sonido sincronizado.
Valor predeterminado:false
first_frame_image_urlstringURL de imagen del primer fotograma.
last_frame_image_urlstringURL de imagen del fotograma final; requiere una duración de 5 segundos.
modelstringIdentificador del modelo.
output_resolutionstringResolución de salida.
Valores permitidos:720p, 1080p, 4k
Valor predeterminado: 720p
promptstringDescripción del video.
Rango:1 - 2500
kling-v3-turbo-image-to-video6 campos
callback_urlstringURL de webhook para notificaciones asíncronas.
duration_secondsintegerDuración en segundos.
Valores permitidos:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Valor predeterminado: 5
first_frame_image_urlstringURL de imagen del primer fotograma.
modelstringIdentificador del modelo.
output_resolutionstringResolución de salida.
Valores permitidos:720p, 1080p
Valor predeterminado: 720p
promptstringDescripción del video.
Rango:1 - 2500
Reglas condicionales
Estos requisitos se aplican cuando todas las condiciones enumeradas coinciden.
-
Cuando
model = kling-o1- Obligatorio
- No aceptado
output_resolution,negative_prompt,cfg_scale
-
Cuando
model = kling-v2.1-master-image-to-video- Obligatorio
- No aceptado
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v2.1-pro- Obligatorio
- No aceptado
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v2.1-standard- Obligatorio
- No aceptado
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v2.5-turbo-image-to-video-pro- Obligatorio
- No aceptado
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v2.6- Obligatorio
- No aceptado
output_resolution,negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v3-omni- Obligatorio
- No aceptado
negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
Cuando
model = kling-v3-turbo-image-to-video- Obligatorio
- No aceptado
enable_sound,aspect_ratio,negative_prompt,cfg_scale,last_frame_image_url,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
Crear aceptación
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta en proceso
GET /api/v1/kling/image_to_video/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta completada
GET /api/v1/kling/image_to_video/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}
Consulta fallida
GET /api/v1/kling/image_to_video/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
Devolución de llamada del cliente: completado
POST callback_url
Esquema de respuesta
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}
Devolución de llamada del cliente: fallido
POST callback_url
Esquema de respuesta
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Authentication required"
}
Errores
GET /api/v1/kling/image_to_video/:id
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Authentication required"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumen de validación legible por personas.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
Ejemplo de respuesta
{
"error": "model must be one of: kling-o1, kling-v2.1-master-image-to-video, kling-v2.1-pro, kling-v2.1-standard, kling-v2.5-turbo-image-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-turbo-image-to-video"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Insufficient balance"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "API key credit limit exceeded"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "The request uses features that are not supported for the selected model"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Rate limit reached. Please retry later."
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Service under maintenance, please try again later"
}
Errores
POST /api/v1/kling/image_to_video
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "The request timed out"
}
Errores
GET /api/v1/kling/image_to_video/:id
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Task with id 'tsk_reference_demo' not found"
}
Ejemplos de código generados
Usa cURL directamente o instala un SDK para tu lenguaje. Cada muestra envía la solicitud validada que se muestra en esta referencia.
Instalar
pip install runapi-kling
import os
from runapi.kling import KlingClient
client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.image_to_video.create(
model="kling-o1",
prompt="A gentle camera pan across the scene.",
first_frame_image_url="https://file.runapi.ai/first-frame.png"
)