Wan / HappyHorse: API de generación de video

HopBase expone la generación de video de Wan y HappyHorse mediante el contrato de la API oficial, en las rutas originales. El código escrito con el SDK oficial o la API HTTP oficial migra cambiando únicamente la URL base y la clave: el cuerpo de la solicitud, la forma de la respuesta y las rutas no cambian.

Modelos disponibles

La duración de Wan 3.0 también admite -1 para automático. Su grupo de referencia admite hasta 10 imágenes de referencia, 5 videos de referencia, 5 pistas de audio de referencia, 1 documento y 1 enlace web.

Use exactamente los ID anteriores. No hay alias registrados; los nombres de modelo desconocidos se rechazan. wan3.0-video-prime, happyhorse-1.1-video-edit y la línea HappyHorse 1.0 no se ofrecen.

wan3.0-video y los modelos happyhorse-1.1-* se sirven desde dos grupos separados — Wan 3.0 oficial y HappyHorse 1.1 oficial —, así que una clave solo llega a un modelo si incluye su grupo; una misma clave puede incluir ambos. Confirme qué modelos alcanza su clave con GET /v1/models antes de enviar trabajo de pago.

Los precios por nivel y las especificaciones completas están en las fichas de modelo: wan3.0-video, happyhorse-1.1-t2v, happyhorse-1.1-i2v, happyhorse-1.1-r2v.

Parámetros de la solicitud

Todas las solicitudes usan Authorization: Bearer sk-your-key y Content-Type: application/json. No necesita enviar ninguna cabecera asíncrona: las tareas siempre son asíncronas.

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

HappyHorse trunca sin error los prompts en chino de 2501-5000 caracteres a unos 2500.

input.media

Formatos aceptados en file: docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md.

En Wan 3.0, la entrada de primer / último fotograma y el grupo de referencia (reference_*, file, link) son mutuamente excluyentes.

url acepta una URL pública absoluta http(s) o una URI data: (base64). oss:// se rechaza: el objeto pertenece a su propia cuenta en la nube, a la que la pasarela no tiene acceso.

Los tipos, cantidades y combinaciones se validan al enviar; el tamaño, las dimensiones, el códec, las duraciones y el número de páginas los valida el servicio durante la ejecución. El cuerpo JSON completo está limitado a 128 MiB incluido base64, así que use URL para medios grandes.

parameters

Un parámetro que el modelo no admite devuelve 400 en lugar de ignorarse. La pasarela siempre envía resolution y duration (valores predeterminados arriba); los demás campos omitidos no se envían y se aplican los valores predeterminados del servicio.

Ejemplo de imagen a video:

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "La cámara se acerca lentamente, la luz se desplaza por la escena",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

Respuesta

Respuesta del envío

Un envío exitoso devuelve 200 con el ID de tarea de HopBase en output.task_id del formato de respuesta oficial (con la forma blt…):

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "PENDING"
  },
  "request_id": "..."
}

Campos de la consulta

Consulte GET /api/v1/tasks/{task_id}.

output.task_status (en mayúsculas) avanza PENDING → RUNNING → SUCCEEDED | FAILED; solo estos dos últimos son terminales, así que trate cualquier otro valor como en curso. Un clip típico se completa en 1-5 minutos; los clips largos de Wan 3.0 tardan más. Consulte a intervalos de unos 15 segundos.

En curso

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "RUNNING"
  },
  "model": "wan3.0-video"
}

Completada

Cuando termina con éxito, la respuesta lleva la URL de salida en output.video_url:

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.hop-base.com/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p", "cost": 4.08, "cost_usd": 0.6, "currency": "CNY" }
}

Fallida

Una tarea fallida nunca se factura. code siempre es TaskFailed, así que lea output.message (fallos de tareas asíncronas):

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

Ejemplo mínimo

BASE=https://api.hop-base.com
# 1. Enviar
curl "$BASE/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "Toma aérea de montañas nevadas sobre nubes al amanecer"
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9"
    }
  }'

