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

# Generación de vídeo apimart-zoe

> Genera y edita vídeos con texto, fotogramas y referencias de imagen/vídeo/audio: 480p–4k, imagen final, MOV y generación de borrador a vídeo final.

> [!NOTE]
>
> Esta API es asíncrona. Tras enviar la solicitud, lee `data[0].task_id` y consulta el [estado de la tarea](https://docs.apimart.ai/es/api-reference/tasks/status.md). La generación suele tardar de 1 a 3 minutos; consulta cada 5–10 segundos. El tiempo real depende de la tarea.

```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": "apimart-zoe",
    "prompt": "Un gatito naranja en el alféizar mira a la cámara, con luz solar lateral y un lento acercamiento de cámara",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  }'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "apimart-zoe",
        "prompt": "Un gatito naranja en el alféizar mira a la cámara, con luz solar lateral y un lento acercamiento de cámara",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 8,
        "audio": True,
        "nsfw_check": True,
        "return_last_frame": True
    }
)
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": "apimart-zoe",
    "prompt": "Un gatito naranja en el alféizar mira a la cámara, con luz solar lateral y un lento acercamiento de cámara",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "audio": true,
    "nsfw_check": true,
    "return_last_frame": true
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KZOEEXAMPLE"
    }
  ]
}
```

## Elegir un modo

| Modo | Parámetros |
| - | - |
| Texto a vídeo | Envía `prompt` sin medios. |
| Fotogramas a vídeo | Usa los roles `first_frame` y, opcionalmente, `last_frame` en `image_with_roles`, o `first_frame_image` / `last_frame_image`. |
| Referencias a vídeo | Imágenes o vídeos de referencia, opcionalmente acompañados de audio. No se admite solo audio. |
| Borrador | `draft: true` produce una salida `480p`. |
| Vídeo final | Usa el `draft_task_id` de un borrador completado con éxito para una salida `1080p`. |
| Edición de vídeo | Usa `omni_reference_task_type: "edit"` y al menos un vídeo fuente. La duración y proporción siguen la fuente. |

## Cabeceras

**Authorization** `string` *required*

Autenticación Bearer: `Bearer <token>`, donde `<token>` es tu clave API de APIMart. Envía el cuerpo con `Content-Type: application/json`.

## Parámetros de solicitud

**model** `string` *required*

Siempre `apimart-zoe`.

**prompt** `string`

Hasta 204.800 caracteres. Obligatorio para texto a vídeo; opcional si solo se envían medios. Prohibido con `draft_task_id`: se hereda el prompt del borrador.

**resolution** `string`

`480p`, `720p`, `1080p`, `2k`, `4k`, sin distinguir mayúsculas. Generación normal: `720p` por defecto. Con `draft: true`, solo `480p`, también si se omite. Con `draft_task_id`, solo `1080p`, también si se omite.

**aspect\_ratio** `string`

`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. Por defecto `adaptive`, determinado por el modelo o los medios. Omítelo en el vídeo final, que hereda la proporción del borrador.

En edición (`edit`), omite el campo o usa `adaptive` para seguir la fuente.

**size** `string`

Nombre alternativo de `aspect_ratio`, con los mismos valores. Es preferible enviar solo uno de los dos campos. Omítelo en el vídeo final.

**duration** `integer`

Generación normal: Segundos enteros de `4` a `30`, por defecto `5`. Se factura la duración solicitada o predeterminada sin ajuste a la duración del resultado. Con `-1`, decide el modelo: reserva de 30 segundos y ajuste según la duración real redondeada al segundo más cercano (0.5 hacia arriba). Omítelo en el vídeo final, que hereda la duración del borrador.

En edición (`edit`), omite el campo o usa `-1`. Omitirlo equivale a `-1`; la duración sigue el vídeo fuente.

**seconds** `integer`

Alias de `duration`, con las mismas reglas. Usa solo uno de los campos. Omítelo en el vídeo final.

**audio** `boolean`

Booleano para generar audio junto con el vídeo. Alias: `generate_audio`. Si se omite, decide el modelo. Prohibido en el vídeo final. Controla el audio de salida, no las referencias de entrada `audio_urls`.

Si envías `audio` y `generate_audio`, sus valores deben coincidir; de lo contrario se devuelve HTTP 400. Si se omiten, el modelo decide y normalmente incluye sonido.

**generate\_audio** `boolean`

Alias de `audio`, con las mismas reglas. Usa solo uno de los campos y omítelo en el vídeo final.

Si envías `audio` y `generate_audio`, sus valores deben coincidir; de lo contrario se devuelve HTTP 400. Si se omiten, el modelo decide y normalmente incluye sonido.

**seed** `integer`

Semilla aleatoria entera. Prohibida en el vídeo final.

**nsfw\_check** `boolean`

La moderación está desactivada por defecto; actívala con `true`.

Booleano opcional. `true` activa la moderación de `prompt`, `image_urls`, `image_with_roles`, fotogramas inicial/final e imágenes `asset://`. No se moderan los vídeos ni audios de referencia.

La solicitud final no incluye prompt ni medios. En el flujo borrador → vídeo final, se modera al generar el borrador.

Una detección devuelve HTTP 400 (`nsfw_content_detected`), con las categorías en `error.message`. Muéstralo como rechazo de moderación, no como error genérico de parámetros. Si el servicio de moderación falla o no está disponible, la generación continúa; activar este parámetro no garantiza que todas las solicitudes completen la moderación.

**omni\_reference\_task\_type** `string`

Admite `auto` (predeterminado, equivale a omitir; decide el modelo), `reference` y `edit`. `reference` / `edit` requieren medios de referencia; con texto solo o fotogramas inicial/final devuelven HTTP 400. `edit` requiere al menos una entrada en `video_urls` y no admite `draft: true`. `extend` no está disponible y devuelve HTTP 400. Omitir al generar el vídeo final.

**return\_last\_frame** `boolean`

Con `true`, devuelve además el último fotograma en PNG en `data.result.last_frame_url`. Desactivado por defecto. Omitir al generar el vídeo final.

**output\_format** `string`

`mp4` (predeterminado) o `mov` (contenedor QuickTime); otros valores devuelven HTTP 400. Alias: `response_format`. Si envías ambos, prevalece `output_format`. Omitir al generar el vídeo final.

**response\_format** `string`

Alias de `output_format`, admite `mp4` / `mov`. Si envías ambos, prevalece `output_format`. Omitir al generar el vídeo final.

**enhance\_prompt** `boolean`

Con `true`, optimiza automáticamente el prompt antes de generar. Por defecto se usa el prompt original sin optimización. Omitir al generar el vídeo final.

**image\_with\_roles** `object[]`

Cada elemento contiene `url` y `role`. Roles: `first_frame` (inicial), `last_frame` (final), `reference_image` (referencia). Como máximo un fotograma inicial y uno final; el final requiere el inicial. No se pueden combinar con medios de referencia.

No envíes `image_urls` y `image_with_roles` juntos: devuelve HTTP 400 (`invalid_request_error`) al enviar, sin cargo. Los alias `image`, `images` e `image_url` cuentan como `image_urls` y no evitan esta restricción.

**image\_urls** `string[]`

Hasta 30 imágenes de referencia. Consulta abajo los formatos, dimensiones y tamaños de archivo.

No envíes `image_urls` y `image_with_roles` juntos: devuelve HTTP 400 (`invalid_request_error`) al enviar, sin cargo. Los alias `image`, `images` e `image_url` cuentan como `image_urls` y no evitan esta restricción.

**first\_frame\_image** `string`

Dirección del fotograma inicial, equivalente al rol `first_frame` de `image_with_roles`.

**last\_frame\_image** `string`

Dirección del fotograma final, equivalente al rol `last_frame`. También se requiere un fotograma inicial.

**video\_urls** `string[]`

Hasta 10 vídeos de referencia. URL `http(s)` pública o `asset://<ID del medio>`, sin `data:` Base64. Las dimensiones, la duración exacta y los fotogramas por segundo se validan al enviar según las reglas siguientes.

Para facturar, se suman las duraciones y después se redondea la suma hacia abajo a segundos enteros, sin ajustes posteriores. Este redondeo no se usa para validar la duración de cada vídeo. Acceso o medición de duración fallidos: HTTP 400 (`input_video_probe_failed`), sin cargo.

`auto` / `reference`: 2–15 segundos, rango admitido `1.8 ≤ t ≤ 15.2`. Fuentes para `edit`: 4–30 segundos, rango admitido `3.8 ≤ t < 30.2`. Valida la duración exacta sin redondear.

**audio\_urls** `string[]`

Hasta 10; WAV / MP3; cada uno de 2–15 segundos y `≤ 15 MB`, hasta 30 segundos en total. Tolerancia ±0.2 segundos: `1.8 ≤ t ≤ 15.2` por clip y `≤ 30.2` en total. Requiere imagen o vídeo de referencia.

URL pública `http(s)` o `asset://<ID del recurso>`; no admite `data:` Base64. La duración se comprueba al enviar; una duración no válida devuelve HTTP 400 síncrono sin cargo.

**draft** `boolean`

`true` genera un borrador `480p`. Los demás parámetros siguen las reglas normales. No envíes este campo al generar el vídeo final.

La edición de vídeo (`edit`) no admite borradores.

**draft\_task\_id** `string`

`task_id` de un borrador completado con éxito para generar un vídeo final `1080p`. Úsalo en las 24 horas posteriores a la creación del borrador. Se heredan prompt, medios, duración y proporción; no vuelvas a enviarlos. El vídeo final también prohíbe `seed`, `audio` y su alias `generate_audio`.

## Direcciones y límites de los medios

Imágenes, vídeos y audios admiten URL públicas `http(s)` o recursos APIMart `asset://<ID del recurso>`. Ninguno admite `data:` Base64; sube primero el material. El registro es automático, sin llamada API adicional. Si falla, la tarea falla y se reembolsa el cargo.

| Medio | Requisitos |
| - | - |
| Imágenes de referencia | Hasta 30; JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF; proporción 0.4–2.5; anchura y altura de 300–6000 píxeles cada una; cada imagen `< 30 MB`. |
| Vídeos de referencia | Hasta 10; MP4 / MOV (H.264 / H.265; pista de audio: AAC / MP3); cada uno `≤ 200 MB`. Consulta abajo las reglas de dimensiones, duración y fotogramas por segundo. |
| Audio de referencia | Hasta 10; WAV / MP3; cada uno de 2–15 segundos y `≤ 15 MB`, hasta 30 segundos en total. Tolerancia ±0.2 segundos: `1.8 ≤ t ≤ 15.2` por clip y `≤ 30.2` en total. Requiere imagen o vídeo de referencia. |

### Validación de los vídeos de referencia

| Propiedad | Requisito |
| - | - |
| Anchura y altura | Anchura y altura de 300–6000 píxeles cada una. |
| Área en píxeles (anchura × altura) | 409.600–8.295.044 píxeles. |
| Proporción (anchura / altura) | 0.4–2.5. |
| Duración por vídeo | `auto` / `reference`: 2–15 segundos, rango admitido `1.8 ≤ t ≤ 15.2`. Fuentes para `edit`: 4–30 segundos, rango admitido `3.8 ≤ t < 30.2`. Valida la duración exacta sin redondear. |
| Fotogramas por segundo | Redondea al entero más cercano (0.5 hacia arriba), después comprueba 24–60fps. Se admiten 23.976 y 59.94. |

Dimensiones, área en píxeles, proporción, duración exacta y fps del vídeo, junto con la duración del audio de referencia, se validan al enviar. Los errores devuelven HTTP 400 síncrono sin cargo. Los errores de vídeo usan `invalid_request_error` e incluyen las medidas. Comprueba el área, no un lado corto mínimo de 480 y largo máximo de 4096.

Considerando solo las dimensiones, 420×1000 (420.000 píxeles) cumple. 720×480 (345.600 píxeles), 848×480 (407.040 píxeles) y 4096×2160 (8.847.360 píxeles) no cumplen los límites de área. También deben cumplirse la duración, los fps y los demás requisitos.

Dimensiones de imagen, tamaño de archivo y codificación se validan durante la generación. Si no cumplen, la tarea falla con reembolso automático. Comprueba estas propiedades antes de llamar a la API cuando sea posible.

### Reglas de combinación de medios

* No envíes `image_urls` y `image_with_roles` juntos: devuelve HTTP 400 (`invalid_request_error`) al enviar, sin cargo. Los alias `image`, `images` e `image_url` cuentan como `image_urls` y no evitan esta restricción.
* Los fotogramas inicial/final no pueden aparecer en la misma solicitud que imágenes, vídeos o audios de referencia.
* Como máximo un fotograma inicial y uno final. El final requiere el inicial.
* Hasta 30 imágenes, 10 vídeos y 10 audios de referencia, con un máximo combinado de 50 medios.
* Incumplir estas combinaciones o cantidades devuelve HTTP 400 de forma síncrona, sin cargo.
* `omni_reference_task_type: "edit"` requiere al menos un vídeo fuente (`3.8 ≤ t < 30.2` segundos). `duration` / `seconds`: omitir o `-1`; `aspect_ratio` / `size`: omitir o `adaptive`. No combinar con `draft: true`. Auto/reference mantienen el límite de 2–15 segundos y su tolerancia.

> [!WARNING]
>
> Estos campos devuelven HTTP 400 si están presentes, incluso con `""`, `[]`, `false` o `null`; elimínalos por completo: `negative_prompt`, `camera_fixed`, `camerafixed`, `extend_from_task_id`, `mask_url`, `video_list`, `element_list`, `multi_shot`, `tools`. Omite `n` o usa `1`.

## Ejemplos de solicitud

Las URL siguientes son ejemplos. Sustitúyelas por direcciones de medios accesibles.

### Fotogramas inicial y final

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Transición natural del primer al último fotograma, manteniendo una iluminación coherente",
  "image_with_roles": [
    {
      "url": "https://example.com/start.jpg",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/end.jpg",
      "role": "last_frame"
    }
  ],
  "duration": 6
}
```

También puedes usar `first_frame_image` y `last_frame_image`. No añadas imágenes, vídeos ni audio de referencia a la misma solicitud.

### Referencias de imagen, vídeo y audio

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "El personaje de la imagen de referencia se mueve con naturalidad en la escena del vídeo, con música al ritmo de las imágenes",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://example.com/bgm.mp3"
  ],
  "duration": -1
}
```

