> ## 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ídeos Muse Video Ext

> Genera un vídeo MP4 a partir de texto o de hasta 9 imágenes de referencia: unos 10 segundos, 720p, con sonido.

> [!NOTE]
>
> Esta API es asíncrona. Guarda el ID de tarea tras el envío y consulta `GET /v1/tasks/{task_id}` para obtener el estado y los resultados. En la respuesta de envío predeterminada, el ID está en `data[0].task_id`.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: <unique-operation-key>' \
  --data '{
    "model": "muse-video-ext",
    "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
    "aspect_ratio": "16:9",
    "duration": 10,
    "resolution": "720p"
  }'
```

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

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Idempotency-Key": "<unique-operation-key>"
    },
    json={
        "model": "muse-video-ext",
        "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
        "aspect_ratio": "16:9",
        "duration": 10,
        "resolution": "720p"
    }
)
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",
    Accept: "application/json",
    "Idempotency-Key": "<unique-operation-key>"
  },
  body: JSON.stringify({
    "model": "muse-video-ext",
    "prompt": "Waves gently wash a beach at sunset, slow camera pan, natural ocean sounds, no text",
    "aspect_ratio": "16:9",
    "duration": 10,
    "resolution": "720p"
  })
});
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_01K..."
    }
  ]
}
```

## Cabeceras de solicitud

**Authorization** `string` *required*

Usa una APIMart API Key con el formato `Bearer <token>`. Tanto el envío como las consultas requieren autenticación con la misma identidad de usuario.

**Idempotency-Key** `string`

Muy recomendable. Usa una clave nueva para cada generación independiente (1–191 caracteres ASCII visibles; se recomienda UUID). Sustituye `<unique-operation-key>` en los ejemplos. Tras un tiempo de espera agotado o un fallo de red, repite con el mismo endpoint, cuerpo, versión de respuesta y clave. Una vez recibido el ID, consulta únicamente esa tarea.

## Parámetros de solicitud

**model** `string` *required*

Valor fijo: `muse-video-ext`.

**prompt** `string` *required*

Descripción del contenido deseado en chino o inglés. No puede quedar vacía tras quitar los espacios iniciales y finales. Es obligatoria incluso con imágenes de referencia.

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

Hasta 9 entradas de imágenes de referencia no vacías. Admite URL públicas, Data URI (como `data:image/png;base64,...`) o base64 sin prefijo. Omite el campo o envía `[]` para generar solo a partir del texto. Se recomiendan PNG, JPEG y WebP. El servidor debe acceder directamente a las URL sin cookies de inicio de sesión del navegador.

El tamaño original combinado de todas las imágenes no debe superar **11 MiB (11.534.336 bytes)**. Es un límite total, no por imagen. base64 añade tamaño al cuerpo de la solicitud. No envíes URL `blob:`, rutas locales ni objetos `File`.

**aspect\_ratio** `string`

Admite las siete proporciones siguientes. Si se omite, texto a vídeo usa `16:9`; con referencias, sigue su composición. Una proporción explícita tiene prioridad. Para selección automática, omite el campo; no envíes `"auto"`.

`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`

**size** `string`

Campo de compatibilidad que admite las siete proporciones anteriores o `auto`, pero no tamaños en píxeles como `1024x1024`. Enviar solo `size: "auto"` equivale a no indicar proporción. Se recomienda `aspect_ratio`. Si ambos valores son válidos, `aspect_ratio` tiene prioridad, pero cada campo se valida por separado: una proporción válida no corrige un `size` inválido.

**n** `integer` (default: 1)

Solo un resultado por solicitud. Únicamente se acepta el número `1`. Los valores explícitos `0`, negativos o mayores que `1` provocan un error.

**duration** `integer | string` (default: 10)

Fija en unos 10 segundos. Admite el número `10` o las cadenas `"10"` y `"10s"`; se recomienda el número `10`. Alias compatibles: `seconds` y `duration_seconds`. Usa un solo campo de duración; cada campo enviado se valida de forma independiente.

**resolution** `string` (default: 720p)

Solo admite `720p`, no `1080p` ni `4k`. Las dimensiones y la duración reales se obtienen de los metadatos del archivo devuelto.

**audio** `boolean`

Los vídeos incluyen sonido de forma predeterminada; puedes omitir el campo. `true` no cambia este comportamiento y `false` se rechaza.

> [!NOTE]
>
> Devuelve una URL MP4: unos 10 segundos, 720p, con sonido. Las referencias guían la generación, sin garantizar un primer fotograma idéntico píxel a píxel.

### Otros parámetros opcionales

**webhook** `string`

URL base del backend para las notificaciones. La plataforma elimina las barras finales y añade `/callback`: `https://your-backend.example/muse` pasa a ser `https://your-backend.example/muse/callback`. Omítela si solo usas consultas periódicas.

