HiAPI
Blog

Tutoriel

Comment appeler l'API veo-3.1 text-to-video : exemples curl et Python

Guide d'intégration pratique pour les développeurs

Nov 17, 2026
Illustration de couverture en coupe transversale de minéral à facettes plates, dans des tons pétrole profond, sarcelle et malachite, pour le tutoriel sur l'API de synthèse vidéo veo-3.1.
Sur cette page

Ce que veo-3.1/text-to-video peut faire pour vous

veo-3.1/text-to-video est un modèle de génération vidéo à partir de texte exposé via l'API unifiée de HiAPI. Vous envoyez une invite textuelle, choisissez quelques options de sortie, et vous recevez la vidéo générée. Il se trouve sur HiAPI aux côtés d'autres endpoints de génération, donc si vous utilisez déjà les capacités d'image ou de chat sur cette plateforme, cette méthode d'intégration vous semblera familière : une requête HTTP authentifiée renvoie une tâche, que vous interrogez jusqu'à son achèvement.

Cet endpoint est le bon choix lorsque vous disposez d'une description textuelle d'une scène et souhaitez générer une courte vidéo sans gérer vous-même l'infrastructure. Vous n'avez pas à vous occuper de l'allocation GPU, des poids du modèle ni de la file d'attente. Le prix à payer est que la génération est asynchrone : vous soumettez une tâche, puis revenez plus tard consulter le résultat. C'est la norme pour la vidéo, car le rendu prend plus de temps qu'un simple cycle requête/réponse.

Utilisez le text-to-video lorsque l'entrée principale est une invite. Si vous avez ensuite besoin d'une génération conditionnée par une image ou une vidéo, consultez les endpoints correspondants dans le catalogue de modèles. La structure des requêtes ici (authentification, soumission de tâche, interrogation) est le même schéma que vous réutiliserez dans les endpoints média de HiAPI, donc l'apprendre une fois vous servira durablement. Vous trouverez les détails complets du modèle sur la page du modèle veo-3.1/text-to-video.

Endpoint, authentification et structure de la requête

Toutes les requêtes HiAPI utilisent HTTPS et un bearer token. Stockez votre clé API dans une variable d'environnement plutôt que de la coder en dur, et envoyez-la dans l'en-tête Authorization :

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Une requête text-to-video est un objet JSON contenant un champ model et un objet input. L'objet input contient l'invite ainsi que les éventuels contrôles de sortie. Une requête minimale se présente ainsi :

{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "Une ruelle néon détrempée par la pluie, la nuit, travelling avant lent"
  }
}

Ce qui est renvoyé n'est pas la vidéo finale, mais une enveloppe de tâche. Elle contient généralement un identifiant de tâche, un champ de statut et un horodatage. Sa structure ressemble à ceci :

