# Wan 3.0 Prime — /videos/generations

Wan 3.0 Prime: el mismo modelo que Wan 3.0, con generación más rápida y cobro por segundo. Texto a vídeo, primer fotograma, primer y último fotograma, referencia multiimagen y edición a partir de un vídeo de referencia en un solo endpoint; 2–30 segundos, 480P / 720P / 1080P. Trabajos asíncronos; los fallos no se cobran.

**Endpoint:** `POST https://nezhagate.com/v1/videos/generations`

## Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace del vídeo. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

**Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, HTTP 202)**

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "Un shiba inu persigue pétalos de cerezo que caen bajo un árbol, sol radiante, cámara lenta", "duration": 5, "resolution": "720P", "size": "16:9"}'
```

Respuesta (HTTP 202)

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "wan3.0-video-prime"
}
```

**Paso 2 · Consulta cada 5–10 segundos hasta que `status` sea `succeeded` o `failed`**

```
curl https://nezhagate.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Respuesta cuando sale bien

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "wan3.0-video-prime",
  "data": [
    {"url": "https://img.nezhagate.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "wan3.0-video-prime"}
}
```

**Paso 3 · `data[0].url` es el clip (MP4). Se guarda 15 días; descárgalo en tu propio almacenamiento para conservarlo más tiempo.**

**Ejemplo completo (Python: enviar, esperar y guardar en disco)**

```
import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. enviar el trabajo
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "wan3.0-video-prime",
    "prompt": "Un shiba inu persigue pétalos de cerezo que caen bajo un árbol, sol radiante, cámara lenta",
    "duration": 5,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 10 segundos, durante una hora como máximo
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar el vídeo
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("wan3.0-video-prime.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

Mientras está en cola, la consulta también devuelve `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). Si se agota el tiempo máximo que fijaste, no vuelvas a enviarlo: el trabajo sigue ahí, así que vuelve a consultar el mismo id más tarde.

## Autenticación
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## De un vistazo

| Duración | 2–30 s |
| --- | --- |
| Resolución | 480P / 720P / 1080P |
| Proporción | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / adaptive |
| Imágenes de referencia | hasta 10 · una como primer fotograma, dos pueden ser primer y último fotograma, más como referencias |
| Vídeos de referencia | hasta 5, 15 s en total |
| Audio de referencia | hasta 5 |
| Sonido | lo decide el modelo; no se puede activar ni desactivar (`audio: false` se rechaza) |
| Longitud del prompt | hasta 5 000 bytes (UTF-8; unos 1 666 caracteres chinos) |
| Forma de cobro | por segundo: tarifa × (segundos de salida + segundos de vídeo de referencia) |

## Parámetros de la petición

El cuerpo JSON de `POST /v1/videos/generations`:

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | El ID del modelo: `wan3.0-video-prime`. |
| prompt | string | Sí | Lo que ocurre en el clip: escena, cámara y movimiento. Hasta 5 000 bytes (UTF-8; un carácter chino cuenta como 3 bytes, así que caben unos 1 666). |
| duration | integer | No | Duración de salida en segundos: cualquier entero de 2 a 30; si se omite, 2. Alias: `seconds`. Con vídeos de referencia, los segundos de salida más los de referencia no pueden superar 30. |
| resolution | string | No | Resolución: 480P / 720P / 1080P; si se omite, 720P. Incluye la P (`720` sin la P se rechaza). |
| size | string | No | Proporción: 16:9 / 9:16 / 1:1 / 4:3 / 3:4; si se omite, 16:9. Con primer fotograma puedes enviar `adaptive` para que el clip siga la proporción de la imagen. Alias: `aspect_ratio`. |
| images | array | No | Imágenes de referencia, hasta 10: una pasa a ser el primer fotograma; dos son referencias por defecto, o primer y último fotograma con `image_role: first_frame`; tres o más son referencias. Menciónalas en el prompt como `@Image1`. Una sola imagen puede ir en `image`. Restricción de revisión de rostros: evita referencias con rostros humanos reales; los rostros realistas también pueden activar la detección. `FaceDetectionSuspect` indica un posible rostro humano real. `DataInspectionFailed` significa que la entrada no superó la revisión de contenido, no que el servicio esté caído. Sustituye la referencia antes de reenviar en vez de repetir la misma entrada; contacta con soporte ante posibles errores. Las tareas fallidas no se cobran. |
| image_role | string | No | Cómo se usan las imágenes: `first_frame` (primer fotograma, o primer y último fotograma; 2 imágenes como máximo) o `reference`. Si se omite, una imagen es el primer fotograma y dos o más son referencias; con vídeos de referencia solo funciona `reference`. |
| video_references | array | No | Vídeos de referencia, hasta 5, cada uno escrito como `{"url": "...", "duration": 5}`: `duration` es la duración de ese vídeo en segundos (1–15) y es obligatorio. 15 s en total como máximo, y los segundos de referencia más los de salida no pueden superar 30. Los segundos de vídeo de referencia también se cobran. El enlace tiene que descargar el archivo en sí; los enlaces a páginas web como YouTube, Bilibili, TikTok o carpetas compartidas en la nube se rechazan con un 400 al enviar. |
| audio_reference | array | No | Audio de referencia, hasta 5, solo URL http(s) públicas; tiene que ir junto con una imagen o un vídeo de referencia. No se cobra. El enlace tiene que descargar el archivo en sí; los enlaces a páginas web como YouTube, Bilibili, TikTok o carpetas compartidas en la nube se rechazan con un 400 al enviar. |
| audio | boolean | No | La pista de sonido la decide el modelo y no se puede activar ni desactivar; `false` se rechaza (400), así que no lo envíes. |
| prompt_extend | boolean | No | Si el modelo puede ampliar tu prompt; si se omite, lo decide el modelo. |
| callback_url | string | No | Adónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo. |
| n | integer | No | Cada trabajo genera un solo clip; no hace falta enviarlo. Un valor mayor que 1 también genera un solo clip, pero al enviar se retiene el precio de n clips y lo retenido de más se devuelve cuando termina el trabajo. |

