Crear videos cortos con wan2.7-video/text-to-video@pro: flujo de trabajo completo con la API de hiapi

El éxito de un video corto depende de la velocidad de iteración: necesitas muchos clips candidatos, en formato vertical, con sonido y rápido. Esta guía gira en torno a eso, usando wan2.7-video/text-to-video@pro en hiapi: el modelo de texto a video Tongyi Wanxiang 2.7 de Alibaba, con salida de hasta 1080P, audio nativo y clips de hasta 15 segundos. Cada estructura de solicitud, límite de parámetros y mensaje de error a continuación se verificó ejecutándolos realmente contra la API en producción al momento de escribir este artículo, y los dos clips de demostración incrustados también se generaron tal cual con el código mostrado.

Qué te ofrece el modelo

wan2.7-video/text-to-video@pro se ofrece a través del endpoint unificado de tareas asíncronas de hiapi (/v1/tasks). Características clave, verificadas contra el esquema en línea:

• Salida: MP4 H.264, hasta 1080P, con pista de audio AAC nativa: el modelo genera sonido ambiente y efectos de sonido a partir de tu prompt, sin necesidad de un paso de audio independiente.
• Duración: de 2 a 15 segundos por clip (segundos enteros).
• Relación de aspecto: 16:9, 9:16, 1:1, 4:3, 3:4: verdadero vertical 9:16, compatible con formatos tipo Shorts/Reels/TikTok, sin recortes.
• Facturación: se cobra por segundo de video de salida, desde $0.167/segundo al momento de escribir: un clip de 5 segundos en 1080P cuesta aproximadamente $0.84. Antes de generar en lote, confirma siempre en la página de precios.

El video no tiene modo síncrono: debes crear la tarea, consultar su estado hasta que termine y luego descargar el resultado.

Ejemplo mínimo funcional (curl)

Crear la tarea:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "微距棚拍：一滴宝蓝色墨水落入清水中，慢动作绽放，墨丝舒展成云朵形状，背景为明亮的白色无缝背景，清晰的高调布光，轻柔的环境嗡鸣",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Respuesta:

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

Consultar el resultado:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Durante el renderizado, data.status es handling; al terminar cambia a success y data.output[0].url contiene el MP4. Esta solicitud generó tal cual este clip:

⚠️ La URL de salida es un enlace temporal con marca de tiempo expireAt. En cuanto la tarea tenga éxito, descarga el archivo a tu propio almacenamiento: no lo enlaces en caliente ni lo guardes en la base de datos.

Esquema de entrada completo (verificado contra la API en línea)

La API valida input de forma estricta y rechaza campos desconocidos. Esta es la lista completa de campos aceptados, obtenida sondeando directamente el endpoint, no copiada de ningún sitio:

Campo	Tipo	Restricción	Obligatorio
prompt	string	Descripción de la escena; también impulsa el audio generado	✅
ratio	string	Uno de 16:9, 9:16, 1:1, 4:3, 3:4	Opcional
resolution	string	720P o 1080P	Opcional
duration	integer	2–15 (segundos)	Opcional
negative_prompt	string	Contenido que se debe suprimir (p. ej., marcas de agua, superposiciones de texto)	Opcional
seed	integer	Reproducible entre reintentos	Opcional
watermark	boolean	Activa o desactiva la marca de agua del proveedor	Opcional

Dos trampas que te ayudarán a evitar un 400:

• El nombre del campo es ratio, no aspect_ratio: los modelos de imagen en hiapi usan aspect_ratio, pero este modelo de video no. Enviar aspect_ratio devuelve additional properties 'aspect_ratio' not allowed.
• duration se valida en el servidor: duration: minimum: got 1, want 2 y maximum: got 999, want 15 son los errores exactos que obtienes al salir del rango 2–15.

Python de extremo a extremo: entra un prompt, sale un MP4 listo para publicar

