> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrucciones de integración de la API de HappyHorse Videos

> HappyHorse Video API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) y guárdelo para su uso posterior.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/happyhorse-tasks).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.