> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vidu Q4 Preview Generación de video

> Genera videos desde un fotograma inicial o hasta 15 imágenes y 3 clips de audio de referencia. 3–16 segundos, hasta 4K, con audio por defecto.

<Info>
  Admite imagen a video y referencias a video, pero no texto sin imágenes ni fotogramas inicial y final combinados. Tras enviar la solicitud, obtén el ID en `data[0].task_id` y consulta el estado y resultado en [Consulta de tareas](/es/api-reference/tasks/status).
</Info>

## Modos de generación

`viduq4-preview` selecciona el modo automáticamente según las imágenes, los roles y el audio de referencia. No se necesita un parámetro de modo adicional.

| Entrada | Modo |
| - | - |
| Solo `first_frame_image` o una imagen con `role: "first_frame"` | Imagen a video |
| Una imagen sin rol y sin audio de referencia | Imagen a video |
| Rol `reference_image` o `reference` presente, sin fotograma inicial explícito | Referencias a video |
| 2–15 imágenes en total, sin fotograma inicial explícito | Referencias a video |
| Audio de referencia con 1–15 imágenes, sin fotograma inicial explícito | Referencias a video |

* **Imagen a video**: exactamente un fotograma inicial; prompt opcional; no admite audio de referencia.
* **Referencias a video**: 1–15 imágenes, hasta 3 clips de audio de referencia y **prompt obligatorio**. Con una sola imagen sin audio de referencia, indica `role: "reference_image"` explícitamente; de lo contrario, se usa imagen a video.
* Un fotograma inicial explícito (`first_frame_image` o `role: "first_frame"`) no puede combinarse con otras imágenes, roles de referencia o audio de referencia. Si se combina, devuelve HTTP 400.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "viduq4-preview",
      "prompt": "Una chica se gira sonriendo, su cabello largo ondea al viento y la cámara se acerca lentamente",
      "image_urls": ["https://example.com/first-frame.png"],
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/videos/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "viduq4-preview",
          "prompt": "Una chica se gira sonriendo, su cabello largo ondea al viento y la cámara se acerca lentamente",
          "image_urls": ["https://example.com/first-frame.png"],
          "duration": 5,
          "resolution": "1080p"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "viduq4-preview",
      prompt: "Una chica se gira sonriendo, su cabello largo ondea al viento y la cámara se acerca lentamente",
      image_urls: ["https://example.com/first-frame.png"],
      duration: 5,
      resolution: "1080p"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Cabeceras de solicitud

<ParamField header="Authorization" type="string" required>
  Autenticación Bearer con formato `Bearer <token>`, donde `<token>` es tu APIMart API Key.
</ParamField>

## Parámetros de solicitud

<ParamField body="model" type="string" required>
  Debe ser exactamente `viduq4-preview` en minúsculas.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt de generación de video, máximo 20.000 caracteres.

  * Imagen a video: opcional. Si se omite, el modelo genera el contenido a partir del fotograma inicial.
  * Referencias a video: obligatorio. Si falta, devuelve HTTP 400.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Array de imágenes. Admite URL públicas o Data URL Base64 como `data:image/png;base64,...`.

  * Imagen a video: solo una imagen, usada como fotograma inicial.
  * Referencias a video: 1–15 imágenes en total junto con `image_with_roles`.

  Se puede combinar con `image_with_roles`; las cantidades se suman. No combinar con `first_frame_image` ni un rol `first_frame` explícito. Para una imagen sin rol, la presencia de audio de referencia también determina el modo.
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  Array de imágenes con roles. Un elemento para imagen a video; 1–15 imágenes junto con `image_urls` para referencias a video.

  <Expandable title="Mostrar campos de imagen">
    <ParamField body="url" type="string" required>
      URL pública de la imagen o Data URL Base64.
    </ParamField>

    <ParamField body="role" type="string">
      Rol de imagen, sin distinguir mayúsculas:

      * `first_frame`: fotograma inicial para imagen a video.
      * `reference_image`: imagen de referencia; también admite `reference`.
      * Omitido o vacío: sin audio de referencia, el total determina el modo: una imagen para imagen a video, dos o más para referencias a video. Con audio de referencia, se usa referencias a video.

      Otros valores, como `last_frame`, devuelven HTTP 400 de forma síncrona.
    </ParamField>
  </Expandable>

  Puede combinarse con `image_urls` para aportar referencias, pero los roles de fotograma inicial no pueden mezclarse con material de referencia.