# 2. Consulte con el output.task_id devuelto, cada unos 15 segundos
curl "$BASE/api/v1/tasks/blt-su-id-de-tarea" \
  -H "Authorization: Bearer sk-your-key"

Notas

• Los campos desconocidos y un segundo valor JSON se rechazan antes de que la solicitud salga. Esto es deliberado.
• Los medios de referencia se descargan en el lado oficial, no en HopBase. Los alojamientos de imágenes que bloquean IP de centros de datos (muchas CDN gratuitas lo hacen) provocan que la tarea falle minutos después del envío; prefiera incrustados data: o su propio almacenamiento de objetos / CDN.
• Consulte GET /api/v1/tasks/{task_id}. Note que esta ruta no lleva /v1 delante de /api, a diferencia de los endpoints de video de otras páginas. No hay endpoint de listado; conserve los ID de tarea por su cuenta.
• Una tarea que sigue sin terminar 2 horas después de su creación se marca como fallida automáticamente, y estas tareas no se pueden cancelar.
• output.video_url es una URL firmada en api.hop-base.com, válida por 24 horas desde el momento en que la tarea se completa.
• Consultar de nuevo devuelve la misma URL sin extenderla, y una URL vencida devuelve 410, así que descargue los resultados dentro de esa ventana.
• usage.ratio refleja la relación de aspecto producida y puede ser dimensiones en bruto (por ejemplo 1632:937) en lugar de uno de los valores del enum de la solicitud.

Errores comunes y soluciones

Los errores de solicitud devuelven {"code":…,"message":…}.

Texto de message para 413 y 404:

request body exceeds the 128 MiB limit (received N bytes)
invalid task ID format
task not found            # también con la clave de otro usuario

Cualquier otro campo (size / n / image de OpenAI, img_url / negative_prompt / shot_type de Wan 2.x, claves extra en media) devuelve 400:

400 {"code":"InvalidParameter","message":"request body does not match the JSON contract: json: unknown field \"size\""}

Cuando una tarea falla, actúe según output.message:

Facturación

Enviar una tarea verifica el saldo disponible menos las estimaciones de las tareas en curso menos la estimación de esta solicitud; si eso no alcanza, recibe un 402 con code insufficient_balance, y la estimación se libera automáticamente al finalizar la tarea. Vea Resumen de video para los detalles compartidos por todas las familias de video. Una tarea fallida nunca se factura.

Ambas series se facturan por duración de video en segundos, con un precio unitario por segundo que varía según el nivel de resolución, no por token:

cargo = usage.billed_seconds × tarifa del nivel usage.billing_bucket

usage.SR indica el nivel de resolución del video generado (480 / 720 / 1080) y es lo que lo selecciona. Las dos series cobran tarifas distintas en el mismo nivel.

Se diferencian en qué cubre la duración facturable:

• wan3.0-video se factura por el video de entrada además del de salida — duración facturable = duración del video de entrada + duración del video de salida —, por lo que usage.input_video_duration se suma a los segundos facturados: vale 0.0 cuando la solicitud no lleva video de entrada.
• Los modelos happyhorse-1.1-* se facturan solo por la salida y, para referencia a video, la documentación oficial fija input_video_duration en 0.

Cuando la tarea termina, el objeto usage de la raíz de la consulta también incluye cost_usd —el importe en USD realmente descontado de su saldo por esta tarea, 0 si falló sin cargo—, cost (el mismo cargo en CNY) y currency (siempre CNY).

Los precios de lista oficiales están en la página de precios. Su tarifa es la que aparece en el catálogo de modelos con la sesión iniciada, y el cargo real de cada solicitud está en su registro de uso.

Próximos pasos

• Resumen de video: retención de saldo, tiempos de espera y URL de resultados comunes a todos los modelos de video
• API de video MiniMax Hailuo H3
• Códigos de error y reintentos: incluye fallos de tareas asíncronas
• Concurrencia, tiempos de espera y facturación