Passer au contenu principal
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 le point d’entrée unifié /happyhorse/videos et le paramètre action.

Processus de demande

Pour utiliser l’API HappyHorse Videos, obtenez d’abord votre API Token depuis la console Ace Data Cloud et conservez-le pour une utilisation ultérieure. 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 à 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. Lors de votre première demande, un quota gratuit vous sera offert pour une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde général dans la console.
📘 Documentation complète : HappyHorse Videos API →

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, et nécessite la transmission de 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, et nécessite la transmission de 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, et nécessite la transmission de prompt et de 1 à 9 image_urls.
  • video_edit : édition de vidéo, prend en charge happyhorse-1.0-video-edit, et nécessite la transmission de prompt et de video_url, avec la possibilité de transmettre en supplément 0 à 5 images de référence image_urls.
Chaque action utilise le modèle 1.1 par défaut ; video_edit ne dispose actuellement que de happyhorse-1.0-video-edit.

Utilisation de base

La génération de vidéo à partir de texte nécessite seulement de fournir prompt, et il est également possible de spécifier des paramètres tels que resolution, ratio, duration :
Un exemple de résultat retourné est le suivant :
Description des champs :
  • success : indique si cette requête a réussi.
  • task_id : ID de tâche côté Ace Data Cloud, utilisable pour consulter l’état de la tâche.
  • trace_id : ID de suivi de cette requête, utilisé pour diagnostiquer les problèmes.
  • data : liste des résultats vidéo.
    • id : ID de 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, options possibles 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 : ratio largeur/hauteur de sortie.
Le code CURL correspondant est le suivant :
Le code Python correspondant est le suivant :

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 ratio largeur/hauteur de sortie suivra autant que possible l’image de première image ; par conséquent, cette action ne nécessite pas la transmission de ratio.

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 de 1 à 9 images de référence. Dans le prompt, vous pouvez utiliser character1, character2 et d’autres moyens pour référencer les images dans l’ordre correspondant.

Édition de vidéo

La durée de sortie et le cadrage de video_edit héritent de la vidéo source ; transmettre duration ou ratio ne les modifiera pas ; le cadrage de la génération de vidéo à partir d’image hérite également de l’image source. Les frais d’édition sont calculés selon le total des durées des vidéos d’entrée et de sortie. 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 facultatives seront utilisées comme images de référence, par exemple pour le changement de tenue, le transfert de style ou le remplacement local. audio_setting peut être auto ou origin, où origin indique la conservation de l’audio de la vidéo originale.

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, auquel cas l’API renverra immédiatement task_id et enverra le résultat final par POST à cette adresse une fois la tâche terminée :
Le résultat renvoyé immédiatement est le suivant :
Si vous souhaitez uniquement effectuer un sondage, sans rappel nécessaire, vous pouvez également transmettre "async": true, puis interroger le résultat de la tâche via HappyHorse Tasks API.

Informations de facturation

HappyHorse facture en fonction du nombre de secondes de vidéo générée et de la résolution :
  • 720P : à partir d’environ 0,105 $ / seconde.
  • 1080P : à partir d’environ 0,18 $ / seconde.
  • video_edit : facturé selon la durée cumulée 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 avec la requête, l’API renvoie le code d’erreur et la description correspondants. Les erreurs courantes sont les suivantes :
  • 400 : paramètres de requête 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 l’invite a été refusée après avoir déclenché la modération de contenu.
  • 429 : requêtes trop fréquentes, déclenchant la limitation de débit ; veuillez réessayer plus tard.
  • 500 : erreur interne du serveur ou échec de la génération.