Vidu

Vidu Q3

vidu-q3-ad/reference-to-video

Modelo de video a partir de una imagen de referencia para anuncios y videos cortos de redes sociales, que permite restringir la apariencia del sujeto y la composición, ideal para producir contenido rápidamente y para iterar múltiples versiones

vidu-q3-ad/reference-to-video vidu-q3-mix/reference-to-video

Probar vidu-q3-ad/reference-to-video

Entrada

Salida

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

Precios

vidu-q3-ad/reference-to-video per second

Especificaciones	Precio unitario
1280*720	$0.149
1280*960	$0.149
1280*1280	$0.149
960*1280	$0.149
720*1280	$0.149
1920*1080	$0.180
1920*1440	$0.180
1808*1808	$0.180
1440*1920	$0.180
1080*1920	$0.180

Descripción general

La línea de generación de video por referencia de Vidu Q3 está orientada a la producción de videos cortos que requieren un control preciso de la imagen y una estabilidad del sujeto. Los desarrolladores envían de 1 a 7 imágenes de referencia junto con un prompt y pueden generar videos de 3 a 15 segundos; las imágenes de referencia se citan en el prompt como Image1, Image2 según el orden del array para restringir personajes, objetos o el estilo visual. La salida admite dos niveles de resolución, 720P y 1080P, con diez formatos de relación de aspecto en total, permite activar la generación de audio sincronizado con la imagen y también permite fijar una semilla para reproducir resultados. Es adecuado para equipos que necesitan probar rápidamente varias versiones de material publicitario, demostraciones de producto o fragmentos cortos de personajes.

Aspectos destacados

Restricción del sujeto y el estilo mediante múltiples referencias: se pueden enviar hasta 7 imágenes de referencia a la vez, posicionadas en el prompt como Image1, Image2 según su orden, para restringir respectivamente personajes, objetos o el estilo visual.
Generación conjunta de imagen y audio: al activar audio, el video genera un sonido sincronizado con la imagen; desactivado por defecto, se obtiene un video sin sonido, lo que facilita el doblaje posterior.
Combinación flexible de duración y formato: la duración es seleccionable entre 3 y 15 segundos; los niveles 720P y 1080P incluyen cada uno cinco relaciones de aspecto: 16:9, 4:3, 1:1, 3:4 y 9:16.
Semilla fija para facilitar la reproducción e iteración: admite especificar una semilla aleatoria de 0 a 2147483647; con la misma configuración se pueden reproducir los resultados, lo que facilita comparar el efecto de los cambios en el prompt.

Descripción de capacidades

Generación impulsada por múltiples imágenes de referencia: acepta de 1 a 7 imágenes JPG, PNG o WEBP de acceso público, con un máximo de 50 MB por imagen y una relación de aspecto de 1:4 a 4:1, para fijar personajes, la apariencia de objetos o el estilo general.

Control de escena y movimiento de cámara mediante el prompt: un prompt de hasta 5000 caracteres puede describir la escena, la acción, el movimiento de cámara y el sonido, y mediante los índices Image1, Image2 apuntar a imágenes de referencia concretas para asignar funciones por imagen.

Generación de audio opcional: el interruptor audio controla si se genera un audio sincronizado con la imagen; al desactivarse, se obtiene un video silencioso, lo que facilita integrarlo en flujos propios de doblaje o música.

Selección de resolución y formato: el parámetro size ofrece dos niveles, 720P y 1080P, que cubren formatos horizontal, vertical, cuadrado y dos proporciones verticales, adaptándose a las especificaciones de las distintas ubicaciones de publicación.

Control de duración y marca de agua: duration toma valores entre 3 y 15 segundos; watermark permite elegir si se añade la marca de generación con IA en la esquina inferior derecha; la facturación se calcula según los segundos de salida.

Casos de uso

