Vidu

Vidu Q4 Preview

vidu-q4-preview/image-to-video

Primera versión preliminar pública de la serie Vidu Q4, centrada en la actuación de personajes y el audio nativo, compatible con hasta 15 imágenes y 3 referencias de audio como guía, con salida de vídeo de hasta 4K

vidu-q4-preview/image-to-video vidu-q4-preview/reference-to-video

Probar vidu-q4-preview/image-to-video

Entrada

Creaciones

Ver todas las creaciones

Salida

video

Rellena los parámetros y genera: los resultados aparecerán aquí.

Precios

vidu-q4-preview/image-to-video per second

Especificaciones	Precio unitario
540P	$0.0515
720P	$0.109
1080P	$0.1375
2K	$0.2175
4K	$0.446

Descripción general

vidu-q4-preview/image-to-video es la versión preliminar de lanzamiento de la serie Vidu Q4, que genera videos con audio nativo a partir de una imagen de primer fotograma. El modelo admite duraciones de 3 a 16 segundos y salidas de 540p a 4K, manteniendo la relación de aspecto de la imagen del primer fotograma; es posible describir el movimiento, la cámara y el sonido mediante prompts. Está orientado a desarrolladores que necesitan actuación de personajes, lenguaje cinematográfico y efectos de sonido sincronizados, para cortometrajes narrativos, previsualización de anuncios o comparación de varias propuestas.

Aspectos destacados

Impulsado por imagen de primer fotograma con audio nativo sincronizado: la imagen del primer fotograma fija la composición y la relación de aspecto; al generar se producen por defecto diálogos y efectos de sonido al mismo tiempo, y también es posible desactivar la salida de audio para obtener un video silencioso.
Una sola generación cubre de 3 a 16 segundos y salida 4K: los parámetros de duración y resolución se ajustan dentro de la misma ruta, de 540p a 4K según se necesite, lo que reduce el empalme por segmentos en planos largos.
La versión preliminar Q4 se centra en la actuación expresiva: la posición oficial apunta a una mejora integral en la actuación de personajes, el lenguaje cinematográfico y los efectos visuales, adecuada para planos que exigen continuidad de acción y emoción.

Descripción de capacidades

De primer fotograma a video con sonido: basta con introducir una imagen de primer fotograma para generar un video, cuya relación de aspecto sigue a la de la imagen; el audio nativo está activado por defecto, de modo que se obtienen diálogos y efectos de sonido a la vez, y al desactivarlo se obtiene un video sin sonido.

Duración y resolución ajustables: la duración de una generación se puede establecer en segundos enteros entre 3 y 16, y la resolución admite cinco niveles: 540p, 720p, 1080p, 2K y 4K, para planificar el uso según las especificaciones de salida.

El prompt controla movimiento y sonido: el prompt admite hasta 20000 caracteres y puede describir el movimiento, el movimiento de cámara y el sonido, para guiar la dinámica de la imagen y el contenido de audio.

Límites de entrada de imagen claros: la imagen del primer fotograma admite JPG, JPEG, PNG y WEBP, con un máximo de 50MB, y la relación de aspecto debe estar entre 1:4 y 4:1, lo que facilita la validación del material antes de la integración.

Casos de uso

Cortometrajes narrativos para creadores independientes y pequeños estudios: usar una imagen clave como primer fotograma junto con un prompt para generar fragmentos de cortometraje con diálogos y efectos de sonido, que pasan directamente al flujo de edición.
Previsualización de planos para anuncios y videos de marca: generar videos en varias resoluciones a partir de imágenes de producto o fotogramas de storyboard, para que el cliente confirme el encuadre, el ritmo y la dirección sonora antes de pasar a la producción formal.
Comparación de varias propuestas para planos dramáticos: ajustar el prompt y los parámetros de duración sobre el mismo primer fotograma y generar por lotes distintas propuestas de actuación o de movimiento de cámara para la selección interna.

Limitaciones y recomendaciones de selección

Este modelo es una versión preliminar Preview, y la capacidad y las funciones oficiales seguirán cambiando con las iteraciones, por lo que no se recomienda que sea la única dependencia de un flujo de producción estable a largo plazo. La duración máxima de una generación es de 16 segundos, por lo que los planos más largos requieren generarse por segmentos y empalmarse; la entrada parte de una única imagen de primer fotograma y no permite combinar varias referencias en una misma ruta. Si se necesita mantener la coherencia de personajes y voces con imágenes o audio de referencia, debe usarse la ruta reference-to-video de la misma serie. Cuando se requiere de forma imprescindible una narrativa coherente de varios planos o videos muy largos, es necesario evaluar otros modelos que admitan mayor duración o un control de coherencia más potente.

Preguntas frecuentes

Ver todas las preguntas →

¿Se puede configurar la relación de aspecto al generar vídeo a partir de una imagen?

