Blog

Tutoriel

Comment utiliser pixverse-v6-max/text-to-video via l'API HiAPI : curl, Python et exemples de requêtes exécutables

Nov 13, 2026
Illustration de couverture plate d'un motif de panier tressé épais aux teintes espresso, avoine et laiton, formant une grille rappelant un métier à tisser.
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 :

  1. Soumettre une tâche de génération avec le prompt et les paramètres.
  2. Recevoir immédiatement un identifiant de tâche.
  3. Interroger cette tâche jusqu'à ce qu'elle signale son achèvement (ou son échec).
  4. 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/json pour chaque requête avec un corps.
  • Envoyez Authorization: Bearer $HIAPI_API_KEY pour 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 exemple 16: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=payload sérialise automatiquement le corps et définit le type de contenu. Si vous utilisez plutôt data=json.dumps(payload), conservez l'en-tête explicite Content-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, ou aspect_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 aspectRatio ou durationSeconds sont, 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 duration et le format de chaîne de aspect_ratio.
  • 404 à la soumission — chemin de point de terminaison incorrect. Vérifiez que le chemin est exactement pixverse-v6-max/text-to-video et 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 →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API