> ## 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.

# Pixverse v6 Generación de Video

>  - Modelo unificado de generación de video Pixverse v6
- Soporta texto a video, imagen a video, transición de primer/último frame, fusión multi-referencia y extensión de video
- Resoluciones 360p/540p/720p/1080p, duración de 1–15 segundos
- API de tareas asíncronas: tras el envío, consulte el resultado por ID de tarea 

<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": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
    }'
  ```

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

  url = "https://api.apimart.ai/v1/videos/generations"

  payload = {
      "model": "pixverse-v6",
      "prompt": "A cinematic shot of a corgi running through a sunflower field at golden hour",
      "size": "16:9",
      "resolution": "540p",
      "duration": 5
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/videos/generations";

  const payload = {
    model: "pixverse-v6",
    prompt: "A cinematic shot of a corgi running through a sunflower field at golden hour",
    size: "16:9",
    resolution: "540p",
    duration: 5
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "invalid duration 20, allowed range: 1-15 seconds"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Falló la autenticación, verifique su API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "insufficient quota: balance=0, required=0.25",
      "type": "quota_not_enough"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Demasiadas solicitudes, intente nuevamente más tarde",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Autenticación

<ParamField header="Authorization" type="string" required>
  Todos los endpoints requieren autenticación mediante Bearer Token.

  Obtener una API Key:

  Visite la [página de gestión de API Key](https://apimart.ai/keys) para obtener su API Key.

  Añada la siguiente cabecera a la solicitud:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Parámetros de la solicitud

<ParamField body="model" type="string" required>
  Nombre del modelo de generación de video. Fijo en `pixverse-v6`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Descripción del contenido del video, hasta 5000 caracteres. Obligatorio en todos los modos.
</ParamField>

<ParamField body="resolution" type="string" default="540p">
  Nivel de resolución del video. Afecta directamente la facturación.

  * `360p`: SD
  * `540p`: Estándar (predeterminado)
  * `720p`: HD
  * `1080p`: Full HD

  <Warning>
    Otros valores de resolución devolverán un error de parámetro.
  </Warning>
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duración del video en segundos, rango `1–15`.

  <Warning>
    El modo de transición de primer/último frame solo admite `5` u `8` segundos.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="16:9">
  Relación de aspecto del video. Solo efectivo en los modos texto a video y fusión multi-referencia.

  * `16:9`: Horizontal panorámico (predeterminado)
  * `4:3`: Horizontal 4:3
  * `1:1`: Cuadrado
  * `3:4`: Vertical 3:4
  * `9:16`: Vertical
  * `2:3`: Vertical 2:3
  * `3:2`: Horizontal 3:2
  * `21:9`: Cinematográfico panorámico
</ParamField>

<ParamField body="seed" type="integer" default="0">
  Semilla aleatoria, rango `0–2147483647`. El mismo prompt y semilla pueden reproducir resultados similares.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Prompt negativo para excluir contenido no deseado. Hasta 2048 caracteres.
</ParamField>

<ParamField body="audio" type="boolean" default="false">
  Si se genera una pista de audio.

  * `true`: Generar audio (aumenta el precio)
  * `false`: Sin audio (predeterminado)
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Si se añade marca de agua en la esquina inferior derecha del video.

  * `true`: Añadir marca de agua
  * `false`: Sin marca de agua (predeterminado)
</ParamField>

<ParamField body="motion_mode" type="string">
  Modo de movimiento.

  * `normal`: Modo estándar (`pixverse-v6` solo admite este valor)

  <Warning>
    `fast` solo se aplica a modelos antiguos y será rechazado por el upstream para `pixverse-v6`.
  </Warning>
</ParamField>

<ParamField body="generate_multi_clip_switch" type="boolean" default="false">
  Si se genera un video continuo de múltiples clips. Solo soportado en los modos texto a video e imagen a video.

  * `true`: Generar video continuo de múltiples clips
  * `false`: Clip único (predeterminado)
</ParamField>

<ParamField body="image_urls" type="array<url>">
  Array de URL de imágenes de entrada para imagen a video. Solo se utiliza la primera imagen.

  Las imágenes deben ser URL HTTP/HTTPS accesibles públicamente.
</ParamField>

<ParamField body="first_frame_image" type="url">
  URL del primer frame en el modo de transición. Debe enviarse junto con `last_frame_image`.
</ParamField>

<ParamField body="last_frame_image" type="url">
  URL del último frame en el modo de transición. Debe enviarse junto con `first_frame_image`.
</ParamField>

<ParamField body="img_references" type="array<url>">
  Array de URL de imágenes de referencia para el modo de fusión multi-referencia. Soporta 1–7 imágenes.

  Pasar este campo activa el modo de fusión multi-referencia.
</ParamField>

<ParamField body="extend_from_task_id" type="string">
  ID de la tarea de origen para la extensión de video. Pasar este campo activa el modo de extensión.

  La tarea de origen debe pertenecer al usuario actual, usar el modelo `pixverse-v6` y tener estado `completed`.
</ParamField>

## Modos de generación

El adaptador despacha automáticamente al modo de generación correspondiente según los campos de la solicitud. La coincidencia se realiza por orden de prioridad; gana el primero que coincide.

| Modo                           | Condición de activación                         | Descripción                                     |
| ------------------------------ | ----------------------------------------------- | ----------------------------------------------- |
| Texto a video                  | Sin campos de imagen ni de extensión            | Genera video a partir del `prompt`              |
| Imagen a video                 | `image_urls` con una imagen                     | Usa la primera imagen como entrada              |
| Transición primer/último frame | `first_frame_image` y `last_frame_image` juntos | Genera una transición fluida entre dos frames   |
| Fusión multi-referencia        | Array `img_references` proporcionado            | Fusiona 1–7 imágenes de referencia en un video  |
| Extensión de video             | `extend_from_task_id` proporcionado             | Continúa desde una tarea de Pixverse completada |

<Warning>
  Todas las entradas de imagen solo aceptan URL HTTP/HTTPS accesibles públicamente. base64 y Data URI no son compatibles. Si solo dispone de imágenes locales, súbalas primero a un object storage y pase la URL.
</Warning>

## Reglas de parámetros

| Restricción             | Descripción                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| Duración                | `1 ≤ duration ≤ 15` segundos; modo de transición solo `5` u `8` segundos                               |
| Resolución              | Solo se admiten `360p`, `540p`, `720p`, `1080p`                                                        |
| Relación de aspecto     | `size` solo es efectivo en los modos texto a video y fusión multi-referencia                           |
| Longitud del prompt     | `prompt` hasta 5000 caracteres, `negative_prompt` hasta 2048 caracteres                                |
| Imagen a video          | `image_urls` solo usa la primera imagen                                                                |
| Transición              | `first_frame_image` y `last_frame_image` deben enviarse en pareja                                      |
| Modo de movimiento      | `pixverse-v6` solo admite `normal`                                                                     |
| Fusión multi-referencia | `img_references` admite 1–7 imágenes                                                                   |
| Extensión de video      | `extend_from_task_id` debe apuntar a una tarea `pixverse-v6` con estado `completed` del usuario actual |

## Respuesta

<ResponseField name="code" type="integer">
  Código de estado de la respuesta. `200` en caso de éxito.
</ResponseField>

<ResponseField name="data" type="array">
  Array de tareas devuelto.

  <Expandable title="Elemento del array">
    <ResponseField name="status" type="string">
      Estado inicial de la tarea. `submitted` tras un envío exitoso.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador único de la tarea para consultar estado y resultado.
    </ResponseField>
  </Expandable>
</ResponseField>

## Consulta del resultado de la tarea

La generación de video es una tarea asíncrona. Tras el envío se devuelve un `task_id`. Use el endpoint [Obtener estado de la tarea](/es/api-reference/tasks/status) para consultar progreso y resultado.

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

Se recomienda hacer polling cada 5 segundos hasta que el estado sea `completed` o `failed`.

### Ejemplo de éxito

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "completed",
    "progress": 100,
    "cost": 0.2,
    "credits_cost": 2,
    "created": 1779958948,
    "completed": 1779958999,
    "estimated_time": 100,
    "actual_time": 51,
    "result": {
      "videos": [
        {
          "url": ["https://upload.apimart.ai/f/video/xxxx.mp4"],
          "expires_at": 1780045399
        }
      ]
    }
  }
}
```

