Tutoriel
Comment utiliser pixverse-v6-max image-to-video via l'API HiAPI : curl, Python et une requête qui fonctionne
Sur cette page
Ce qu'exige le point de terminaison pixverse-v6-max image-to-video
Le point de terminaison pixverse-v6-max/image-to-video sur HiAPI est une tâche de génération vidéo asynchrone conditionnée par une image. Cette seule phrase détermine presque toutes les décisions que vous prendrez lors de son intégration.
Le point de terminaison reçoit une image source (la première frame) ainsi qu'un ensemble de paramètres de génération, et renvoie une référence de tâche, et non la vidéo finale. Le rendu réel s'effectue côté serveur et peut prendre de quelques secondes à plusieurs minutes selon les paramètres choisis. Votre client est chargé de soumettre la tâche, puis d'interroger son état jusqu'à ce qu'elle rapporte un état terminal.
Comparez cela à l'édition d'image synchrone : dans l'édition synchrone, vous POST un corps de requête et récupérez l'image transformée dans la même réponse HTTP. Ici, le flux est :
POSTde votre image et de vos paramètres vers le point de terminaison de génération.- Réception d'un identifiant de tâche (généralement accompagné de son état initial).
GETde l'état de la tâche à intervalles réguliers, jusqu'à ce qu'elle soit terminée ou échouée.- Lecture de l'URL de la vidéo générée dans le corps de réponse de la tâche terminée.
En raison de cette séparation, il existe deux catégories d'erreurs distinctes : les problèmes à l'étape de soumission (erreurs d'authentification, corps de requête mal formé, image rejetée) et les problèmes à l'étape d'exécution (tâche acceptée mais échouée ou bloquée). Une bonne intégration traite explicitement les deux catégories — voir la liste de vérification détaillée dans la section de dépannage plus bas.
Un autre point à garder en tête : l'image source est l'ancrage. Le modèle anime à partir de cette première frame, donc la qualité, le ratio d'aspect et le contenu de l'image ont plus d'impact sur la sortie que n'importe quel texte de prompt que vous fournissez. Traitez la validité de l'upload comme une préoccupation de premier plan, et non comme une réflexion après coup.
Préparer votre clé API et le point de terminaison
Avant d'envoyer votre première requête, vous n'avez besoin que de deux choses : une clé API HiAPI et l'URL de base correcte du point de terminaison.
Obtenir votre clé
Créez une clé API dans la console de votre compte HiAPI. Traitez-la comme un mot de passe : placez-la dans une variable d'environnement, pas dans le code source ni dans l'historique du shell.
export HIAPI_API_KEY="your_key_here"
Si vous utilisez un fichier .env en local, ajoutez-le à .gitignore avant de committer quoi que ce soit. Toute clé qui apparaît dans des logs partagés, des captures d'écran ou un dépôt de code doit être immédiatement renouvelée.
Connaître votre URL de base et le chemin
Le point de terminaison se trouve sous l'hôte de l'API HiAPI, avec le chemin de modèle pixverse-v6-max/image-to-video. Dans les exemples ci-dessous, l'URL de base est indiquée comme https://api.hiapi.ai, et le chemin complet est construit à partir de celle-ci. Si votre compte ou votre région vous attribue un hôte différent, remplacez-le de manière cohérente — une inadéquation entre l'hôte et la clé est l'une des causes les plus fréquentes de 401, que les développeurs prennent souvent à tort pour une « clé invalide ».
Choisir vos outils
- curl pour une première validation rapide — cela élimine toutes les variables extérieures à la requête elle-même.
- Python 3 avec
requests(ouhttpx) pour l'intégration réelle.
python3 -c "import requests; print(requests.__version__)"
S'il affiche un numéro de version, vous êtes prêt. Les exemples de cet article ne nécessitent aucune installation de SDK ; tout est en HTTP pur, ce qui signifie aussi que vous pourrez les porter dans n'importe quel langage par la suite. Une fois la clé et l'hôte confirmés, vous pouvez commencer à construire la requête.
Construire la requête avec curl
Commencez par la plus petite requête qui réussit réellement, puis ajoutez des paramètres. Le corps de requête ci-dessous montre la structure d'une soumission image-to-video complète.
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-cdn.example.com/first-frame.jpg",
"duration": 5,
"aspect_ratio": "16:9"
}'
Trois choses se produisent ici :
- L'authentification se fait via le jeton bearer porté dans l'en-tête
Authorization. - Le corps est en JSON, donc l'image est fournie sous forme de chaîne URL (voir la section suivante pour passer un fichier local à la place).
- Deux paramètres de génération —
durationetaspect_ratio— sont des champs de niveau supérieur.
Une soumission réussie renvoie un objet JSON contenant un identifiant de tâche. Capturez-le :
JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"
Puis interrogez-le :
curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
En cas d'échec, vérifiez toujours le champ de statut et le corps de réponse d'erreur brut. curl peut afficher du JSON d'erreur avec un code de sortie 0, donc dans un script, ne vous fiez pas uniquement au code de sortie.
Fournir correctement l'image de première frame
L'image source est le point de défaillance le plus courant ; presque chaque rejet se ramène à l'une des quatre causes suivantes.
1. Image inaccessible
Lorsque vous passez une URL, les serveurs de HiAPI doivent pouvoir la GET — depuis leur réseau, pas le vôtre. Une URL localhost, un bucket privé, une URL signée expirant après soixante secondes ou un point de terminaison derrière un VPN échoueront tous. Utilisez une URL de stockage d'objets lisible publiquement ou un lien CDN, et confirmez qu'elle se charge dans une nouvelle session de navigateur sans cookies.
2. Format d'image non pris en charge
Tenez-vous en aux formats web standard — JPEG, PNG, WebP. Les fichiers à extension inhabituelle, le HEIC capturé par téléphone ou les GIF animés sont risqués. Si votre pipeline produit un format exotique, transcodez-le d'abord.
3. La première frame ne correspond pas au ratio d'aspect déclaré
C'est subtil. Si votre image source est carrée mais que vous demandez 16:9, le service devra recadrer, ajouter des bandes noires ou rejeter l'entrée. Le comportement peut varier, et aucun des trois n'est ce que la plupart des développeurs souhaitent. Recadrez ou ajoutez vous-même des bandes noires avant l'upload, afin que la géométrie de l'image corresponde déjà au aspect_ratio que vous allez demander. Cela rend la sortie prévisible et évite de gaspiller une tâche.
4. Image trop grande ou trop petite
Les images fixes à très haute résolution (par exemple, une sortie d'appareil photo 8K) consomment de la bande passante et peuvent être rejetées ou sous-échantillonnées ; les miniatures minuscules laissent au modèle presque rien à animer. Normalisez l'image vers une dimension de grand côté raisonnable dans le cadre de votre étape de pré-upload.
Passer un fichier local
Si le point de terminaison accepte les uploads multipart pour le champ image, le schéma est le suivant :
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-F "image=@./first-frame.jpg" \
-F "duration=5" \
-F "aspect_ratio=16:9"
Notez qu'avec multipart, les champs numériques deviennent des chaînes. Consultez la référence du point de terminaison pour savoir quels types de contenu sont acceptés, et privilégiez la forme URL dans un pipeline de production — cela permet de garder les gros fichiers binaires complètement hors de votre serveur applicatif.
Définir la durée et le ratio d'aspect
Ces deux champs ont le plus d'impact sur le coût et la sortie de tout le corps de requête.
duration
duration est en secondes et représente la longueur du clip généré. C'est aussi le champ le plus directement lié à la facturation — la tarification à la seconde est calculée en fonction de la durée de sortie demandée, donc choisissez-la avec soin plutôt que de prendre le maximum par défaut. Conseils pratiques :
- Commencez par la durée la plus courte qui raconte votre histoire. Un clip de 5 secondes est parfait pour une boucle, un teaser produit ou un hook social.
- N'utilisez des durées plus longues que si la prise de vue nécessite réellement plus de temps ; une première frame statique animée longtemps aura tendance à dériver et à perdre sa cohérence.
- Validez côté client : rejetez les valeurs non entières, nulles, négatives ou absurdement grandes avant que la requête ne quitte votre service.
if not isinstance(duration, int) or not 1 <= duration <= 8:
raise ValueError("duration out of supported range")
Vérifiez la plage actuellement prise en charge dans la référence du point de terminaison et reproduisez-la dans votre logique de validation — ne codez pas en dur les hypothèses de cet article.
aspect_ratio
aspect_ratio est une chaîne, par exemple "16:9", "9:16" ou "1:1". Il contrôle la géométrie de l'image de sortie.
16:9pour le paysage : YouTube, vidéo héros web, lecture sur ordinateur.9:16pour le portrait : Reels, Shorts, campagnes de style TikTok.1:1pour les flux et les miniatures.
Deux règles vous éviteront des ennuis. Premièrement, faites correspondre l'image source au ratio demandé — une première frame portrait dans une requête paysage entraînera un recadrage que vous ne souhaitiez probablement pas. Deuxièmement, traitez le ratio comme une énumération, pas comme du texte libre : validez-le contre une liste blanche, afin qu'une faute de frappe comme "16x9" échoue rapidement dans votre code plutôt qu'après un aller-retour.
Tout le reste
Si le point de terminaison expose des contrôles de génération supplémentaires, excluez-les de votre première requête. Un corps de requête minimal et validé est votre base de référence ; ajoutez un paramètre à la fois et comparez les sorties. Cette discipline rend évident quel champ a causé une régression.
Implémenter la même requête en Python
Voici la traduction du flux curl en Python. Il reste délibérément léger en dépendances : requests plus la bibliothèque standard.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
resp = requests.post(
f"{BASE}/v1/pixverse-v6-max/image-to-video",
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def fetch(job_id: str) -> dict:
resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job_id = submit("https://your-cdn.example.com/first-frame.jpg")
print("submitted", job_id)
Quelques choix délibérés à retenir :
- Appeler
raise_for_status()lors de la soumission. Un400ou401doit apparaître immédiatement sous forme d'exception, et non se transformer enKeyErrorlorsque vous tentez de lire["id"]dans le corps de réponse d'erreur. - Des délais d'attente explicites. Sans délai d'attente, une connexion bloquée suspendra votre worker indéfiniment.
- Une configuration lue depuis l'environnement. L'URL de base et la clé ne sont jamais codées en dur dans le code.
- De petites fonctions auxiliaires typées.
submitrenvoie la chaîne d'identifiant de tâche ;fetchrenvoie un dictionnaire. Centraliser l'analyse signifie qu'un changement de schéma ne nécessite qu'une seule ligne modifiée.
Si vous préférez httpx, remplacez par httpx.post(...) et httpx.get(...) ; les appels sont identiques par ailleurs. Pour tout ce qui s'exécute dans un gestionnaire de requête web, soumettez ici, puis confiez l'identifiant de tâche à un worker en arrière-plan, plutôt que de laisser la requête HTTP de l'utilisateur bloquer sur la génération vidéo.
Interroger la tâche asynchrone jusqu'à son achèvement
L'interrogation est la partie que la plupart des tutoriels survolent et la source de la plupart des incidents. La boucle elle-même est courte ; la discipline qui l'entoure est ce qui compte.
def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
job = fetch(job_id)
status = job.get("status")
if status == "completed":
return job["output"]["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish within {timeout}s")
Points clés encodés ci-dessus :
- Définissez toujours une échéance. La génération vidéo est lente ; une boucle non bornée devient une facture non bornée et un worker bloqué. Dix minutes est une limite raisonnable pour les clips courts — ajustez-la selon votre réglage de durée.
- Distinguez les états terminaux. Seul
completedproduit une URL.failedetcancelledsont aussi des états terminaux — arrêtez l'interrogation et exposez le champ error. - Utilisez un intervalle raisonnable. Quelques secondes suffisent. Marteler le point de terminaison de statut vous fera limiter le débit et ne vous apprendra rien de nouveau.
- Un backoff doux pour les tâches longues : passez l'intervalle de 3 à 10 secondes après la première minute. Cela réduit la charge sans ajouter de coût de latence.
- Persistez l'identifiant de tâche. Stockez-le avec vos propres enregistrements, afin qu'en cas de redémarrage du processus, vous puissiez reprendre l'interrogation sans resoumettre — et repayer — la même tâche.
- N'interrogez jamais directement depuis le navigateur avec votre clé API. Faites passer les vérifications de statut par votre backend.
Lorsqu'une tâche est terminée, téléchargez la vidéo dans votre propre stockage en temps voulu, plutôt que de faire un lien permanent vers l'URL renvoyée ; les URL d'actifs générés ne sont pas garanties permanentes.
Diagnostiquer les échecs et les tâches bloquées
Suivez cette liste de vérification dans l'ordre. Chaque étape isole une couche.
Erreurs de soumission (tâche jamais créée)
401 Unauthorized— clé absente, mal formée, révoquée, ou associée au mauvais hôte. Vérifiez que l'en-tête est exactementAuthorization: Bearer <key>, avec un seul espace, et qu'aucun saut de ligne superflu ne traîne dans la variable d'environnement.403 Forbidden— la clé est valide mais n'est pas autorisée pour ce modèle ou ce point de terminaison. Vérifiez le chemin de ressource caractère par caractère :pixverse-v6-max/image-to-video.400 Bad Request— votre JSON est mal formé ou un champ est invalide. Décodez le corps de réponse d'erreur ; il indique généralement le champ problématique. Coupables courants :durationen chaîne plutôt qu'en nombre,"16x9"plutôt que"16:9",imagemanquant.- Erreurs de validation de type
422— le champ existe mais est hors plage. Consultez la référence du point de terminaison plutôt que de deviner. 429 Too Many Requests— vous soumettez trop vite. Mettez les soumissions en file d'attente et réessayez avec un backoff exponentiel et du jitter ; ne réessayez jamais dans une boucle serrée.
Échecs d'exécution (tâche créée mais non réussie)
- Statut
failedavec une erreur liée à l'image — la récupération de l'URL source a échoué après la soumission. C'est le piège classique du « ça marche dans mon navigateur » : l'URL exige un cookie, un referrer ou une liste blanche d'IP. Réhébergez l'image publiquement. - Statut
failedavec une erreur de contenu ou de validation — l'image source est rejetée pour des raisons techniques (format, géométrie, taille). Transcodez, redimensionnez et recadrez à nouveau selon le ratio d'aspect déclaré. - Tâche bloquée en file d'attente ou en traitement après votre échéance — vérifiez d'abord que vous lisez le bon identifiant de tâche (les erreurs de copier-coller sont étonnamment courantes). Vérifiez ensuite si le statut est réellement inchangé, ou si vos interrogations frappent la mauvaise URL de base. Si elle est vraiment bloquée, annulez et resoumettez une fois si l'API le permet ; les resoumissions silencieuses répétées sont exactement la façon dont le budget disparaît.
Une habitude qui fait gagner du temps
Journalisez l'identifiant de requête complet, l'identifiant de tâche, le statut HTTP et le corps de réponse pour chaque appel — en masquant la clé. Quand un problème survient à deux heures du matin, un identifiant de requête fait la différence entre une correction en cinq minutes et une heure de conjectures. Commencez par le corps de requête minimal et validé, ajoutez un paramètre à la fois, et vous n'aurez presque jamais besoin de cette liste de vérification.
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