¿Cómo usar la API de Vidu Q4 Preview de imagen a video? Genera un video 4K con audio en 5 minutos

TL;DR

• Qué es: Vidu Q4 Preview de imagen a video ya está disponible en HiAPI; abre la página del modelo, sube un primer fotograma y escribe una frase de acción para obtener un video de 3 a 16 segundos, hasta 4K, con audio nativo activado por defecto. Los nuevos usuarios reciben 200 créditos al registrarse.
• Cuánto cuesta: se cobra por los segundos enteros enviados multiplicados por el precio unitario de la resolución elegida: 540p $0.0515/s, 720p $0.109/s, 1080p $0.1375/s, 2K $0.2175/s, 4K $0.446/s. 5 segundos en 720p cuestan $0.545; 5 segundos en 4K cuestan $2.23. El interruptor audio no influye en el precio.
• Cómo llamarlo lo más rápido: en la página del modelo sube el primer fotograma, elige 720p y 5 segundos y ejecuta directamente; para integrarlo en tu producto usa POST https://api.hiapi.ai/v1/tasks con model establecido en vidu-q4-preview/image-to-video.

¿Qué es Vidu Q4 Preview? Qué añade respecto a Q3 Mix

Su única entrada es un primer fotograma. La composición, el ángulo de cámara, la iluminación y el formato quedan fijados por esa imagen; el modelo se encarga de completar el movimiento, el desplazamiento de cámara y el sonido, y entrega un MP4.

En comparación con el video de referencia a video de Q3 Mix, el imagen a video de Q4 trae tres cambios concretos:

• Un solo primer fotograma llega a 3–16 segundos. No hace falta preparar varias imágenes de referencia; una sola basta para sostener todo el plano. La duración se indica en segundos enteros y por defecto es 5 segundos.
• Hasta 4K. Hay cinco opciones: 540p, 720p, 1080p, 2K y 4K; el límite del video de referencia a video de Q3 Mix era 1080P, y Q4 lleva el imagen a video hasta 4K.
• Audio nativo activado por defecto. audio es true por defecto; los sonidos ambientales, diálogos y efectos indicados en el prompt se generan junto con el video. Solo si se establece en false se obtiene un video sin sonido, sin cambio de precio.
• Superficie de parámetros muy reducida. Solo hay cinco campos: image_url, prompt, duration, resolution y audio. No existe aspect_ratio; si se envía, devuelve 400. El formato sigue únicamente al primer fotograma.

El siguiente hidroavión es un video de 5 segundos en 720p generado a partir de un único primer fotograma; el acercamiento de cámara, el arranque de la hélice y las ondas en el agua están en el prompt:

El piloto saluda, el motor del hidroavión arranca, la hélice comienza a girar, se forman ondas en el agua, la cámara avanza lentamente, luz dorada del amanecer.

Generar con este prompt → El enlace solo rellena previamente el prompt de texto; después de abrirlo tendrás que subir el primer fotograma y establecer la resolución en 720p y la duración en 5 segundos.

Prueba en línea: el primer video en 5 pasos

1. Abre la página del modelo Vidu Q4 Preview de imagen a video; tras iniciar sesión, las cuentas nuevas tienen 200 créditos.
2. Sube el primer fotograma; se admiten JPG/JPEG/PNG/WEBP y un máximo de 50 MB por imagen. Asegúrate de que ese fotograma sea el segundo 0 que deseas.
3. En el campo de prompt escribe solo la acción, el movimiento de cámara y el sonido que quieres añadir; no repitas lo que ya aparece en la imagen.
4. Elige una duración en segundos enteros entre 3 y 16; empieza con 5. Para la resolución, elige primero 720p. Mantén el audio activado.
5. Envía la solicitud, descarga el video cuando esté listo y luego decide si quieres volver a generarlo con mayor resolución.

200 créditos equivalen aproximadamente a $0.10, insuficiente para un video de 3 segundos en 540p; se recomienda recargar $10 para probar el primer nivel.

Integración con la API: 4 pasos para ponerla en marcha

1. Crea una API Key en la consola.
2. Haz POST https://api.hiapi.ai/v1/tasks, escribe vidu-q4-preview/image-to-video en model y coloca los campos dentro de input.
3. Tras obtener el taskId, consulta periódicamente GET /v1/tasks/{taskId} o configura callback en el nivel superior del cuerpo de la solicitud.
4. Cuando status pase a success, descarga el MP4 desde output[0].url.

curl ejecutable

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-q4-preview/image-to-video",
    "input": {
      "image_url": "https://your-cdn.com/first-frame.jpg",
      "prompt": "El piloto saluda, el motor del hidroavión arranca, la hélice comienza a girar, se forman ondas en el agua, la cámara avanza lentamente, luz dorada del amanecer.",
      "duration": 5,
      "resolution": "720p",
      "audio": true
    }
  }'

El ID de la tarea está en data.taskId; al consultar, incluye la misma Bearer Key:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status pasa por queued, handling, archiving, success o fail. archiving significa que todavía se está procesando, no es un fallo.

Versión Python: crear, consultar y descargar