**language** `string`

Controla el idioma de los errores del Webhook, no el contenido generado. Valores: `zh`, `en`, `ja`, `ko`, `ru`, `fr`, `de`, `id`, `pt`, `es`. No admite etiquetas regionales como `zh-CN`. Para las consultas, pasa el idioma por separado como parámetro GET.

## Generación con imágenes de referencia

```json theme={null}
{
  "model": "muse-video-ext",
  "prompt": "The fox in the reference image slowly raises its head, wind moves its fur, gentle camera push-in",
  "image_urls": [
    "https://your-cdn.example/fox.png"
  ],
  "duration": 10,
  "resolution": "720p"
}
```

Sustituye la URL de ejemplo por una imagen accesible. El ejemplo omite la proporción para seguir la composición de la referencia; añade `aspect_ratio` para fijarla. Añade más referencias a `image_urls`, hasta 9 en total.

## Respuesta de envío

La respuesta predeterminada es HTTP `200`, con `data` como array. `submitted` significa que la tarea se ha aceptado, no que haya terminado. Guarda `data[0].task_id` y consulta la tarea.

> **Versión de respuesta opcional: 2026-07-27**
>
> Con la cabecera `X-APIMart-Response-Version: 2026-07-27`, el envío devuelve HTTP `202`. Lee el ID en `data.id` y la ruta de consulta en `data.poll_url`.
>
> ```json theme={null}
> {
>   "code": 202,
>   "request_id": "req_example",
>   "data": {
>     "id": "task_01K...",
>     "object": "generation.task",
>     "type": "video",
>     "status": "pending",
>     "progress": 0,
>     "poll_url": "/v1/tasks/task_01K..."
>   }
> }
> ```
>
> Esta versión no cambia la estructura de las respuestas GET. Si añades esta cabecera, no sigas leyendo el ID de envío en `data[0].task_id`.

## Consultar estado y resultados

Usa el ID completo recibido al enviar y la misma identidad de usuario. `language` es opcional y define el idioma de los errores. Consulta todos los campos en [Estado de tarea](https://docs.apimart.ai/es/api-reference/tasks/status.md).

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

Consulta cada 5–10 segundos, sin solicitudes simultáneas para la misma tarea. Un tiempo de espera del cliente o detener las consultas no cancela la tarea del servidor. Guarda el ID y reanuda las consultas GET más tarde; no envíes automáticamente una nueva generación.

| `data.status` | Acción |
| - | - |
| `pending` / `processing` | En cola o procesándose; continúa consultando. |
| `completed` | Generación correcta; detén las consultas y lee la URL del resultado. |
| `failed` | Generación fallida; detén las consultas y lee `data.error.message`. |
| `unknown` / … | Estado incierto. Conserva el ID y limita los reintentos de consulta; no lo consideres un éxito ni regeneres automáticamente. |

Determina la finalización con `data.status`. HTTP `200` o `progress: 100` por sí solos no indican éxito. Un `polling_error` durante el procesamiento tampoco es un fallo terminal.

Ejemplo de respuesta de una tarea completada (URL de resultado ilustrativa):

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

En las respuestas de consulta, `data` es un objeto y `url` un array de cadenas. El primer resultado está en `data.result.videos[0].url[0]`. Si existe, `expires_at` indica la caducidad en segundos Unix; guarda los archivos necesarios antes de esa fecha. `actual_time` mide el tiempo de procesamiento de la tarea, no la duración de reproducción del vídeo.

## Limitaciones y gestión de errores

No se admiten vídeos o audios de referencia, máscaras, control del primer/último fotograma, extensiones ni remix. `quality` no tiene efecto. Omite `seed`, `negative_prompt`, `width`, `height`, `response_format` y `output_format`, ya que no son parámetros de generación de este modelo. `async: false` no activa la generación síncrona y `stream` no ofrece un flujo SSE de generación.

| HTTP / `error.code` | Acción |
| - | - |
| `400 / invalid_request_error` | Revisa el prompt, el número de referencias, la proporción, el número de resultados y las especificaciones fijas. |
| `409 / idempotency_in_progress` | Espera según `Retry-After` y repite la solicitud original con la misma clave de idempotencia. |
| `409 / idempotency_key_reused` | La misma clave se usó para solicitudes diferentes. Corrige la gestión de claves; cada generación independiente necesita una nueva. |
| `409 / idempotency_result_indeterminate` | Detén los reenvíos automáticos y conserva la clave y los datos de la tarea para investigar. |
| `429` | Espera según `Retry-After` antes de reintentar. |

Las tareas fallidas también pueden devolver HTTP `200`; revisa `data.status` y `data.error.message`. Un error de red o `5xx` al enviar puede ocurrir después de la aceptación, por lo que no debes reenviar inmediatamente con una clave nueva.


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