Equipos de marca y publicidad: varias imágenes de producto + texto de argumentos de venta: producen clips publicitarios cortos con el formato especificado para publicaciones en redes sociales y materiales de las páginas de detalle de comercio electrónico.
Creadores de contenido de personajes: hojas de diseño de personaje + descripción de la trama: generan breves tomas narrativas con una apariencia de personaje consistente, para fragmentos de series cortas, validación de conceptos de estilo anime y previsualización de guiones gráficos.
Equipos creativos: imágenes de referencia de estilo + descripción de la propuesta: producen rápidamente varias versiones de prueba para comparaciones A/B, controlando las variables con una semilla fija, y tras seleccionar pasan a la producción formal.
Producción de demostraciones de producto: fotos de producto + descripción de escenarios de uso: convierten imágenes estáticas de producto en videos de demostración con movimientos de cámara, para sitios web, presentaciones y materiales de formación.

Limitaciones y recomendaciones de selección

La duración de salida por generación está limitada a entre 3 y 15 segundos, por lo que no cubre directamente videos largos ni narraciones continuas de múltiples planos; el resultado final aún requiere edición y montaje manual. Las imágenes de referencia deben ser de acceso público y no superar los 50 MB cada una; las imágenes almacenadas de forma privada deben convertirse primero en direcciones accesibles. El audio es una opción de generación; cuando se requieren diálogos o doblajes alineados con precisión con la imagen, resulta más controlable generar la salida sin sonido y producirlos por separado. Actualmente solo admite generación impulsada por imágenes de referencia y no acepta entrada de solo texto; para ideas sin material de referencia, elija la línea de texto a video.

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-q3-ad/reference-to-video

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

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

seedintegerOpcionalmin 0max 2147483647

Semilla aleatoria para reproducir el resultado de la generación; valores de 0 a 2147483647.

sizestringOpcionalPredeterminado: "1280*720"

Resolución del video de salida en formato ANCHO*ALTO, disponible en dos niveles, 720P y 1080P, y cada nivel admite 16:9, 4:3, 1:1, 3:4 y 9:16; el precio por segundo varía según el nivel. Valor predeterminado 1280*720.

Opciones:1280*7201280*9601280*1280960*1280720*12801920*10801920*14401808*1808

Mostrar todo (2)

1440*19201080*1920

audiobooleanOpcionalPredeterminado: false

Si se genera audio sincronizado con la imagen; al desactivarse, se produce un video sin sonido. Valor predeterminado false.

promptstringObligatoriominLength 1maxLength 5000

Describe la escena, el movimiento, la cámara y el sonido; las imágenes de referencia se citan en el prompt con numeración Image1, Image2, etc., según el orden del arreglo.

durationintegerObligatorioPredeterminado: 5min 3max 15

Duración del video de salida en segundos; rango de 3 a 15. Valor predeterminado 5.

watermarkbooleanOpcionalPredeterminado: false

Si se añade una marca de agua de generación por IA en la esquina inferior derecha; desactivado de forma predeterminada. Valor predeterminado false.

reference_image_urlsarrayObligatoriominItems 1maxItems 7

Arreglo de imágenes de referencia; proporciona de 1 a 7 imágenes (personas, objetos o estilos); cada una debe ser JPG/PNG/WEBP, no superar los 50MB, tener una relación de aspecto entre 1:4 y 4:1 y ser de acceso público; se citan en el prompt con numeración Image1, Image2, etc.

Array [ string ]

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-q3-ad/reference-to-video",
  "input": {
    "size": "1280*720",
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "watermark": false,
    "reference_image_urls": "…"
  }
}'

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-q3-ad/reference-to-video",
    input: {
      "size": "1280*720",
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "watermark": false,
      "reference_image_urls": "…"
    }
  }),
});
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-q3-ad/reference-to-video",
        "input": {
          "size": "1280*720",
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "watermark": False,
          "reference_image_urls": "…"
        }
    },
)
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"
    }
  }
}