Tutoriel
Comment appeler happyhorse-1.1/text-to-video via l'API HiAPI : exemples curl et Python fonctionnels
Structure de requête, interrogation asynchrone et traitement audio natif pour une intégration fonctionnelle
Sur cette page
Ce que couvre cette intégration
Ce guide vous accompagne tout au long de l'appel de happyhorse-1.1/text-to-video via l'API unifiée HiAPI. À la fin, vous disposerez d'une requête fonctionnelle : soumettre une invite textuelle, interroger jusqu'à l'achèvement, et enregistrer la vidéo générée avec sa piste audio native. Nous présenterons d'abord la structure de la requête pour que vous compreniez la charge utile avant d'écrire le moindre code ; nous fournirons ensuite un appel curl prêt à copier ; puis nous expliquerons le modèle d'interrogation asynchrone nécessaire à la génération vidéo ; enfin, nous transposerons le tout en Python avec une gestion d'erreurs de base. Aucune expérience préalable des API vidéo n'est requise : il vous suffit d'une clé API HiAPI et d'un terminal ou d'un environnement Python. L'objectif est de fournir un exemple d'intégration minimal mais complet, que vous pourrez adapter à votre propre pipeline.
Structure de la requête pour happyhorse-1.1/text-to-video
Avant de lancer un appel, il est utile de comprendre les champs qui composent une requête text-to-video. Ce point de terminaison accepte une charge utile JSON contenant au minimum l'identifiant du modèle et votre invite textuelle. D'autres champs courants contrôlent les dimensions et la durée de la sortie, mais les noms exacts des paramètres et les valeurs acceptées doivent être vérifiés dans la documentation du modèle sur HiAPI. Une charge utile valide ressemble généralement à ceci :
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Au lever du soleil, la caméra effectue un lent travelling horizontal au-dessus d'une forêt brumeuse"
}
Gardez la charge utile à plat et n'utilisez que les champs décrits dans la documentation du modèle. Les champs non reconnus ou les types mal formatés sont la cause la plus fréquente de rejet des requêtes. En cas de doute, commencez par une charge utile minimale contenant uniquement model et prompt, puis ajoutez les paramètres optionnels un par un pour isoler le problème.
Lancer la première requête avec curl
Une fois la charge utile prête, vous pouvez soumettre la tâche avec curl. Vous envoyez une requête POST avec un corps JSON et votre clé API dans l'en-tête Authorization. La réponse contient généralement l'identifiant de la tâche, que vous utiliserez ensuite pour interroger son état. Voici un exemple fonctionnel :
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Au lever du soleil, la caméra effectue un lent travelling horizontal au-dessus d'une forêt brumeuse"
}'
Remplacez $HIAPI_API_KEY par votre clé réelle, ou exportez-la dans votre shell. La réponse sera au format JSON, contenant un champ id (ou un identifiant nommé de manière similaire) ainsi qu'un statut indiquant que la tâche a été acceptée. Lisez attentivement la réponse : si le statut n'indique pas une acceptation, vérifiez le message d'erreur avant de continuer. Ne supposez pas à ce stade que la vidéo est prête ; la tâche vient seulement d'être mise en file d'attente.
Gérer l'interrogation asynchrone
La génération vidéo n'est pas instantanée, c'est pourquoi HiAPI renvoie un identifiant de tâche dans la réponse initiale plutôt que la vidéo finale. Vous devez interroger le point de terminaison de statut jusqu'à ce que la tâche atteigne un état terminal. Le schéma général est le suivant : soumettre la tâche, récupérer l'ID, puis demander répétitivement l'état de la tâche à intervalles courts. Arrêtez-vous lorsque l'état indique un succès ou un échec. Voici la logique sous forme de pseudo-code :
- Soumettre la tâche et lire l'
idde la tâche. - Attendre quelques secondes.
- Demander l'état de la tâche avec cet
id. - Si l'état est « completed » ou « succeeded », récupérer l'URL de sortie et quitter la boucle.
- Si l'état est « failed », consigner l'erreur et quitter.
- Sinon, attendre à nouveau et répéter, jusqu'à un nombre maximal raisonnable de tentatives.
Évitez d'interroger trop fréquemment. Pour les tâches vidéo, un intervalle de quelques secondes entre chaque tentative suffit généralement. De plus, ne comptez pas sur une réponse bloquante unique contenant la vidéo finale ; le modèle asynchrone est intentionnel et reste cohérent pour toutes les tâches de génération longue durée.
Audio natif dans la sortie
Les vidéos générées par happyhorse-1.1/text-to-video intègrent nativement un audio dans leur sortie. Lorsque la tâche est terminée, la réponse pointe vers le fichier vidéo généré, lequel contient déjà la piste audio. Vous n'avez pas besoin de générer ou de récupérer l'audio séparément. Pour enregistrer et vérifier le résultat, téléchargez le fichier vidéo depuis l'URL fournie et conservez son format de conteneur. Si vous traitez le fichier par programmation, vérifiez que le flux audio est présent, par exemple à l'aide d'un outil multimédia. Sauf si votre pipeline en aval l'exige, ne retirez pas et ne réencodez pas l'audio, car cela pourrait dégrader la qualité ou supprimer complètement la piste audio. Considérez le fichier renvoyé comme un actif audiovisuel complet.
Effectuer la même requête en Python
Transposer l'appel curl en Python est direct : réutilisez la même charge utile JSON et ajoutez la boucle d'interrogation. L'exemple suivant utilise requests, attend entre chaque tentative et lève une exception en cas d'échec. Remplacez le chemin du point de terminaison et les noms des champs de statut par ceux indiqués dans la documentation de happyhorse-1.1/text-to-video sur HiAPI.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "Au lever du soleil, la caméra effectue un lent travelling horizontal au-dessus d'une forêt brumeuse",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("Vidéo prête :", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "Échec de la génération"))
time.sleep(5)
else:
raise TimeoutError("Délai d'interrogation dépassé")
Cela suit la logique « interroger jusqu'à l'achèvement » décrite précédemment. Utilisez raise_for_status() pour exposer rapidement les erreurs HTTP, et maintenez un intervalle de sommeil raisonnable pour éviter les requêtes inutiles.
Résoudre les problèmes courants
La plupart des problèmes d'intégration se rangent dans quelques catégories. Une charge utile mal formatée, par exemple un champ model manquant ou un type JSON incorrect, est immédiatement rejetée ; vérifiez attentivement votre JSON par rapport à la documentation du modèle. Une interrogation trop fréquente peut entraîner des limitations de débit ou une charge inutile ; augmentez l'intervalle de sommeil. Confondre la réponse initiale avec la vidéo finale est une autre erreur fréquente ; interrogez toujours jusqu'à un état terminal. Les erreurs d'authentification signifient généralement un en-tête Authorization manquant ou mal formaté, vérifiez donc que votre clé API est correctement exportée. Enfin, si la tâche échoue après interrogation, consultez le message d'erreur dans la réponse de statut ; il indique souvent une invite invalide ou un paramètre non pris en charge. Après avoir corrigé ces problèmes, réessayez avec une charge utile minimale valide.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage