Tutoriel
Comment utiliser pixverse-v6-max/text-to-video via l'API HiAPI : curl, Python et exemples de requêtes exécutables
Sur cette page
Ce que fait ce point de terminaison et quand l'utiliser
pixverse-v6-max/text-to-video est un point de terminaison de génération de vidéo à partir de texte sur HiAPI. Vous envoyez un prompt texte décrivant la scène souhaitée, et le point de terminaison renvoie une vidéo rendue. Comme la génération vidéo prend du temps, ce point de terminaison est asynchrone : la requête initiale ne renvoie pas directement la vidéo, mais un identifiant de tâche que vous utilisez pour suivre la progression et récupérer le résultat final.
Ce schéma « requête—accusé de réception—interrogation » (polling) est le modèle mental central de tout ce tutoriel. Le déroulement interne est toujours le même :
- Soumettre une tâche de génération avec le prompt et les paramètres.
- Recevoir immédiatement un identifiant de tâche.
- Interroger cette tâche jusqu'à ce qu'elle signale son achèvement (ou son échec).
- Télécharger ou intégrer l'URL de la vidéo résultante.
Quand ce point de terminaison est adapté
Choisissez pixverse-v6-max/text-to-video lorsque vous n'avez qu'une description et aucune source : par exemple, réaliser une bande-annonce produit à partir d'un brief textuel, générer un clip d'arrière-plan pour une application, créer un aperçu de storyboard. Si vous disposez déjà d'une image et souhaitez l'animer, il s'agit d'un workflow image-vers-vidéo, pas de ce point de terminaison. Si vous souhaitez que le modèle itère sur le prompt de manière conversationnelle, c'est un autre mode d'interaction. Ce point de terminaison est la voie directe et unique de génération texte-vers-vidéo.
Comme la génération est asynchrone, il convient aussi aux architectures basées sur des files d'attente : un backend Web reçoit la demande de l'utilisateur, soumet la tâche, puis un processus worker interroge et livre le résultat plus tard. Aucune étape de l'appel ne bloque jusqu'à la fin du rendu complet.
Avant de commencer : authentification et bases de requête
Avant d'écrire du code, vérifiez trois choses.
1. Une clé API
Chaque requête HiAPI nécessite une authentification par clé API. Traitez-la comme un mot de passe : ne la committez pas dans un dépôt de code source, chargez-la depuis une variable d'environnement et révoquez-la immédiatement en cas de fuite. Les exemples ci-dessous la lisent depuis HIAPI_API_KEY, donc exportez-la d'abord dans votre shell :
export HIAPI_API_KEY="your_key_here"
2. L'URL de base correcte
Toutes les requêtes sont envoyées à l'URL de base de l'API HiAPI, avec le chemin du point de terminaison ajouté. Utilisez l'URL de base indiquée dans votre compte HiAPI plutôt que de coder en dur un nom d'hôte trouvé dans un article de blog — en cas de doute, consultez la référence API du tableau de bord. Les exemples ci-dessous utilisent $HIAPI_BASE_URL comme espace réservé pour cette valeur.
3. Conventions JSON
La soumission et l'interrogation de statut reposent toutes deux sur du JSON via HTTPS :
- Envoyez
Content-Type: application/jsonpour chaque requête avec un corps. - Envoyez
Authorization: Bearer $HIAPI_API_KEYpour chaque requête (y compris les interrogations de statut). - Attendez-vous à du JSON en retour, y compris en cas d'erreur — lisez le corps de la réponse d'erreur, pas seulement le code de statut HTTP.
Vérification rapide de bon fonctionnement
Si vous disposez d'un point de terminaison léger utilisable (par exemple une route models ou account), appelez-le une fois avant de toucher au point de terminaison vidéo. Un retour 200 ici prouve que votre clé, votre URL de base et la forme de vos en-têtes sont corrects, ce qui élimine trois variables lors du débogage ultérieur.
Une requête curl exécutable
Voici l'appel de soumission complet. Le chemin du point de terminaison est pixverse-v6-max/text-to-video ; le corps de la requête porte votre prompt et vos paramètres de génération.
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Nuit, une ruelle néon détrempée par la pluie, travelling avant lent, rendu cinématographique",
"duration": 5,
"aspect_ratio": "16:9"
}'
Explication champ par champ
prompt— la description textuelle. Soyez explicite sur le sujet, le mouvement, le mouvement de caméra et l'ambiance. C'est le levier le plus important pour la qualité du résultat.duration— la durée du clip demandée. Voir la section sur la durée et le rapport d'image ci-dessous.aspect_ratio— le rapport d'image de sortie, par exemple16:9,9:16,1:1.
Ce qui est renvoyé
Une soumission réussie renvoie un objet JSON contenant un identifiant de tâche — le handle utilisé pour l'interrogation. Consultez la référence API pour le nom exact du champ ; dans ce tutoriel, nous l'appelons task_id. Conservez-le :
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Nuit, une ruelle néon détrempée par la pluie, travelling avant lent, rendu cinématographique","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
Notez ce que la réponse ne contient pas : la vidéo. La génération s'exécute en arrière-plan. Traitez la réponse de soumission comme un accusé de réception, pas comme un résultat.
La version Python de la même requête
La version Python correspond exactement à l'appel curl. Pour la concision, nous utilisons requests, mais httpx ou urllib fonctionnent tout aussi bien — la seule exigence est les mêmes en-têtes et le même corps JSON.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"prompt": "Nuit, une ruelle néon détrempée par la pluie, travelling avant lent, rendu cinématographique",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# Afficher le corps de la réponse d'erreur du serveur — il indique généralement le champ en cause
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
Points à retenir
json=payloadsérialise automatiquement le corps et définit le type de contenu. Si vous utilisez plutôtdata=json.dumps(payload), conservez l'en-tête expliciteContent-Type.- Définir un timeout client lors de la soumission empêche la connexion de rester suspendue. Cela ne limite pas le temps de génération — la génération a lieu côté serveur, ce qui explique justement la nécessité du polling.
- Vérifiez le code de statut avant d'analyser. Les corps de réponse 4xx fournissent souvent plus d'informations que le code de statut lui-même ; affichez-le.
- Ne journalisez jamais la clé API. Journalisez plutôt le
task_id— il peut être stocké sans risque et c'est votre handle de débogage.
Paramètres de durée et de rapport d'image
Ces deux champs sont la source la plus fréquente de rejets de requête, ils méritent donc une attention particulière.
duration
duration définit la longueur du clip demandée, en secondes. Les valeurs demandables sont limitées par la plage prise en charge par le point de terminaison ; envoyer une valeur hors de cette plage produit généralement une erreur de validation de paramètre plutôt qu'une troncature silencieuse du clip. Choisissez parmi les valeurs prises en charge documentées dans la référence API et conservez un entier. Plus le clip est long, plus le rendu prend de temps, donc pendant le développement, privilégiez la durée la plus courte prise en charge — ce que vous validez, c'est la chaîne de traitement, pas l'art cinématographique.
aspect_ratio
aspect_ratio est une chaîne de la forme W:H. Faites-la correspondre à l'endroit où la vidéo sera finalement affichée :
16:9— paysage : héros de site web, lecteurs de style YouTube, arrière-plans de bureau.9:16— portrait : fils de contenus courts mobiles et stories.1:1— carré : mises en page en grille et vignettes.
Se tromper de forme ici est peu coûteux à corriger, mais très coûteux si on s'en aperçoit trop tard : un nouveau rendu consomme un cycle de génération complet, alors déterminez le contexte d'affichage cible avant de soumettre.
Que vérifier en cas de rejet
- Incohérence de type —
durationécrit sous forme de chaîne ("5") au lieu d'un nombre, ouaspect_ratioécrit sous forme de deux nombres. Gardez duration numérique et aspect ratio sous forme de chaîne. - Valeur non prise en charge — durée ou ratio hors de la plage documentée. Comparez élément par élément avec la liste de référence.
- Nommage des champs — des fautes de frappe comme
aspectRatiooudurationSecondssont, au mieux, traitées silencieusement comme champs inconnus. Copiez les noms de champs depuis la documentation de référence.
Méthode rapide pour localiser le champ fautif : soumettez d'abord avec uniquement prompt, puis rajoutez les paramètres un par un. Le premier rejet pointe vers le champ en cause.
Interroger la tâche asynchrone jusqu'à ce que la vidéo soit prête
Le polling est une boucle qui suit trois règles : vérifier le statut, dormir, s'arrêter sur un état terminal. Ajoutez-y une limite supérieure pour éviter qu'une tâche bloquée ne tourne indéfiniment à vide.
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # voir la référence API pour la route de statut
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # backoff modéré, avec plafond
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
Pourquoi le backoff est important
Interroger à intervalle fixe d'une seconde une tâche de génération qui prend une minute gaspille des dizaines de requêtes. Commencez par un petit intervalle et augmentez progressivement — le multiplicateur plafonné ci-dessus se stabilise à un intervalle confortable sans marteler l'API. Si vous exécutez de nombreuses tâches, une file d'attente avec un seul processus worker de polling est plus respectueuse qu'une boucle par requête.
Traiter le résultat
Une fois la tâche réussie, la réponse porte l'URL de la vidéo. Récupérez-la rapidement et, si le résultat doit être conservé, copiez-le dans votre propre stockage — les URL signées ne sont pas éternelles. Avant de livrer le fichier à l'utilisateur, vérifiez le type de contenu et la taille lors du téléchargement, et enregistrez le task_id avec l'actif stocké, afin que tout problème futur puisse être retracé jusqu'à l'enregistrement de génération exact.
Résoudre les erreurs courantes
En cas d'échec d'appel, parcourez cette liste point par point. La plupart des échecs relèvent de l'une des quatre catégories suivantes.
Authentification et accès
- 401 / unauthorized — clé absente, mal formée ou non envoyée. Vérifiez que l'en-tête est exactement
Authorization: Bearer <key>et que la variable d'environnement est bien définie dans le shell ou le processus qui effectue l'appel. - 403 / forbidden — la clé est valide, mais l'accès à ce point de terminaison n'est pas autorisé. Vérifiez la portée des permissions de cette clé dans le tableau de bord.
Validation de la requête
- 400 / 422 — JSON mal formé ou valeur de champ incorrecte. Affichez le corps complet de la réponse d'erreur ; il indique généralement le champ. Revérifiez le type de
durationet le format de chaîne deaspect_ratio. - 404 à la soumission — chemin de point de terminaison incorrect. Vérifiez que le chemin est exactement
pixverse-v6-max/text-to-videoet que votre URL de base n'a pas de segment de chemin dupliqué ou manquant.
Échecs au niveau de la tâche
- Statut
failed— la tâche a été acceptée mais la génération a échoué. Lisez le message d'erreur de la tâche ; il permet de distinguer un refus de contenu d'une panne interne. Un prompt rejeté est un problème de prompt, pas un problème d'API — modifiez-le et soumettez à nouveau. - Blocage à l'état en cours d'exécution — fixez une échéance au polling et traitez le timeout comme un échec à gérer, pas comme une exception qui fait planter le service.
Problèmes d'exploitation
- 429 / limitation de débit déclenchée — trop de soumissions ou de pollings en cours. Réduisez la concurrence et respectez les éventuelles consignes de réessai de la réponse.
- Timeout de connexion à la soumission — problème réseau ou de proxy, pas de génération. Réessayez la soumission avec backoff, mais seulement si vous pouvez tolérer la création éventuelle de tâches en double.
- 404 sur l'URL de la vidéo au téléchargement — l'URL a expiré. Récupérez à nouveau le résultat de la tâche au lieu de réutiliser l'ancienne URL.
Une habitude reproductible
Pour chaque échec, notez trois valeurs : le code de statut HTTP, le corps de la réponse et (s'il existe) le task_id. Ces trois éléments transforment « ça ne marche pas » en « ça ne marche pas ici », et c'est la seule clé pour accélérer le débogage.
Et ensuite
Vous maîtrisez maintenant la boucle complète : authentification, soumission, obtention de l'identifiant de tâche, polling avec backoff, et récupération du résultat. Pour passer en production, encapsulez la soumission et le polling dans une petite classe cliente, stockez le task_id et le prompt avec chaque actif pour la traçabilité, et déplacez le polling vers un processus worker en arrière-plan afin que les requêtes destinées à l'utilisateur ne soient jamais bloquées par le rendu.
Ensuite, explorez les points de terminaison voisins dans la documentation de référence HiAPI — l'animation image-vers-vidéo pour animer des images fixes existantes, et le mode d'interaction itératif sur le prompt pour affiner le style visuel avant de lancer une génération complète. La forme des requêtes apprise ici s'y transpose presque telle quelle.
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