La API de Kling 4.0 en PoYo usa un único ID de modelo, kling-4.0, para texto a vídeo, generación con primer y último fotograma, referencias visuales y edición de vídeo. Envías una solicitud, guardas su ID de tarea y consultas su estado hasta que termina. Esta guía sigue el esquema actual de PoYo, revisado el 24 de octubre de 2026; los nombres de campo de otros proveedores no son intercambiables.
Abre el playground de Kling 4.0 para probar las entradas de forma visual o consulta la documentación de la API.
Genera tu primer vídeo con cURL
Define POYO_API_KEY en el entorno de tu shell y envía esta solicitud de cinco segundos. Guarda la credencial en tu servidor, nunca en código que se ejecute en el navegador.
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-4.0",
"input": {
"prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}'
Lee data.task_id en la respuesta JSON; que el envío se acepte no significa que el vídeo esté terminado. Sustituye YOUR_TASK_ID por ese valor en la siguiente llamada:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Los estados documentados son not_started, running, finished y failed. Cuando la tarea termina, busca en data.files el file_url del vídeo. Si falla, revisa error_message y conserva el ID de tarea para el diagnóstico. Consultar una tarea existente no requiere volver a enviarla.
Un bucle de sondeo acotado en Python
Instala requests y ejecuta esto en tu backend. Comprueba tanto los errores HTTP como los de la aplicación, se detiene si la tarea falla y limita la espera a 30 minutos. Si se agota el tiempo, vuelve a consultar la misma tarea más tarde; repetir el envío automáticamente podría crear un segundo trabajo facturable.
import os
import time
import requests
base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") not in (0, 200):
raise RuntimeError(body.get("message") or "PoYo API error")
return body["data"]
task = checked(session.post(base + "/api/generate/submit", json={
"model": "kling-4.0",
"input": {
"prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
task = checked(session.get(
base + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "Generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", [])
if f.get("file_type") == "video"]
if not videos:
raise RuntimeError("Finished task returned no video")
print(videos[0])
break
time.sleep(10)
else:
raise TimeoutError("Check the saved task ID again: " + task_id)
Elige el modo de entrada correcto
| Objetivo | Campos dentro de input | Restricción importante |
|---|---|---|
| Texto a vídeo | prompt o multi_prompt | Indica exactamente uno |
| Primer y último fotograma | image_urls con una o dos URL ordenadas | Omite aspect_ratio |
| Generación con referencias | reference_image_urls, reference_video_urls o kling_elements | Como máximo un primer fotograma opcional |
| Editar metraje | video_url y prompt | Sin image_urls, multi_prompt, reference_video_urls ni aspect_ratio |
El campo del vídeo de origen activa el modo de edición aunque también haya imágenes de referencia. En imagen a vídeo, la primera imagen fija el fotograma inicial y una segunda imagen define el fotograma final. Las imágenes de referencia orientan la identidad o el estilo y no equivalen a fotogramas de inicio o fin.
Límites que conviene validar antes de enviar
La generación admite duraciones enteras de 3 a 30 segundos, en 720p o 1080p. En este esquema de PoYo, un prompt normal está limitado a 26.000 caracteres. Cada plano de multi_prompt acepta hasta 512 caracteres; si omites la duración del plano, se usan cinco segundos por defecto. La suma de las duraciones de los planos debe estar entre 3 y 30 segundos, y si indicas una duración explícita en el nivel superior, debe coincidir con ese total.
Las referencias admiten hasta 10 imágenes, cinco vídeos y siete sujetos, con un límite conjunto de 15 recursos. Un primer fotograma cuenta tanto para el límite de imágenes como para el total. Cada vídeo de referencia o de sujeto debe durar entre 3 y 30 segundos, y su duración real combinada no puede superar los 30 segundos. No redondees las duraciones a la baja para que una entrada demasiado grande pase la validación.
Entiende tu primera factura
Una solicitud de cinco segundos en 720p sin entrada de vídeo cuesta 142,5 créditos, es decir, 0,7125 $ con la conversión publicada actualmente. Una entrada de vídeo cambia tanto la tarifa como la duración facturable. Consulta los ejemplos de precios antes de estimar un flujo con vídeo de referencia o de edición.
El producto oficial para creadores anuncia controles adicionales, como varios fotogramas clave. El esquema de PoYo expone aquí hasta dos fotogramas de inicio y fin y prompts por plano; no envíes a este endpoint campos inventados como keyframes, seed, negative_prompt o generate_audio. Para ver ejemplos que funcionan, sigue con la guía de prompts y el tutorial de Omni Reference.
Preguntas frecuentes
¿El ID de modelo de la API es kling-4-0? No. Ese es el slug de la página. El ID de modelo de la solicitud es kling-4.0.
¿Puedo pedir 4K aquí? Este endpoint de PoYo solo acepta actualmente 720p y 1080p. Consulta el esquema del proveedor en lugar de copiar las especificaciones de marketing de la app para creadores.
¿Puedo usar un callback? La solicitud de envío admite un callback_url en el nivel superior. Consulta la documentación actual para gestionar los callbacks; el ejemplo de sondeo anterior no depende de ello.
¿Por dónde empiezo? Haz primero una solicitud corta solo con texto, guarda su ID de tarea y el resultado, y después añade una modalidad de entrada cada vez en el playground.