Instrucciones de integración de la API de HappyHorse Videos

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

Proceso de solicitud

Para usar la API de HappyHorse Videos, primero obtenga su API Token en la consola de Ace Data Cloud y guárdelo para su uso posterior.

Si aún no ha iniciado sesión o no se ha registrado, se le redirigirá automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual. Un API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluye crédito gratuito para una experiencia sin costo; cuando el crédito sea insuficiente, 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 predeterminada, admite happyhorse-1.0-t2v y happyhorse-1.1-t2v, debe incluir prompt.
image_to_video: generación de video a partir de imagen de primer fotograma, admite happyhorse-1.0-i2v y happyhorse-1.1-i2v, debe incluir 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, debe incluir prompt y 1–9 image_urls.
video_edit: edición de video, admite happyhorse-1.0-video-edit, debe incluir prompt y video_url, y puede incluir adicionalmente 0–5 imágenes de referencia 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, y también se pueden especificar parámetros como resolution, ratio y duration:

{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Un ejemplo del resultado devuelto es el siguiente:

{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}

Descripción de los campos:

success: si esta solicitud se realizó correctamente.
task_id: ID de la tarea en Ace Data Cloud, que puede utilizarse 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 la tarea en HappyHorse.
- video_url: dirección del enlace CDN del video generado.
- state: estado de la tarea, opciones pending / succeeded / error.
- duration: duración facturable del video, 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:

curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'

El código Python correspondiente es el siguiente:

import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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

Al usar 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 pasar ratio.

{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}

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

Al usar reference_to_video, se pueden pasar 1–9 imágenes de referencia en image_urls. En el texto de indicación, se pueden utilizar character1, character2 y otras formas para hacer referencia a las imágenes en el orden correspondiente.

{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Edición de video

Al usar video_edit, se debe pasar el video que se desea 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 significa conservar el audio del video original.

{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}

Devolución de llamada asíncrona

La generación de video requiere cierto tiempo de procesamiento. Si no desea mantener una conexión larga en espera, puede pasar callback_url; en este caso, la API devolverá inmediatamente task_id, y cuando la tarea se complete, enviará el resultado final mediante POST a esta dirección:

{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}

El resultado devuelto inmediatamente es el siguiente:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

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 HappyHorse Tasks API.

Explicación de la 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 de facturación real se determinará según las estadísticas después de que la tarea se complete.

Las tareas fallidas no se cobran ni consumen la cuota gratuita.

Manejo de errores

Cuando haya un problema con la solicitud, la API devolverá el código de error y la descripción correspondientes; los más 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 está fuera del 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 en la generación.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Instrucciones de integración de la API de HappyHorse Videos

Proceso de solicitud

Tipos de operación

Uso básico

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

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

Edición de video

Devolución de llamada asíncrona

Explicación de la facturación

Manejo de errores

​Proceso de solicitud

​Tipos de operación

​Uso básico

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

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

​Edición de video

​Devolución de llamada asíncrona

​Explicación de la facturación

​Manejo de errores

Proceso de solicitud

Tipos de operación

Uso básico

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

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

Edición de video

Devolución de llamada asíncrona

Explicación de la facturación

Manejo de errores