Tutorial de integración de la API Wan 3.0: curl, Python y todos los parámetros

Wan 3.0 versión estándar (wan3.0-video) utiliza en HiAPI la interfaz asíncrona unificada: se envía con POST /v1/tasks, se obtiene un taskId y luego se consulta el resultado con GET /v1/tasks/{taskId}. Basta con escribir una sola frase de prompt para generar un video con sonido; también se pueden añadir el primer fotograma, el último fotograma, o hasta 10 imágenes de referencia, 5 videos de referencia y 5 audios de referencia para controlar conjuntamente la generación. Este artículo ofrece ejemplos de curl y Python listos para ejecutar, todos los parámetros actuales y varios puntos a tener en cuenta antes de lanzar a producción.

Primero, el precio

Resolución	Por segundo	5 segundos
480P	$0.04	$0.20
720P	$0.08	$0.40
1080P (predeterminado)	$0.16	$0.80

Precio actual de HiAPI, verificado el 18 de octubre de 2026. El sonido está activado por defecto y no se cobra aparte.

Atención a los valores predeterminados: si no se especifica resolution, se usa 1080P; si no se especifica duration, se usan 5 segundos, lo que cuesta $0.80 por video. Al probar prompts, recuerda escribir explícitamente "resolution": "480P".

Para generar más rápido se puede usar la versión acelerada wan3.0-video-prime, cuyo precio es más del doble que la versión estándar (480P a $0.0875 por segundo).

Un video real generado

480P, 16:9, 5 segundos, con sonido:

A steaming noodle stall at a night market, close on the cook's hands as she lifts a tangle of noodles from a boiling pot and swirls them into a blue-rimmed bowl; slow push-in, warm tungsten light against cool blue street glow, steam drifting through the frame. Sound: rolling boil, the clink of a ladle, crowd murmur and a scooter passing in the distance.

Generar con este prompt →

wan3.0-video, 480P, 5 segundos, $0.20.

Ejecutar el primer ejemplo

Preparación: crea una API Key en la consola. Los nuevos usuarios registrados reciben 200 créditos de regalo.

curl: enviar la tarea

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Devuelve inmediatamente un taskId y la generación se realiza en segundo plano:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: consultar el resultado

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Cuando data.status cambie a success, data.output[0].url será la dirección del video. La dirección temporal caduca aproximadamente a los 7 días, así que descárgalo y guárdalo cuanto antes. fail indica error y no se cobra.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "wan3.0-video",
    "input": {
        "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
        "resolution": "480P",
        "duration": 5,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(10)

print(d["output"][0]["url"] if d["status"] == "success" else d)

Los videos cortos suelen generarse en pocos minutos; un intervalo de sondeo de 10 segundos es suficiente.

Todos los parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Texto	Escena, acción, cámara, iluminación y sonido se escriben aquí; en el modo de referencia se usan Image1, Video1, Audio1 para referirse a los materiales
resolution	No	480P / 720P / 1080P (predeterminado)	Determina el precio por segundo
duration	No	Entero 2–30, predeterminado 5	La duración total de los videos de referencia más la duración de salida no puede superar los 30 segundos
aspect_ratio	No	adaptive (predeterminado) / 16:9 / 4:3 / 1:1 / 3:4 / 9:16	adaptive elige automáticamente según el material y el prompt
audio	No	Booleano, predeterminado true	Si incluir pista de audio sincronizada
seed	No	0–2147483647	Fijarlo facilita la reproducibilidad
first_frame_url	No	1 URL de imagen	Modo primer fotograma
last_frame_url	No	1 URL de imagen	Se usa junto con el primer fotograma para especificar el último fotograma
reference_image_urls	No	Máximo 10	Imágenes de referencia
reference_video_urls	No	Máximo 5, cada uno de 1–15 segundos, total ≤15 segundos	Videos de referencia
reference_audio_urls	No	Máximo 5 WAV/MP3	Debe usarse junto con imágenes o videos
reference_file_urls	No	Máximo 1	Documento o presentación
reference_link_urls	No	Máximo 1	Página web que no requiera inicio de sesión

Los dos modos no se pueden mezclar: el modo primer/último fotograma y el modo de referencia reference_* son mutuamente excluyentes; en una solicitud solo se puede elegir uno.

Ejemplo del modo de referencia:

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "Use Image1 as the product: slow quarter orbit around it on a wooden counter, soft morning window light. Sound: gentle pouring water.",
    "reference_image_urls": ["https://example.com/product.jpg"],
    "resolution": "480P",
    "duration": 5
  }
}

Errores comunes

Todos se devuelven de forma síncrona al enviar con HTTP 400, no se crea la tarea y no se cobra:

• duration: maximum: got 99, want 30: la duración supera los 30 segundos.
• resolution: value must be one of '480P', '720P', '1080P': la resolución debe llevar la P en mayúscula.
• additional properties 'negative_prompt', 'image_urls' not allowed: este modelo no tiene prompt negativo; el campo de imágenes de referencia se llama reference_image_urls, no image_urls.
• Una API Key incorrecta devuelve HTTP 401; saldo insuficiente devuelve 402.

Si la tarea falla después de crearse, en la consulta del resultado aparece como status: "fail", pero el código de estado HTTP sigue siendo 200, así que hay que revisar data.status.

A tener en cuenta antes de lanzar a producción

• Usa callback en lugar de sondeo: añade en el nivel superior del cuerpo de la solicitud "callback": {"url": "https://tu-dominio/hiapi/callback", "when": "final"} y HiAPI te notificará activamente cuando termine la tarea. callback va en el nivel superior, no dentro de input.
• Evita el cobro duplicado: incluye el encabezado Idempotency-Key al enviar. Si reintentas tras un timeout de red con la misma key, se devuelve el taskId original y no se crea otra tarea.
• Guarda cuanto antes: la dirección temporal caduca en unos 7 días. Si necesitas conservarlo a largo plazo, pasa "storage": "persistent" al crear la tarea o conviértelo después a almacenamiento persistente; consulta la documentación de creación de tareas.

Preguntas frecuentes

¿Se puede usar sin imágenes de referencia?

Sí. Basta con escribir prompt para generar un video; los materiales de referencia son opcionales.

¿El sonido cuesta más?

No. audio está activado por defecto y el precio solo depende de la resolución y los segundos. Si no quieres sonido, pasa false.

¿Quieres formato vertical?

Pasa 9:16 en aspect_ratio.

¿Se pueden usar el primer fotograma y las imágenes de referencia juntos?

No, hay que elegir uno de los dos.

Para más formas de escribir prompts, consulta la guía completa de prompts de Wan 3.0, con videos reales para los 4 escenarios. También puedes copiar directamente el prompt del puesto de fideos de arriba y generar uno por $0.20.