Tutoriel

Comment utiliser veo-3.1-lite/text-to-video via l'API hiapi : curl, Python et une requête exécutable

Aug 27, 2026

veo-3.1-lite/text-to-video génère un court clip vidéo à partir d'un simple prompt textuel — aucune image de départ n'est nécessaire. Ce guide fournit des exemples curl et Python prêts à copier-coller pour la véritable API de tâches hiapi, le schéma d'entrée exact (vérifié sur l'endpoint en ligne), ainsi que les formes d'erreurs que vous rencontrerez réellement en production.

1. Prérequis

Un compte hiapi et une clé API (sk-...) obtenue depuis le tableau de bord API Keys.
curl, ou Python 3 avec requests installé (pip install requests).
Rien d'autre — text-to-video n'a besoin que d'une chaîne de prompt.

Sur hiapi, chaque modèle de génération passe par la même API de tâches asynchrones unifiée : POST /v1/tasks crée une tâche, puis vous interrogez ou attendez un callback pour obtenir le résultat. veo-3.1-lite/text-to-video s'appelle exactement comme n'importe quel autre modèle vidéo — mêmes en-têtes d'authentification, même cycle de vie de tâche — seuls model et input diffèrent. L'id du modèle est veo-3.1-lite/text-to-video, avec le suffixe /text-to-video ; la même série propose également veo-3.1-lite/image-to-video, un id de modèle distinct qui anime une image source à la place.

2. Exemple minimal exécutable

2.1 Créer une tâche (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "a paper boat drifting down a rain-slicked city street at night, neon signs reflecting on wet asphalt",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

Un appel réussi renvoie immédiatement un id de tâche — la génération est asynchrone :

{"code":200,"data":{"taskId":"tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX"},"message":"success"}

2.2 Interroger le résultat

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer sk-<your-api-key>"

Pendant le rendu du clip, status vaut "handling". Une fois terminé :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX",
    "model": "veo-3.1-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {"artifactId": "...", "type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786932195}
    ]
  },
  "message": "success"
}

output[0].url est un lien temporaire et expirable — téléchargez le fichier avant l'expiration définie par expireAt (ou transférez la sortie vers un stockage persistant).

2.3 Exemple Python complet

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str) -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "veo-3.1-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": 6,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
    }, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, poll_seconds: int = 5, timeout_seconds: int = 600) -> str:
    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(poll_seconds)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_seconds}s")


if __name__ == "__main__":
    tid = create_task("a paper boat drifting down a rain-slicked city street at night")
    video_url = wait_for_result(tid)
    print(video_url)

3. Schéma d'entrée

Tous les champs ci-dessous se trouvent sous input. Le schéma est strict — envoyer un champ inexistant renvoie une erreur 400 (additional properties '<field>' not allowed), ce qui permet de valider rapidement une requête avant le rendu.

Champ	Type	Obligatoire	Description
`prompt`	string	Oui	Description de la scène ; précisez le sujet, le mouvement et le comportement de la caméra.
`duration`	integer	Non	Parmi `4`, `6`, `8` (secondes).
`resolution`	string	Non	`"720p"` ou `"1080p"`.
`aspect_ratio`	string	Non	`"16:9"` ou `"9:16"`.
`generate_audio`	boolean	Non	Inclure dans le rendu un audio d'ambiance/d'effets synchronisé.
`negative_prompt`	string	Non	Éléments de contenu que le rendu doit éviter.
`seed`	integer	Non	Valeur fixe pour reproduire la même composition/mouvement entre plusieurs tentatives.

Des durées plus longues et des résolutions plus élevées augmentent le coût de rendu — avant de monter en charge sur des lots de tâches, consultez les tarifs actuels par modèle sur la page de tarification.

4. Bonnes pratiques en production

Privilégier les callbacks au polling à grande échelle

Pour tout usage au-delà d'un script ponctuel, enregistrez un callback plutôt que d'interroger en boucle :

{
  "model": "veo-3.1-lite/text-to-video",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-app.example.com/webhooks/hiapi", "when": "final"}
}

callback.url doit être une URL http(s) accessible, et when n'accepte que "final" — hiapi effectue un unique POST lorsque la tâche atteint un état terminal (success ou failed). Cela évite de gaspiller du quota de requêtes dans une boucle de polling et permet de récupérer le résultat dès qu'il est prêt, ce qui est d'autant plus important pour la vidéo (temps de rendu plus long que pour la génération d'images).

Idempotence et nouvelles tentatives

Si votre exécuteur de tâches est susceptible de réessayer une soumission (crash, timeout, redéploiement), enregistrez votre propre clé d'idempotence avec le taskId renvoyé avant d'envoyer la requête, afin qu'une nouvelle tentative puisse vérifier « ai-je déjà soumis ceci ? » plutôt que de créer un rendu en double et de payer deux fois.

Gestion des erreurs

Deux formes d'erreurs distinctes apparaissent en pratique :

Entrée invalide (400) — erreur de validation du corps de requête :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Échec d'authentification/permission (401) — clé absente, invalide ou aux permissions insuffisantes :

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model...","request_id":"...","type":"hiapi_error"}}

Branchez d'abord sur le code de statut HTTP, puis inspectez le corps de la réponse — 400 signifie presque toujours un nom de champ ou une valeur erronés (corrigez la requête), tandis que 401 signifie que la clé elle-même doit être traitée (permissions du tableau de bord ou nouvelle clé).

5. Pages associées

Page du modèle veo-3.1-lite/text-to-video — tarifs en temps réel et playground dans le navigateur pour tester un prompt avant d'écrire le code d'intégration.
Page du modèle veo-3.1-lite/image-to-video — modèle frère conditionné par une image, pour animer une scène existante plutôt que de partir d'un texte.
Introduction à l'API asynchrone unifiée — le cycle de vie de tâche partagé par tous les modèles hiapi (image, vidéo, audio).
Documentation d'authentification — format de la clé API et détails des en-têtes de requête.
Guide de l'API seedance-2.5/text-to-video — un second modèle texte-vers-vidéo sur la même API de tâches, utile pour comparer schémas et tarifs.

Questions fréquentes

veo-3.1-lite/text-to-video nécessite-t-il une image de départ ? Non. Il génère entièrement à partir de la chaîne prompt. Si vous avez une image source à animer, utilisez plutôt l'id de modèle distinct veo-3.1-lite/image-to-video.

Quelles résolutions et durées sont prises en charge ? resolution vaut "720p" ou "1080p" ; duration vaut 4, 6 ou 8 secondes. Toute autre valeur renvoie une erreur 400 listant l'ensemble des valeurs autorisées.

Le clip généré peut-il inclure de l'audio ? Oui — définissez "generate_audio": true dans input pour inclure un audio d'ambiance/d'effets synchronisé.

Comment éviter d'interroger en boucle ? Passez un objet callback contenant l'url de votre webhook et "when": "final". Une fois la tâche terminée, hiapi envoie un POST à cette URL, sans que vous ayez à revérifier périodiquement via GET /v1/tasks/<id>.

Pourquoi ma requête renvoie-t-elle 401 au lieu de 400 ? Un 401 avec error_code/code valant "permission_denied" indique que la clé API elle-même est invalide ou n'a pas accès à ce modèle — vérifiez le tableau de bord API Keys. Un 400 indique que le corps de requête est mal formé pour une clé valide.

L'URL de la vidéo renvoyée est-elle permanente ? Non — output[0].url est un lien temporaire avec un horodatage expireAt. Téléchargez-le ou transférez-le vers un stockage persistant avant expiration.