</ParamField>

<ParamField body="first_frame_image" type="string">
  Solo para imagen a video. URL pública o Data URL Base64 del fotograma inicial.

  Al usar este campo, no envíes otras imágenes ni audio de referencia. Para referencias a video, usa `image_urls` o `image_with_roles`.
</ParamField>

<ParamField body="audio_urls" type="string[]">
  Array de URL de audio de referencia, solo para referencias a video. Máximo 3 clips en total junto con `audio_url`.

  Formato MP3, cada clip de 3–12 segundos y hasta 50MB. Incluso con audio de referencia, se requiere al menos una imagen y un `prompt`.

  Un formato o duración de audio no válido provoca un fallo durante la ejecución con reembolso íntegro, no un HTTP 400 síncrono al enviar la solicitud.
</ParamField>

<ParamField body="audio_url" type="string">
  URL de un único audio de referencia. Mismos requisitos que `audio_urls`; máximo 3 clips entre ambos campos.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  Solo para referencias a video. Admite `1:1`, `9:16`, `16:9`, `3:4` y `4:3`. Por defecto: `16:9`.

  En imagen a video, el fotograma inicial determina la relación de aspecto y se ignora este parámetro.
</ParamField>

<ParamField body="size" type="string">
  Alias de compatibilidad de `aspect_ratio` con los mismos valores. Se recomienda usar solo uno de los dos campos. Sin efecto en imagen a video.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duración en segundos. Admite 3–16 segundos, no 1–2 segundos.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Resolución: `540p`, `720p`, `1080p`, `2K` o `4K`, sin distinguir mayúsculas.
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  Indica si se genera video con diálogos y efectos de sonido.

  * `true`: video con pista de audio (por defecto).
  * `false`: video sin sonido.

  El precio es igual con o sin sonido.
</ParamField>

<ParamField body="seed" type="integer">
  Semilla aleatoria. Omite el campo o envía `0` para un valor aleatorio.
</ParamField>

## Requisitos del material

* Imagen a video: exactamente un fotograma inicial obligatorio; no admite audio de referencia.
* Referencias a video: 1–15 imágenes obligatorias; hasta 3 clips de audio de referencia opcionales.
* PNG, JPEG, JPG y WEBP, hasta 50MB por imagen.
* Con Base64, el cuerpo completo debe ser inferior a 20MB. Se recomiendan URL públicas.
* Las URL de imagen deben ser públicas. Sustituye las URL de ejemplo por direcciones realmente accesibles.

<Warning>
  Ambos modos requieren imágenes y no admiten `last_frame_image`. Mezclar fotogramas iniciales con referencias o superar los límites de imágenes/audio devuelve HTTP 400 al enviar, sin crear tarea ni cobrar. Un formato o duración de audio no válido provoca un fallo durante la ejecución y un reembolso.
</Warning>

## Ejemplos de solicitud

### Solo fotograma inicial, sin prompt

```json theme={null}
{
  "model": "viduq4-preview",
  "image_urls": ["https://example.com/first-frame.png"]
}
```

Por defecto genera 5 segundos, 720p y audio.

### Fotograma inicial con rol explícito y salida 4K

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "La cámara se acerca lentamente mientras la persona sonríe de forma natural",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}
```

### Video sin sonido usando el campo de fotograma inicial

```json theme={null}
{
  "model": "viduq4-preview",
  "first_frame_image": "https://example.com/first-frame.png",
  "duration": 5,
  "resolution": "1080p",
  "audio": false
}
```

### Video con varias imágenes y audio de referencia

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "El chico de la imagen 1 habla con la chica de la imagen 2 usando el contenido del audio de referencia, en la cafetería de la imagen 3",
  "image_urls": [
    "https://example.com/boy.png",
    "https://example.com/girl.png",
    "https://example.com/cafe.png"
  ],
  "audio_urls": ["https://example.com/line.mp3"],
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "720p"
}
```