La URL del video está en `data.result.videos[0].url[0]`. El campo `url` es a su vez un array. Los enlaces de video suelen caducar tras 24 horas; descárguelos o transfiéralos a tiempo.

### Ejemplo de fallo

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KSPX48B8V1M6C2ZN0D0T4BKB",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "created": 1779958948,
    "completed": 1779958960,
    "error": {
      "code": "task_failed",
      "message": "pixverse error 400063: moderation failed",
      "type": "task_failed"
    }
  }
}
```

En caso de fallo, `cost` suele ser `0`. La causa del error está en `data.error.message`.

## Casos de uso

### Caso 1: Texto a video

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A neon-lit alley in Tokyo at night, light rain, anamorphic lens flare",
  "size": "21:9",
  "resolution": "720p",
  "duration": 8,
  "seed": 42,
  "audio": true
}
```

### Caso 2: Imagen a video

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "Camera slowly zooms in, gentle wind moves the leaves",
  "image_urls": ["https://example.com/first-frame.jpg"],
  "resolution": "540p",
  "duration": 5
}
```

### Caso 3: Transición primer/último frame

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "transform smoothly from a puppy to a cat",
  "first_frame_image": "https://example.com/puppy.jpg",
  "last_frame_image": "https://example.com/cat.jpg",
  "resolution": "540p",
  "duration": 5,
  "motion_mode": "normal"
}
```

### Caso 4: Fusión multi-referencia

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "A girl wearing the outfit from image 2, holding the cat from image 3",
  "img_references": [
    "https://example.com/character.jpg",
    "https://example.com/outfit.jpg",
    "https://example.com/cat.jpg"
  ],
  "size": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

### Caso 5: Extensión de video

```json theme={null}
{
  "model": "pixverse-v6",
  "prompt": "the character now walks into a forest",
  "extend_from_task_id": "task_01JWXXXXXXXXXXXX",
  "resolution": "540p",
  "duration": 5
}
```