Las imágenes de `image_urls` se tratan como referencias. Con `duration: -1`, el modelo decide la duración de salida.

### Edición de vídeo

`omni_reference_task_type: "edit"` requiere al menos un vídeo fuente (`3.8 ≤ t < 30.2` segundos). `duration` / `seconds`: omitir o `-1`; `aspect_ratio` / `size`: omitir o `adaptive`. No combinar con `draft: true`. Auto/reference mantienen el límite de 2–15 segundos y su tolerancia.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Transforma la escena en una película clásica en blanco y negro, conservando el movimiento de cámara y la composición",
  "video_urls": [
    "https://example.com/source_20s.mp4"
  ],
  "omni_reference_task_type": "edit"
}
```

La edición usa la tarifa con vídeo de referencia. Se reservan 30 segundos de salida y se ajusta el cargo según la duración real redondeada a segundos enteros, incluyendo el vídeo de referencia con la fórmula siguiente.

### Último fotograma, salida MOV y optimización del prompt

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Un gatito naranja en el alféizar mira a la cámara, con luz solar lateral y un lento acercamiento de cámara",
  "duration": 5,
  "return_last_frame": true,
  "output_format": "mov",
  "enhance_prompt": true
}
```

## Borrador → vídeo final

1. Envía el borrador con `draft: true`. Si omites `resolution`, se usa `480p`; si lo incluyes, solo se admite `480p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "prompt": "Un gatito naranja en el alféizar mira a la cámara, con luz solar lateral y un lento acercamiento de cámara",
  "draft": true
}
```

