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

# Instructions d’intégration de l’API HappyHorse Videos

> HappyHorse Video API guide - Ace Data Cloud

Cet article présente la méthode d’intégration de l’API HappyHorse Videos. Cette interface prend en charge la génération de vidéos à partir de texte, la génération de vidéos à partir d’une image de première image, la génération de vidéos à partir d’images de référence et l’édition de vidéos via l’entrée unifiée `/happyhorse/videos` et le paramètre `action`.

## Processus de demande

Pour utiliser l’API HappyHorse Videos, obtenez d’abord votre API Token dans la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications), à conserver en réserve.

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

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, puis vous reviendrez automatiquement sur la page actuelle une fois terminé.

**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service.** La première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde universel dans la [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## Types d’opérations

`action` détermine le mode de génération de cette requête :

* `generate` : génération de vidéo à partir de texte, action par défaut, prend en charge `happyhorse-1.0-t2v` et `happyhorse-1.1-t2v`, doit recevoir `prompt`.
* `image_to_video` : génération de vidéo à partir d’une image de première image, prend en charge `happyhorse-1.0-i2v` et `happyhorse-1.1-i2v`, doit recevoir `image_url`.
* `reference_to_video` : génération de vidéo à partir d’images de référence, prend en charge `happyhorse-1.0-r2v` et `happyhorse-1.1-r2v`, doit recevoir `prompt` et 1–9 `image_urls`.
* `video_edit` : édition de vidéo, prend en charge `happyhorse-1.0-video-edit`, doit recevoir `prompt` et `video_url`, et peut recevoir en supplément 0–5 images de référence `image_urls`.

Chaque action utilise par défaut le modèle 1.1 ; `video_edit` ne propose actuellement que `happyhorse-1.0-video-edit`.

## Utilisation de base

La génération de vidéo à partir de texte nécessite uniquement de fournir `prompt`, et peut également spécifier des paramètres tels que `resolution`, `ratio` et `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 exemple de résultat retourné est le suivant :

```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
    }
  ]
}
```

Description des champs :

* `success` : indique si cette requête a réussi.
* `task_id` : ID de la tâche côté Ace Data Cloud, peut être utilisé pour consulter l’état de la tâche.
* `trace_id` : ID de suivi de cette requête, utilisé pour résoudre les problèmes.
* `data` : liste des résultats vidéo.
  * `id` : ID de la tâche côté HappyHorse.
  * `video_url` : adresse du lien CDN de la vidéo générée.
  * `state` : état de la tâche, parmi `pending` / `succeeded` / `error`.
  * `duration` : durée de la vidéo facturée, en secondes ; pour `video_edit`, il s’agit du total des durées des vidéos d’entrée et de sortie.
  * `resolution` : résolution de sortie.
  * `ratio` : rapport largeur-hauteur de sortie.

Le code CURL correspondant est le suivant :

```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
}'
```

Le code Python correspondant est le suivant :

```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)
```

## Génération de vidéo à partir d’une image de première image

Lors de l’utilisation de `image_to_video`, `image_url` sera utilisée comme première image de la vidéo. Le rapport largeur-hauteur de sortie suivra autant que possible l’image de première image, cette action n’a donc pas besoin de transmettre `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
}
```

## Génération de vidéo à partir d’images de référence

Lors de l’utilisation de `reference_to_video`, `image_urls` peut transmettre 1–9 images de référence. Dans le texte d’invite, vous pouvez utiliser `character1`, `character2` et d’autres moyens pour référencer les images dans l’ordre correspondant.

```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
}
```

## Édition de vidéo

Lors de l’utilisation de `video_edit`, il est obligatoire de transmettre la vidéo à éditer `video_url` et l’intention d’édition `prompt`. Les `image_urls` optionnelles serviront d’images de référence, par exemple pour le changement de tenue, le transfert de style ou le remplacement localisé. `audio_setting` peut être `auto` ou `origin`, où `origin` signifie conserver l’audio de la vidéo originale.

```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"
}
```

## Rappel asynchrone

La génération de vidéos nécessite un certain temps de traitement. Si vous ne souhaitez pas maintenir une connexion longue en attente, vous pouvez transmettre `callback_url`. Dans ce cas, l’API renverra immédiatement le `task_id`, et une fois la tâche terminée, le résultat final sera envoyé par POST à cette adresse :

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

Le résultat renvoyé immédiatement est le suivant :

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

Si vous souhaitez uniquement effectuer un sondage, sans avoir besoin de rappel, vous pouvez également transmettre `"async": true`, puis consulter le résultat de la tâche via [l’API HappyHorse Tasks](https://platform.acedata.cloud/documents/happyhorse-tasks).

## Explication de la facturation

HappyHorse facture selon le nombre de secondes de la vidéo produite et la résolution :

* `720P` : à partir d’environ 0,105 \$ / seconde.
* `1080P` : à partir d’environ 0,18 \$ / seconde.
* `video_edit` : facturé selon la durée totale de la vidéo d’entrée et de la vidéo de sortie ; la durée réellement facturée est basée sur les statistiques après l’achèvement de la tâche.

Les tâches échouées ne sont pas facturées et ne consomment pas non plus le quota gratuit.

## Gestion des erreurs

Lorsqu’un problème survient dans la requête, l’API renvoie le code d’erreur et l’explication correspondants. Les plus courants sont les suivants :

* `400` : les paramètres de la requête sont incorrects, par exemple l’action et le modèle ne correspondent pas, `prompt` / `image_url` / `video_url` est manquant, ou `duration` dépasse la plage de 3 à 15 secondes.
* `401` : échec de l’authentification, le token est invalide ou ne correspond pas à l’API.
* `403` : solde insuffisant, ou le prompt a été refusé après avoir déclenché la modération de contenu.
* `429` : les requêtes sont trop fréquentes, la limitation de débit est déclenchée, veuillez réessayer plus tard.
* `500` : erreur interne du serveur ou échec de la génération.


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