Los demás campos (`seed`, `negative_prompt`, `fps`, `watermark` y similares) no se reenvían y no cambian el precio; los resultados siempre son MP4 y se devuelven como `url`.

## Precio

Se cobra por segundo: coste = tarifa por segundo de la resolución elegida × (segundos de salida + los segundos de cada vídeo de referencia). Las imágenes y el audio de referencia son gratis. Se retiene al enviar y se reembolsa íntegro si falla. 1 crédito = $0.005.

| Resolución | Créditos / s | USD / s | Clip de 5 segundos |
| --- | --- | --- | --- |
| 480P Aún no disponible | 10.8 | $0.054 | $0.27 |
| 720P Aún no disponible | 22.4 | $0.112 | $0.56 |
| 1080P Aún no disponible | 40 | $0.20 | $1.00 |

El nivel 480P / 720P / 1080P aún no está disponible y se rechaza con 400 al enviar; esta tabla se actualizará sola cuando se abra.

## Material de referencia

- Un solo endpoint; los parámetros eligen el modo: sin imagen es texto a vídeo; una imagen es el primer fotograma; dos imágenes con `image_role: first_frame` son el primer y el último fotograma (la primera abre el clip y la segunda lo cierra); si no, dos o más son referencias, hasta 10.

- Hasta 5 vídeos de referencia (15 s en total, cada uno con su `duration`) sirven para reescribir o continuar ese metraje; con vídeos de referencia, las imágenes solo pueden ser referencias, no fotogramas. Hasta 5 pistas de audio de referencia, solo URL públicas.

- Con primer fotograma, `size: adaptive` hace que el clip siga la proporción de la imagen. Restricción de revisión de rostros: evita referencias con rostros humanos reales; los rostros realistas también pueden activar la detección. `FaceDetectionSuspect` indica un posible rostro humano real. `DataInspectionFailed` significa que la entrada no superó la revisión de contenido, no que el servicio esté caído. Sustituye la referencia antes de reenviar en vez de repetir la misma entrada; contacta con soporte ante posibles errores. Las tareas fallidas no se cobran.

- Cada imagen puede ser una URL pública de imagen, un `data:` URI o base64, de hasta 16 MB; para enviar varias, ponlas en un array en `images`. Guardamos las imágenes antes de poner el trabajo en cola; si alguna no se puede leer, la petición se rechaza con 400, `message` indica cuál y no se cobra nada.

- Los archivos de referencia que alojamos se guardan 7 días; los resultados, 15 días.