{
  "id": "job_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

Référez-vous à la réponse réelle pour les noms exacts des champs, mais la structure est cohérente : vous avez besoin de id pour interroger, et status vous indique si la tâche est en file d'attente, en cours d'exécution ou terminée. Ne pensez pas que la tâche est terminée parce que l'appel de soumission a renvoyé 200 — cela signifie seulement que la tâche a été acceptée.

Choisir les paramètres : audio natif et paliers de résolution

Outre l'invite, les paramètres les plus importants pour le text-to-video sont la génération ou non d'audio natif, et le palier de résolution cible. Les deux influencent le temps de génération et la nature de la sortie, alors faites un choix réfléchi plutôt que d'utiliser les valeurs par défaut à l'aveugle.

Audio natif

Certains modèles vidéo peuvent générer une piste audio en plus de l'image. Si cet endpoint propose un commutateur d'audio natif, l'activer signifie que le clip généré contient un son synchronisé. C'est utile pour les scènes où l'audio fait partie intégrante de l'expérience — bruit ambiant, musique ou effets sonores correspondant à l'action. Si vous prévoyez d'ajouter votre propre bande-son ou une voix off en post-production, désactivez-le pour que la sortie se concentre sur l'image. La génération audio augmente aussi le temps de traitement, donc ne l'activez que si vous en avez vraiment besoin.

Paliers de résolution

Les paliers de résolution vous permettent d'arbitrer entre fidélité d'image, coût et latence. Les paliers plus élevés produisent une sortie plus nette, mais prennent plus de temps et consomment plus de ressources. Choisissez le palier le plus bas qui satisfait votre objectif de livraison : un palier brouillon pour l'itération et la relecture, un palier plus élevé pour le rendu final. Si vous générez de nombreux candidats pour une même invite, explorez avec un palier plus bas, puis régénérez le gagnant en pleine qualité. La facturation suit la sortie que vous générez, donc le choix conscient du palier est votre principal levier de contrôle.

Si vous ne savez pas quelles valeurs l'endpoint accepte actuellement, envoyez d'abord une requête avec seulement l'invite, puis examinez la réponse ou le message d'erreur. HiAPI renvoie des erreurs de validation structurées listant les champs acceptables, ce qui vous permet d'ajuster sans deviner.

Requête curl exécutable

Cette commande curl soumet une tâche text-to-video. Elle définit le type de contenu JSON, transmet le bearer token depuis une variable d'environnement et envoie le corps de requête contenant model et input.

curl -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/text-to-video",
    "input": {
      "prompt": "Une ruelle néon détrempée par la pluie, la nuit, travelling avant lent",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Un appel réussi renvoie un objet JSON contenant l'id et le status de la tâche. Notez cet id — vous en aurez besoin pour interroger. Si vous écrivez un script, vous pouvez extraire l'id en traitant la sortie avec un processeur JSON :

JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Une ruelle néon détrempée par la pluie, la nuit, travelling avant lent"}}' \
  | jq -r '.id')
echo "$JOB_ID"

Adaptez le chemin de l'endpoint, les noms de paramètres et tout champ facultatif selon ce que l'API réelle attend. Ce schéma — POST d'un corps de requête JSON, lecture de l'id dans la réponse — est la base de chaque exemple suivant.

Envoyer la même requête en Python

La version Python fait la même chose avec la bibliothèque standard requests. Lisez la clé depuis l'environnement, construisez le payload, puis soumettez.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "veo-3.1/text-to-video",
    "input": {
        "prompt": "Une ruelle néon détrempée par la pluie, la nuit, travelling avant lent",
    },
}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()

job = response.json()
job_id = job["id"]
print(f"Tâche soumise : {job_id} (statut : {job.get('status')})")

Deux points méritent d'être soulignés. Premièrement, response.raise_for_status() convertit les erreurs HTTP en exceptions, rendant les échecs immédiatement visibles plutôt que de laisser un payload défectueux circuler silencieusement. Deuxièmement, timeout=60 évite qu'une connexion suspendue bloque votre script. La soumission elle-même est rapide ; la vidéo réelle est rendue de manière asynchrone, donc vous n'attendez pas le fichier ici. Ensuite, vous utiliserez job_id pour interroger l'état d'avancement.

Interroger une tâche asynchrone jusqu'à ce que la vidéo soit prête

Après la soumission, interrogez l'endpoint de la tâche jusqu'à ce que le statut indique un succès ou un échec. Une simple boucle avec une courte pause suffit pour commencer.

import time

while True:
    res = requests.get(
        f"{BASE_URL}/videos/generations/{job_id}",
        headers=headers,
        timeout=30,
    )
    res.raise_for_status()
    state = res.json().get("status")
    print(f"Statut : {state}")

    if state == "succeeded":
        video_url = res.json().get("output", {}).get("url")
        print(f"Vidéo prête : {video_url}")
        break
    if state == "failed":
        raise RuntimeError(f"Tâche échouée : {res.json()}")

    time.sleep(5)

Quelques améliorations utiles : commencez par un intervalle court, puis appliquez un backoff progressif pour réduire les requêtes inutiles ; ajoutez un nombre maximal de tentatives ou une échéance pour éviter qu'une tâche bloquée ne boucle indéfiniment ; et traitez avec prudence tout statut inattendu plutôt que de supposer qu'il signifie « continuez d'attendre ». Les valeurs de statut courantes incluent queued, running, succeeded et failed. Lorsqu'une tâche réussit, la réponse porte généralement une URL de sortie ; téléchargez et enregistrez le fichier rapidement, car les URL signées peuvent expirer.

Rendez l'interrogation idempotente et journalisez l'id de tâche à chaque statut. Si votre processus redémarre, vous pouvez reprendre par id sans resoumettre. En production, si la plateforme propose des webhooks, envisagez de les utiliser, avec l'interrogation comme solution de repli.

Diagnostiquer les erreurs courantes

La plupart des échecs se répartissent en quelques catégories. Parcourez la liste ci-dessous dans l'ordre plutôt que de réessayer à l'aveugle.

Échec d'authentification (401/403)

Vérifiez que l'en-tête Authorization est présent et correctement formaté en Bearer <key>, et que la variable d'environnement est bien définie dans le shell ou le processus qui émet la requête. Un piège courant consiste à exécuter un script dans un environnement où la clé existe dans un shell mais pas dans un autre.

Erreurs de validation (400/422)

Ces erreurs renvoient des détails structurés indiquant quel champ pose problème. Causes fréquentes : prompt manquant, valeur de resolution ou duration non prise en charge, ou paramètres imbriqués au mauvais niveau. Prenez le message d'erreur au pied de la lettre — il indique généralement le champ fautif. Envoyez d'abord un payload minimal, puis ajoutez un paramètre à la fois.

Limitation de débit (429)

Vous envoyez des requêtes trop vite. Mettez en place un backoff exponentiel et une limite de tentatives. Si vous lancez de nombreuses tâches, étalez les soumissions et suivez les tâches en cours.

Délais d'attente et erreurs réseau

Un délai d'attente côté client lors de la soumission est rarement un problème de la tâche elle-même — la tâche s'exécute côté serveur. Utilisez des délais raisonnables sur les requêtes de soumission et d'interrogation, et réessayez les requêtes GET idempotentes. Ne réessayez jamais un POST à l'aveugle sans vérifier si la tâche d'origine a déjà été créée.

Une tâche qui ne se termine jamais

Si une tâche reste en queued ou running bien plus longtemps que prévu, vérifiez le code de statut et le message plutôt que de resoumettre. Les invites longues ou les paliers de résolution plus élevés prennent plus de temps ; c'est normal. Si la tâche signale failed, enregistrez le corps complet de la réponse — le message d'erreur indique généralement la cause.

En cas de doute, reproduisez avec la plus petite requête possible et examinez chaque réponse. C'est bien préférable à modifier plusieurs paramètres à la fois puis à deviner lequel compte. Pour les détails propres à l'endpoint, consultez la page du modèle.

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