### Referencias a video con una sola imagen

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "La persona de la imagen de referencia entra en una cafetería y saluda al personal con la mano",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}
```

Este ejemplo no envía audio de referencia y selecciona referencias a video con el rol `reference_image`. Sustituye todas las URL de imagen y audio por direcciones accesibles.

## Respuesta de envío

<ResponseField name="code" type="integer">
  Código de respuesta; `200` indica éxito.
</ResponseField>

<ResponseField name="data" type="array">
  Resultado del envío de la tarea.

  <Expandable title="Mostrar campos de tarea">
    <ResponseField name="status" type="string">
      `submitted` indica que el envío tuvo éxito, no que el video esté terminado.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID de tarea para consultar estado y resultados.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consultar resultados

Consulta cada 5–10 segundos y detente cuando el estado sea `completed` o `failed`. Usa el endpoint unificado:

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Ejemplo de respuesta correcta (URL de video de ejemplo):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": ["https://example.com/generated-video.mp4"]
        }
      ]
    }
  }
}
```

| Estado | Acción |
| - | - |
| `pending` | En cola; seguir consultando |
| `processing` | Generando; seguir consultando |
| `completed` | Éxito; leer enlaces del array `data.result.videos[0].url` |
| `failed` | Fallo; leer causa en `data.error.message` y detener consultas; reembolso íntegro |

Los enlaces son válidos durante 24 horas. Descarga y guarda los archivos cuanto antes. Usa `status` para determinar la finalización, no porcentajes de progreso fijos.

## Facturación

Se cobra según duración y resolución: coste = duración (segundos) × tarifa por segundo de la resolución.

Consulta los [precios de modelos](https://apimart.ai/pricing). Ambos modos cuestan lo mismo, con o sin audio. Las imágenes y los audios de referencia no tienen coste adicional. Las tareas fallidas se reembolsan automáticamente en su totalidad.

## Errores de parámetros frecuentes

Los siguientes casos devuelven HTTP 400 de forma síncrona, sin crear tarea ni cobrar:

| Problema | Acción |
| - | - |
| Sin imágenes | Proporcionar un fotograma inicial o 1–15 imágenes de referencia según el modo |
| Fotograma inicial explícito mezclado con otras imágenes, roles o audio de referencia | Conservar solo un fotograma inicial para imagen a video; eliminar campos o roles de fotograma inicial explícito para referencias a video |
| `role` no admitido, como `last_frame` | Usar `first_frame`, `reference_image`, `reference` o dejar vacío |
| Más de 15 imágenes de referencia | Limitar `image_urls` y `image_with_roles` a 15 en total |
| Más de 3 clips de audio de referencia | Limitar `audio_urls` y `audio_url` a 3 en total |
| Falta `prompt` en referencias a video | Añadir un prompt de hasta 20.000 caracteres |
| Relación de aspecto no admitida, como `21:9` | Usar `1:1`, `9:16`, `16:9`, `3:4` o `4:3` |
| Se proporciona `last_frame_image` | Eliminar el campo; no se admiten fotogramas inicial y final combinados |
| `duration` menor que 3 o mayor que 16 | Usar un entero de 3 a 16 segundos |
| Resolución no admitida, como `480p` o `8K` | Usar `540p`, `720p`, `1080p`, `2K` o `4K` |

## Otros modelos Vidu

Para texto a video o fotogramas inicial y final, usa [Vidu Q3 Pro / Turbo](/es/api-reference/videos/vidu-q3-pro/generation). Este modelo ya admite varias imágenes de referencia; [Vidu Q3 Mix / Standard](/es/api-reference/videos/vidu-q3/generation) también ofrece referencias a video. Para clips de 1–2 segundos, elige `viduq3-pro`; este modelo requiere al menos 3 segundos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.