Este es el flujo de trabajo completo: crear, consultar y descargar, sin SDK, solo con requests:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = 竖屏短视频
            "resolution": "1080P",
            "duration": duration,          # 2..15 秒
            "negative_prompt": "文字叠加, 水印, 扭曲的手",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # 临时链接——请立即下载
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "黄金时刻手持竖屏夜市镜头：一位街头小吃摊主 "
    "在火焰翻腾的炒锅中颠炒滋滋作响的面条，蒸汽和橙色火星向 "
    "镜头旋转飘来，霓虹招牌在虚化背景中透出柔和的粉色和青色，浅 "
    "景深，充满动感的手持纪实感，伴有滋滋声和噼啪声",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

Este es el clip que generó realmente esa llamada: vertical 1080×1920, 5 segundos, con el chisporroteo generado a partir del texto del prompt:

En mi ejecución, un clip de 4 segundos en 16:9 tardó unos 3 minutos en completarse, y el de 5 segundos en 9:16 un poco más: reserva unos minutos por clip, consulta cada 10 segundos aproximadamente y no satures el endpoint.

Consejos de prompts para videos cortos: el movimiento y el audio los decide el prompt

El esquema no tiene parámetros de control de cámara ni de movimiento: todo lo relacionado con movimiento, ritmo y sonido se guía mediante el lenguaje del prompt. Lo que funcionó en mis pruebas:

• Nombra explícitamente el comportamiento de la cámara: por ejemplo, "handheld" (cámara en mano), "slow push-in" (acercamiento lento), "macro" (macro), "shallow depth of field" (profundidad de campo reducida). El temblor documental del clip del mercado nocturno provino por completo de la palabra "handheld".
• Describe el audio que quieres: el modelo genera sonido a partir del prompt. "sizzling and crackling sounds" (sonidos de chisporroteo y crujido) y "gentle ambient hum" (un suave zumbido ambiental) aparecieron en la pista de audio de salida.
• Pon el gancho al principio: en videos cortos, el primer segundo lo decide todo. Coloca el elemento más dinámico (el salteado con llamas, la gota de tinta cayendo al agua) al inicio de la descripción del prompt.
• Usa negative_prompt de forma defensiva: "text overlay, watermark, distorted hands" (superposición de texto, marca de agua, manos distorsionadas) limpia los defectos más comunes sin afectar al prompt principal.
• Fija seed al iterar: con el seed fijo, cambia solo una frase del prompt a la vez y observa qué efecto tiene realmente esa frase.

¿Necesitas control del primer fotograma? Usa la variante de imagen a video

Si tu flujo de trabajo parte de un fotograma clave ya diseñado (una imagen de producto, un primer fotograma con el estilo de la marca), el texto a video no acepta imágenes de entrada. El modelo complementario wan2.7-video/image-to-video@pro sí lo hace: acepta un array media compuesto por objetos {"url": "...", "type": "image"}, junto con los mismos campos prompt / resolution / duration, y anima el fotograma que le proporciones en lugar de generar uno desde cero. Es el mismo flujo basado en tareas y la misma facturación por segundo. Una cadena de producción práctica: genera fotogramas fijos con el modelo de imagen, revísalos y luego anima solo los fotogramas aprobados; así solo gastas en generación de video con fotogramas ya validados.

Errores comunes y lo que significan realmente

• invalid input: prompt: missing required field "prompt": prompt es el único campo obligatorio.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4': pasaste una relación de aspecto no compatible con el modelo (o la escribiste mal).
• invalid input: <root>: additional properties '...' not allowed: campo desconocido; el esquema es estricto, revisa la tabla anterior.
• status: "fail" con TASK_FAILED: la tarea falló después de crearse; crea una nueva tarea (reutiliza tu seed para mantener la reproducibilidad).
• El archivo descargado es muy pequeño o no se reproduce: probablemente accediste a una URL de salida ya caducada. Revisa de nuevo expireAt y descarga justo después de success.

Resumen

Un POST, un bucle de consulta y una descarga: esa es toda la distancia entre un prompt de texto y un MP4 vertical con sonido listo para publicar. Si vas a construir un flujo de producción de videos cortos, obtén una API key en la consola, empieza con la función de Python anterior y explora el resto del catálogo de modelos: el mismo patrón /v1/tasks (como se muestra en nuestra guía de seedance-2.0-fast) se aplica a todos los modelos de video de la plataforma, así que cambiar de modelo después solo requiere modificar una línea.