Generación de vídeo

Endpoints: POST /v1/video/generations (síncrono, explicado primero) y POST /v1/videos + GET /v1/videos/{id} (asíncrono, recomendado para producción). La generación tarda de 30 segundos a varios minutos, según el modelo y la duración; para el endpoint síncrono, establece un tiempo de espera generoso en el cliente (600s es un valor seguro).

Generación de vídeo a partir de texto

Pasa un prompt y elige un modelo. aspect_ratio es opcional.

import requests

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "a cinematic dolly-in on a red origami crane unfolding, soft light",
        "aspect_ratio": "16:9",
    },
    timeout=600,  # video generation can take minutes
)
print(resp.json()["data"][0]["url"])

duration (en segundos) define la duración del clip en los modelos con facturación por segundo: los modelos Seedance y el modelo Wan 2.7. Los modelos Veo lo ignoran; cada clip de Veo dura 8 segundos y se factura por vídeo.

# The models billed per second take a clip length: here 5 seconds of
# Seedance 2. Leave "duration" out and these models make a 5-second clip.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "seedance-2",
        "prompt": "a paper crane unfolds into a flock of birds over a city at dawn",
        "duration": 5,
        "aspect_ratio": "16:9",
    },
    timeout=600,
)
print(resp.json()["data"][0]["url"])

Imagen a vídeo

Añade un image_url y Veo lo animará; de forma predeterminada, la imagen fija se convierte en el primer fotograma del vídeo.

# Image-to-video: animate a still image. The source image can be an
# https URL, or inline base64 — Kunavo hosts it for the model automatically.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "the crane gently lifts off the desk",
        "image_url": "https://your-cdn.com/source.png",
    },
    timeout=600,
)
print(resp.json()["data"][0]["url"])

Primer fotograma, último fotograma y referencias

image_mode controla cómo usa Veo las imágenes. Pasa image_urls (un array) para enviar más de una.

• frame (predeterminado): una imagen sirve como primer fotograma; dos imágenes sirven como primer y último fotograma, y Veo genera la transición entre ellas.
• reference: hasta tres imágenes sirven como referencias de estilo y tema. Orientan el aspecto, pero nunca aparecen como fotogramas.

# First + last frame: pass two images and Veo fills in the motion.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "a smooth transition between the two poses",
        "image_urls": [
            "https://your-cdn.com/first.png",
            "https://your-cdn.com/last.png",
        ],
        "image_mode": "frame",
    },
    timeout=600,
)

Subir un fotograma de origen

Si solo tienes un archivo local, súbelo una vez mediante POST /v1/files y reutiliza la URL permanente que se devuelve.

# No public URL? Upload the still first, then animate it.
with open("frame.png", "rb") as f:
    up = requests.post(
        "https://api.kunavo.com/v1/files",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
    ).json()

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "slow push-in, volumetric light",
        "image_url": up["url"],
    },
    timeout=600,
)

Parámetros

Mecanismo alternativo para entrada sin procesar

En los modelos con facturación por segundo, input se envía tal cual al proveedor ascendente, en lugar de la entrada que crearía nuestro adaptador. Los modelos Veo lo ignoran.

Los campos que determinan el precio son la excepción: resolution siempre se envía como uno de los niveles del modelo (el nivel predeterminado si se omite o no corresponde a ninguno de ellos), y duration debe ser un número entero de segundos dentro del rango del modelo (cualquier otro valor se rechaza con un error 400; se envía 5 si se omite). No se leen resolution ni duration de la propia solicitud cuando se establece input.

Modelos de vídeo

Consulta siempre /models para ver la lista actualizada y los precios por modelo.

Latencia y tiempos de espera

• Kunavo consulta la tarea al proveedor ascendente durante un máximo de 540 segundos antes de devolver un 504.
• Niveles rápidos (Veo 3.1 Fast / Lite): a menudo, 30–90s.
• Niveles de calidad y duraciones más largas: 2–5 minutos.
• Establece el tiempo de espera de tu cliente HTTP en al menos 600s.
• En redes inestables o clientes móviles, prefiere la API asíncrona: el envío tarda unos segundos y luego consultas el resultado.