2. Espera a que el borrador se complete y envía su `task_id` para generar el vídeo final. Basta con `model` y `draft_task_id`. Si indicas `resolution`, debe ser `1080p`.

```json theme={null}
{
  "model": "apimart-zoe",
  "draft_task_id": "task_01KZOEEXAMPLE"
}
```

> [!WARNING]
>
> El vídeo final hereda prompt, medios, duración, proporción, seed y ajustes de audio del borrador. Envía `model`, `draft_task_id`, opcionalmente `resolution: "1080p"` y campos comunes como `nsfw_check` / `webhook`. Los siguientes campos de generación deben estar ausentes; cadenas/arrays vacíos, `false` y `null` también devuelven HTTP 400: `prompt`, `image_urls`, `image_with_roles`, `image`, `images`, `image_url`, `first_frame_image`, `last_frame_image`, `video_urls`, `audio_urls`, `duration`, `seconds`, `aspect_ratio`, `size`, `seed`, `audio`, `generate_audio`, `draft`, `omni_reference_task_type`, `return_last_frame`, `output_format`, `response_format`, `enhance_prompt`. Usa el borrador dentro de las 24 horas desde su creación; ambas generaciones se cobran por separado.

## Consulta de tareas y resultados

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

En la respuesta de envío, `data` es un array; en la consulta, es un objeto de tarea. `data.status`: `pending` = en cola, `processing` = generando, `completed` = éxito, `failed` = fallo. En caso de éxito, lee la dirección del array `data.result.videos[].url`, por ejemplo `data.result.videos[0].url[0]`. Los vídeos se copian al almacenamiento de APIMart. A continuación se muestran solo los campos principales de una consulta exitosa.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZOEEXAMPLE",
    "status": "completed",
    "result": {
      "videos": [
        {
          "url": [
            "https://example.com/generated-video.mp4"
          ],
          "expires_at": 1794475442
        }
      ],
      "last_frame_url": "https://example.com/generated-last-frame.png"
    },
    "progress": 100,
    "completed": 1794389042
  }
}
```

Si la tarea falla, consulta el motivo en `data.error.message`. Los importes cobrados se reembolsan automáticamente.

| Campo | Descripción |
| - | - |
| `data.progress` | Progreso, 0–100. |
| `data.result.videos[].url` | Array de direcciones de vídeo copiadas al almacenamiento APIMart. |
| `data.result.videos[].expires_at` | La dirección caduca 24 horas después de completarse la tarea. Descarga el vídeo cuanto antes. |
| `data.result.last_frame_url` | URL del último fotograma en PNG almacenado en APIMart. Solo aparece si la tarea termina correctamente y la solicitud incluía `return_last_frame: true`. |
| `data.error.message` | Motivo del fallo, solo para `failed`. |
| `data.error.code` | Cadena `task_failed` en caso de fallo. |
| `data.cost` | Coste de la tarea; 0 si falla, tras reembolsar el importe reservado. |

## Reglas de facturación

Facturación por segundo según la resolución y el uso de vídeos de referencia. Tarifas y descuentos en la [página de precios](https://apimart.ai/pricing). `D` es la duración de salida usada para facturar, en segundos.

| Caso | Duración facturable de salida D |
| - | - |
| Generación normal: `duration: 4–30` u omitido (por defecto 5) | Se facturan los segundos solicitados, sin ajustar a la duración del vídeo terminado. |
| `duration: -1` / edición de vídeo `edit` | Se reservan 30 segundos y se ajusta el importe con la duración real redondeada al segundo más cercano (0.5 hacia arriba). |
| Vídeo final | Hereda la duración del borrador. Si este usó `duration: -1`, se toma su duración real como base, sin reajustar a la del vídeo final. |

* Duración total de referencias `R`: medir cada vídeo al enviar, sumar las duraciones y redondear la suma hacia abajo a segundos enteros. No se ajusta después.
* Sin vídeo de referencia: segundos facturables = `D`. Con referencia: `D + max(R, ceil(D × 2/3))`. `ceil` redondea hacia arriba al entero. Se usa la tarifa con vídeo de referencia.
* Ejemplo: solicitar 8 segundos mantiene `D = 8`, aunque el vídeo dure 8.2 segundos. Una duración automática de 8.5 da `D = 9`. Referencias de 2.8 y 3.8 segundos se suman a 6.6 y luego se redondean hacia abajo: `R = 6`.
* Borrador (`480p`) y vídeo final (`1080p`) se facturan por separado. Las referencias del borrador cuentan con su duración original también para el vídeo final, sin volver a subirlas.
* Los envíos fallidos no se cobran. Las tareas fallidas se reembolsan automáticamente.

## Errores comunes

Los envíos fallidos devuelven un objeto `error`: detalles en `error.message` y código de cadena en `error.code`, distinto del estado HTTP. No se cobran.

| HTTP | `error.code` | Causa y solución |
| - | - | - |
| 400 | `invalid_request_error` | Revisa duración, resolución, proporción, cantidad/combinación de medios, parámetros no admitidos y restricciones del borrador/final. También si `draft_task_id` no existe, no es un borrador, no ha terminado o tiene más de 24 horas. También incluye dimensiones, duración exacta o fps no válidos y combinar `image_urls` (con sus alias) con `image_with_roles`. Los errores de vídeo incluyen las medidas reales. Comprueba también duración del audio, tipo de tarea/restricciones de edición, `output_format`, coincidencia de alias de audio y presencia de campos prohibidos. |
| 400 | `nsfw_content_detected` | Rechazo de moderación. Las categorías aparecen en `error.message`. Muestra el rechazo y modifica el contenido antes de reenviar. Sin cargo. |
| 400 | `input_video_probe_failed` | Vídeo de referencia inaccesible o duración no detectable. Revisa dirección y contenido. |
| 402 | `payment_required` | Saldo insuficiente; la duración automática reserva 30 segundos. |
| 503 | `draft_channel_unavailable` / `draft_task_unavailable` | Canal del borrador no disponible o consulta temporalmente fallida. Reintenta más tarde o crea otro borrador. |


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