**Primer y último fotograma: una transición entre dos imágenes**

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "El amanecer da paso al anochecer, las nubes se desplazan y la luz se vuelve cada vez más cálida", "images": ["https://example.com/first.png", "https://example.com/last.png"], "image_role": "first_frame", "duration": 5, "resolution": "720P", "size": "adaptive"}'
```

`image_role: first_frame` convierte las dos imágenes en el primer y el último fotograma; `size: adaptive` hace que el clip siga la proporción de la primera imagen. Sin `image_role`, dos imágenes son referencias.

## Estado y campos del trabajo

`GET /v1/videos/jobs/{id}` devuelve estos estados; cada campo se describe en [Trabajos asíncronos](https://nezhagate.com/es/docs/guide/async-jobs#fields). Consulta cada 5–10 segundos o deja que un webhook (más abajo) te envíe el resultado. Las consultas son gratis, y cualquier clave de la misma cuenta puede consultar el trabajo.

| Estado | Significado |
| --- | --- |
| queued | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| processing | Generándose. |
| succeeded | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| failed | Falló. El motivo está en `error`; los créditos reservados se devuelven íntegros. |

- `processing` puede volver a `queued`, por ejemplo mientras todas las líneas están ocupadas, mientras se vuelve a obtener un clip ya terminado o tras un reinicio del servicio. Si una línea no puede terminar un trabajo, la pasarela puede pasarlo a la siguiente línea para generarlo de nuevo; pase por las líneas que pase, el trabajo se cobra una sola vez.

- Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de los vídeos, 15 días.

## Cuánto tarda

Normalmente 1–3 minutos, más rápido que Wan 3.0 estándar.

## Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en [Códigos de error](https://nezhagate.com/es/docs/guide/errors).

### Errores al enviar

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | invalid_request | Un parámetro no es válido: la duración, la resolución, la proporción o la cantidad de referencias está fuera del rango de este modelo, el prompt es demasiado largo, no se puede leer una imagen o un vídeo de referencia, se envió `audio: false` a un modelo cuyos clips siempre llevan sonido, etc. `message` indica cuál. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 400 | invalid_callback_url | `callback_url` no es una dirección http(s) pública o supera los 2000 caracteres. | Usa una dirección accesible desde internet. |
| 400 | model_not_found | El ID del modelo está mal escrito, falta `model`, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes). | Usa un ID de modelo de `GET /v1/models` o de la [referencia de la API](https://nezhagate.com/es/docs/api). |
| 401 | invalid_api_key | La clave no existe, se eliminó o está desactivada, o la cuenta está desactivada. | Revisa la clave en la página API Keys de la consola. |
| 402 | insufficient_quota | No hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo. | Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga. |
| 429 | rate_limit_exceeded | Se superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera `Retry-After`. | Espera unos segundos y reintenta, o sube el límite de la clave en la consola. |
| 503 | model_maintenance | El modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar. | Reintenta cuando termine el mantenimiento; consulta el [estado del servicio](https://nezhagate.com/es/status). |
| 503 | service_unavailable | Un fallo temporal de nuestro lado, por ejemplo al guardar un archivo de referencia. No se creó ningún trabajo y no se cobró nada. | Reintenta en breve. |

### Trabajos fallidos (`status` `failed`)

| code | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| content_policy | Wan Standard y Prime: la entrada no superó la revisión. `error.reason` es `FaceDetectionSuspect` (posible rostro humano real) o `DataInspectionFailed` (fallo de revisión del contenido de entrada). `error.message` explica el motivo y cómo ajustar la solicitud. Las tareas fallidas no se cobran. | Reescribe el prompt o cambia la referencia antes de volver a enviarlo; la misma entrada se rechaza otra vez. |
| invalid_request | El proveedor del modelo rechazó la petición: un parámetro o una referencia no se pueden usar, o el contenido no superó la revisión. `message` indica el motivo. | Ajusta los parámetros según indica `message` y vuelve a enviarlo. |
| upstream_error | Cualquier otro fallo: se probaron todas las líneas, el trabajo esperó 15 minutos sin empezar, el proveedor lo rechazó sin dar motivo, etc.; `message` indica cuál. | Volver a enviarlo suele funcionar. |

Decide según `code`, no según el texto de `message`. Trata cualquier `code` que no reconozcas (o un error sin `code`) como `upstream_error`: volver a enviarlo suele funcionar. Todos los trabajos fallidos se reembolsan íntegros.

## Webhooks en lugar de consultas

Añade `callback_url` al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. [Documentación de webhooks →](https://nezhagate.com/es/docs/webhooks)

```
curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "wan3.0-video-prime", "prompt": "Un shiba inu persigue pétalos de cerezo que caen bajo un árbol, sol radiante, cámara lenta", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```