Saltar al contenido principal
Este documento presenta el método de integración de HappyHorse Videos API. Esta interfaz admite la generación de video a partir de texto, la generación de video a partir de una imagen de primer fotograma, la generación de video a partir de imágenes de referencia y la edición de video mediante la entrada unificada /happyhorse/videos y el parámetro action.

Proceso de solicitud

Para utilizar HappyHorse Videos API, primero obtenga su API Token en la consola de Ace Data Cloud y guárdelo como respaldo. Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarlo a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual. Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud otorgará créditos gratuitos para una experiencia gratuita; cuando los créditos sean insuficientes, puede recargar saldo general en la consola.
📘 Documentación completa: HappyHorse Videos API →

Tipos de operación

action determina el modo de generación de esta solicitud:
  • generate: generación de video a partir de texto, action predeterminado, admite happyhorse-1.0-t2v y happyhorse-1.1-t2v, se debe proporcionar prompt.
  • image_to_video: generación de video a partir de una imagen de primer fotograma, admite happyhorse-1.0-i2v y happyhorse-1.1-i2v, se debe proporcionar image_url.
  • reference_to_video: generación de video a partir de imágenes de referencia, admite happyhorse-1.0-r2v y happyhorse-1.1-r2v, se deben proporcionar prompt y 1–9 image_urls.
  • video_edit: edición de video, admite happyhorse-1.0-video-edit, se deben proporcionar prompt y video_url, y se pueden proporcionar adicionalmente 0–5 imágenes de referencia en image_urls.
Cada acción utiliza el modelo 1.1 de forma predeterminada; video_edit actualmente solo cuenta con happyhorse-1.0-video-edit.

Uso básico

La generación de video a partir de texto solo requiere proporcionar prompt; también se pueden especificar parámetros como resolution, ratio, duration, etc.:
El ejemplo de resultado devuelto es el siguiente:
Descripción de campos:
  • success: si esta solicitud se realizó correctamente.
  • task_id: ID de tarea del lado de Ace Data Cloud, que se puede utilizar para consultar el estado de la tarea.
  • trace_id: ID de seguimiento de esta solicitud, utilizado para solucionar problemas.
  • data: lista de resultados de video.
    • id: ID de tarea del lado de HappyHorse.
    • video_url: dirección del enlace CDN del video generado.
    • state: estado de la tarea, opcional entre pending / succeeded / error.
    • duration: duración del video facturable, en segundos; para video_edit, es la suma de las duraciones de los videos de entrada y salida.
    • resolution: resolución de salida.
    • ratio: relación de aspecto de salida.
El código CURL correspondiente es el siguiente:
El código Python correspondiente es el siguiente:

Generación de video a partir de una imagen de primer fotograma

Al utilizar image_to_video, image_url se utilizará como el primer fotograma del video. La relación de aspecto de salida seguirá en la medida de lo posible la imagen del primer fotograma, por lo que esta acción no requiere proporcionar ratio.

Generación de video a partir de imágenes de referencia

Al utilizar reference_to_video, image_urls puede recibir entre 1 y 9 imágenes de referencia. En el prompt se pueden utilizar formas como character1, character2, etc. para hacer referencia a las imágenes en el orden correspondiente.

Edición de video

La duración de salida y el formato de video_edit heredan el video de origen; proporcionar duration o ratio no los cambiará; el formato del video generado a partir de imagen también hereda la imagen de origen. La tarifa de edición se calcula según la suma de las duraciones de los videos de entrada y salida. Al utilizar video_edit, se debe proporcionar el video que se va a editar, video_url, y la intención de edición, prompt. Los image_urls opcionales se utilizarán como imágenes de referencia, por ejemplo, para cambio de vestimenta, transferencia de estilo o reemplazo local. audio_setting puede ser opcionalmente auto u origin, donde origin indica conservar el audio original del video.

Devolución de llamada asíncrona

La generación de video requiere cierto tiempo de procesamiento. Si no desea mantener una conexión larga esperando, puede pasar callback_url; en este caso, la API devolverá inmediatamente task_id y, una vez completada la tarea, enviará el resultado final mediante POST a esa dirección:
El resultado devuelto inmediatamente es el siguiente:
Si solo desea realizar sondeos y no necesita una devolución de llamada, también puede pasar "async": true y posteriormente consultar el resultado de la tarea mediante la API de tareas de HappyHorse.

Descripción de facturación

HappyHorse cobra según los segundos de video de salida y la resolución:
  • 720P: desde aproximadamente $0.105 / segundo.
  • 1080P: desde aproximadamente $0.18 / segundo.
  • video_edit: se cobra según la suma de la duración del video de entrada y del video de salida; la duración real facturada se basará en las estadísticas tras completarse la tarea.
Las tareas fallidas no se cobran ni consumen la cuota gratuita.

Manejo de errores

Cuando hay un problema con la solicitud, la API devolverá el código de error y la descripción correspondientes; los comunes son los siguientes:
  • 400: los parámetros de la solicitud son incorrectos, por ejemplo, action y model no coinciden, falta prompt / image_url / video_url, o duration excede el rango de 3–15 segundos.
  • 401: la autenticación falló; el token no es válido o no coincide con la API.
  • 403: saldo insuficiente, o la solicitud fue rechazada porque el prompt activó la revisión de contenido.
  • 429: las solicitudes son demasiado frecuentes, se activó la limitación de velocidad; inténtelo de nuevo más tarde.
  • 500: error interno del servidor o fallo de generación.