API asíncrona (enviar + consultar)

Endpoints: POST /v1/videos + GET /v1/videos/{id}. El objeto de tarea que devuelven utiliza los nombres de campo y los valores de estado del objeto de video de OpenAI, y añade output con la URL del clip. La solicitud es un cuerpo JSON con los parámetros anteriores.

El endpoint síncrono anterior mantiene abierta una conexión HTTP durante un máximo de nueve minutos; resulta práctico para scripts de una sola llamada, pero no es fiable en dispositivos móviles y consume recursos del servidor de forma ineficiente. El par asíncrono devuelve de inmediato un identificador vid_*; consulta GET /v1/videos/{id} hasta que status tenga el valor completed o failed. Los modelos, los precios y las URL archivadas son los mismos.

import requests, time

# 1. Submit — returns immediately with a task id. No long-lived connection.
submit = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        # Optional: retrying with the same key inside ~24h returns the
        # original task rather than submitting again.
        "Idempotency-Key": "my-task-uuid",
    },
    json={
        "model": "veo-3",
        "prompt": "a cinematic dolly-in on a red origami crane",
        "aspect_ratio": "16:9",
    },
    timeout=60,
).json()

task_id = submit["id"]              # "vid_abc..."
status  = submit["status"]          # "queued"

# 2. Poll until terminal. Recommended cadence: 5s, backing off to 30s.
while status not in ("completed", "failed"):
    time.sleep(5)
    r = requests.get(
        f"https://api.kunavo.com/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    ).json()
    status = r["status"]

if status == "failed":
    raise RuntimeError(r["error"]["message"])
print(r["output"]["url"])

Desde el SDK de OpenAI, envía ese cuerpo con client.post y consulta el estado con client.get, como se muestra a continuación. El método client.videos.create propio del SDK no funciona aquí: solo acepta los parámetros de Sora y los envía como un formulario multipart (en el SDK de Python desde la versión 2.27.0), que este endpoint rechaza con un error 400.

import time
from openai import OpenAI

client = OpenAI(api_key=API_KEY, base_url="https://api.kunavo.com/v1")

# The same JSON body, sent with the client's own post().
task = client.post(
    "/videos",
    body={
        "model": "veo-3",
        "prompt": "a cinematic dolly-in on a red origami crane",
        "aspect_ratio": "16:9",
    },
    # object hands back the JSON as parsed. Passing dict instead raises
    # after the task has been created.
    cast_to=object,
    options={"headers": {"Idempotency-Key": "my-task-uuid"}},
)

while task["status"] not in ("completed", "failed"):
    time.sleep(5)
    task = client.get(f"/videos/{task['id']}", cast_to=object)

if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])
print(task["output"]["url"])

Formato de la respuesta

Encabezados y convenciones

• Idempotency-Key (opcional, hasta 128 caracteres): si se envía dos veces la misma clave en la misma cuenta, se devuelve la tarea original en vez de crear un duplicado. Útil para reintentar solicitudes.
• POST /v1/videos devuelve 202 Accepted en un envío nuevo y 200 OK cuando una clave de idempotencia permite recuperar un resultado anterior.
• GET /v1/videos/{id} está limitado al propietario: consultar una tarea de otra cuenta devuelve 404. Nunca confirmamos que exista un identificador que pertenezca a otra persona.
• Frecuencia de consulta recomendada: cada 5 s, con retroceso exponencial hasta 30 s. Las tareas suelen completarse en 30 s–5 min, según el modelo y la resolución.

Cuándo usar cada uno

Respuesta y almacenamiento

La respuesta tiene el formato estándar de OpenAI: data[].url. La URL es un enlace permanente a files.kunavo.com: Kunavo archiva cada resultado en su propia CDN, así que, a diferencia de las URL directas del proveedor, nunca caduca. Todos los clips también aparecen en /app/assets.

Próximos pasos

• Generación de imágenes y endpoint de carga /v1/files
• Errores y el caso del tiempo de espera agotado con 504