No. La relación de aspecto del vídeo final sigue completamente a la imagen del primer fotograma: si subes una imagen horizontal, se genera en horizontal; si subes una imagen vertical, se genera en vertical. Por lo tanto, si quieres un formato vertical 9:16, prepara un primer fotograma en versión vertical. La relación de aspecto del primer fotograma debe estar entre 1:4 y 4:1; las imágenes demasiado alargadas se rechazarán al enviarlas.
¿Para qué sirve el interruptor de audio?

El audio nativo está activado por defecto y genera diálogos, sonido ambiente y efectos de sonido sincronizados con la imagen; al desactivarlo, se produce un video sin sonido, solo con la imagen, ideal para fondos en bucle, añadir tu propia música en la posproducción o agregar subtítulos. El interruptor no afecta el precio.
¿Cuál es la relación entre la duración y el precio?

Se factura multiplicando la duración en segundos enteros enviada por el precio unitario por segundo de la resolución seleccionada; el interruptor de audio y la cantidad de imágenes no participan en el cálculo. A mayor resolución, mayor es el precio unitario por segundo: la categoría 4K es aproximadamente 8.7 veces la categoría 540p. El importe exacto se rige por la página de precios.
¿Para qué escenarios es adecuada cada una de las cinco resoluciones?

540p se usa para probar prompts y encuadres, y también basta para fondos en bucle de tamaño pequeño; 720p cubre la mayoría de redes sociales y web; 1080p se usa para publicaciones habituales; 2K es adecuada para pantallas grandes y presentaciones en televisión; 4K se usa para exposiciones, imágenes de nivel cinematográfico o planos que necesitan recorte en posproducción para una segunda composición. Antes de la versión final, prueba primero con la resolución baja; una vez definida, exporta con la alta.

Crear una tarea de generación

POST https://api.hiapi.ai/v1/tasks

Encabezados

AuthorizationstringObligatorio

Clave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API

Content-TypestringOpcional

El cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.

Idempotency-KeystringOpcional

Clave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.

Clave de idempotencia

Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.

Cuerpo

modelstringObligatorio

Valor fijo actual: vidu-q4-preview/image-to-video

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para vidu-q4-preview/image-to-video y la ruta default; consulta la tabla de parámetros a continuación.

audiobooleanOpcionalPredeterminado: true

Controla si se genera audio nativo sincronizado con el vídeo (diálogo y efectos de sonido); valor booleano, si se establece en false se genera un vídeo sin sonido, por defecto true.

promptstringOpcionalmaxLength 20000

Opcional. Indicación que describe el movimiento de la imagen, el movimiento de cámara y el sonido, con una longitud máxima de 20000 caracteres.

durationintegerOpcionalPredeterminado: 5min 3max 16

Duración del vídeo en segundos, número entero entre 3 y 16, por defecto 5.

image_urlstringObligatoriominLength 1

Dirección de la imagen que se usará como primer fotograma del vídeo; el vídeo de salida mantiene la relación de aspecto de dicha imagen; admite JPG, JPEG, PNG y WEBP, con un tamaño no superior a 50 MB y una relación de aspecto entre 1:4 y 4:1.

resolutionstringOpcionalPredeterminado: "720p"

Resolución del vídeo de salida, por defecto 720p.

Opciones:540p720p1080p2k4k

callbackobjectOpcional

Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.

Callbacks (Webhook)

Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.

urlstringObligatorio

Obligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.

whenstringOpcionalPredeterminado: "final"

Actualmente solo se admite final: notifica tanto en success como en fail.

Opciones:final

storagestringOpcionalPredeterminado: "temp"

Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.

Opciones:temppersistent

Ejemplos de solicitud

# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q4-preview/image-to-video",
  "input": {
    "audio": true,
    "duration": 5,
    "image_url": "…",
    "resolution": "720p"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "vidu-q4-preview/image-to-video",
    input: {
      "audio": true,
      "duration": 5,
      "image_url": "…",
      "resolution": "720p"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "vidu-q4-preview/image-to-video",
        "input": {
          "audio": True,
          "duration": 5,
          "image_url": "…",
          "resolution": "720p"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obtener el detalle de la tarea

GET https://api.hiapi.ai/v1/tasks/:id

Campos de respuesta

taskIdstringObligatorio

ID de tarea, siempre con prefijo tk-hiapi-.

modelstringObligatorio

Nombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.

routestringOpcional

Solo aparece si se usó el parámetro route explícito; repite el valor enviado.

statusstringObligatorio

Estado de la tarea.

Valores de estado

queued En cola, sin iniciar. handling Procesando. archiving Proceso terminado, preparando artefactos. success Terminal: completado, artefactos disponibles (se devuelve output). fail Terminal: error (se devuelve error). Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.

creatednumberObligatorio

Hora de creación de la tarea (segundos Unix).

completednumberObligatorio

Segundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.

outputarrayOpcional

Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).

Array [ object ]

Elementos del array

urlstringObligatorio

URL del artefacto, descargable directamente.

typestringObligatorio

Valores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.

expireAtnumberObligatorio

Segundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.

errorobjectOpcional

Solo con status == fail.

codestringObligatorio

Código de error de negocio.

messagestringObligatorio

Descripción del error.

Ejemplos de respuesta

Éxito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

En proceso (no terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fallido

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}