import time
import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "vidu-q4-preview/image-to-video",
    "input": {
        "image_url": "https://your-cdn.com/first-frame.jpg",
        "prompt": "El piloto saluda, el motor del hidroavión arranca, la hélice comienza a girar, se forman ondas en el agua, la cámara avanza lentamente, luz dorada del amanecer.",
        "duration": 5,
        "resolution": "720p",
        "audio": True,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(5)

if data["status"] == "success":
    with open("vidu-q4.mp4", "wb") as f:
        f.write(requests.get(data["output"][0]["url"], timeout=120).content)
    print("saved vidu-q4.mp4")
else:
    print(data.get("error"))

Las tareas de video suelen tardar de decenas de segundos a varios minutos; un intervalo de consulta de 5 segundos es suficiente, y se recomienda fijar un límite de tiempo de espera de 10–15 minutos.

Cómo configurar el primer fotograma, el formato, el audio y la resolución

El primer fotograma determina el formato. No existe el campo aspect_ratio; la proporción del video final hereda por completo la del primer fotograma, con un rango de relación de aspecto de 1:4 a 4:1. Si quieres un formato vertical, recorta primero el primer fotograma a 9:16 y luego súbelo; si subes una imagen vertical de 4:7, el video final también será 4:7.

El audio viene incluido por defecto. En el prompt de este video de 5 segundos en 720p de la barista se indican murmullos de cafetería y el sonido del vapor de la máquina de café; el audio se genera junto con el video:

La barista deja la jarra de leche, el latte art de la taza toma forma de hoja, se eleva vapor; ella levanta la mirada hacia la cámara y sonríe. De fondo, murmullos de cafetería y el sonido del vapor de la máquina de café. Acercamiento lento a cámara en mano, luz cálida de la mañana entra por la ventana.

Generar con este prompt → Después de abrirlo también tendrás que subir este primer fotograma vertical y elegir la resolución 720p.

Si se establece audio en false, el video sale sin sonido y el precio no cambia. Actívalo solo cuando necesites imagen pura y vayas a añadir música por separado en posproducción.

Elige la resolución según la etapa. Para probar la dirección usa 540p o 720p; cuando esté definido, pasa a 2K / 4K. 4K cuesta $0.446 por segundo, unas 8.7 veces más que 540p; un video de 16 segundos en 4K cuesta $7.136, mientras que los mismos 16 segundos en 720p cuestan $1.744. Con $10 se pueden generar aproximadamente 38 videos de 5 segundos en 540p, 18 de 5 segundos en 720p u 4 de 5 segundos en 4K.

La duración se cobra en segundos enteros. duration solo acepta enteros de 3 a 16, por defecto 5; la factura se calcula multiplicando los segundos enteros enviados por el precio unitario por segundo. 16 segundos cuestan 16 segundos, sin redondear a otra franja.

3 cosas a tener en cuenta antes de lanzar

1. Añade callback con consulta periódica como respaldo. Añade en el nivel superior del cuerpo de la solicitud "callback": {"url": "https://yourapp.com/hook", "when": "final"}; se notificará tanto el éxito como el fallo. La callback puede entregarse repetidamente, así que deduplica por taskId y mantén una consulta programada como compensación.
2. No vuelvas a hacer POST en caso de timeout. Cada envío crea una nueva tarea y se cobra por segundos. Guarda el taskId y consulta el mismo ID cuando haya inestabilidad de red, en lugar de enviar otra vez.
3. Escribe explícitamente duration y resolution. Los valores por defecto son 5 segundos y 720p; si no los indicas, se generará y cobrará según esos valores. En imagen a video no incluyas aspect_ratio ni reference_image_urls; esos dos campos pertenecen a otros modos y enviarlos devuelve directamente 400.
4. Los enlaces de los productos caducan. La url dentro de output incluye expireAt; en cuanto la obtengas, guárdala en tu propio almacenamiento.

Preguntas frecuentes

¿Se pueden enviar dos imágenes, inicial y final, en imagen a video? No; solo se acepta un image_url. Para combinar varias imágenes de referencia, usa el modelo de referencia a video de la misma serie.

¿Se puede elegir 16:9 o 9:16? No; el formato sigue al primer fotograma. Recorta primero el primer fotograma a la proporción deseada y luego súbelo.

¿Sale más barato desactivar el audio? No; audio no influye en el precio; con y sin audio cuesta lo mismo.

¿Cuánto cuesta exactamente un video? Los segundos enteros enviados multiplicados por el precio unitario de la resolución. 5 segundos en 720p cuestan $0.545; 10 segundos en 1080p, $1.375; 16 segundos en 4K, $7.136.

Genera tu primer video ahora

Copia el prompt del hidroavión de arriba, abre la página del modelo Vidu Q4 Preview de imagen a video, sube el primer fotograma, elige 720p / 5 segundos y obtén por $0.545 un video con sonido. Cuando confirmes el plano y el ritmo, cambia resolution a 2k o 4k y vuelve a generar la versión final. Consulta todos los parámetros en la documentación de integración.

Lecturas relacionadas: Precios de Vidu Q4 Preview · Vidu Q4 Preview vs Kling 3.0 · Recetario de prompts de imagen a video