Comment utiliser veo-3.1-lite/image-to-video via l'API hiapi

Veo 3.1 Lite transforme une seule image de référence accompagnée d'un prompt textuel en une courte vidéo, et sur hiapi, il est exposé via la même API de tâches asynchrones partagée par tous les modèles de la plateforme. Ce guide parcourt le flux de requêtes réellement utilisable : obtenir une clé, appeler POST /v1/tasks, récupérer le résultat, ainsi que les détails à surveiller lorsque vous faites passer ce flux d'un script ponctuel à un environnement de production (callbacks, idempotence, gestion des erreurs).

Ce que vous allez construire, et ce qu'il faut préparer

Vous envoyez une URL d'image et un prompt au modèle veo-3.1-lite/image-to-video, et vous récupérez une URL .mp4 hébergée en externe. Tout passe par le point de terminaison de tâches unifié de hiapi, donc la même structure de requête s'applique à tous les modèles vidéo et image de la plateforme — seuls l'id model et les champs input changent.

Avant de commencer :

1. Créez un compte hiapi et récupérez une clé API depuis la console. La clé ressemble à sk-....
2. Préparez une URL d'image accessible publiquement — l'API la récupère côté serveur, donc un chemin localhost ou un bucket privé ne fonctionnera pas.
3. Avant d'envoyer une requête réelle (non test), consultez la page de tarification pour connaître le prix actuel de veo-3.1-lite/image-to-video, car le coût dépend de la durée et de la résolution.

Il n'y a ni niveau gratuit ni mode sans clé — chaque appel nécessite Authorization: Bearer sk-<your-key>.

Exemple minimal fonctionnel

L'API de tâches de hiapi, c'est deux appels : créer une tâche, puis soit la sonder, soit laisser un callback vous indiquer quand elle est terminée. Voici la version par sondage en Python, qui n'utilise que requests et time :

import time
import requests

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

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

Si vous voulez simplement voir le format transmis sur le réseau, voici la même chose en curl brut :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

Quelques points du schéma input méritent d'être connus, car il est plus strict qu'un point de terminaison générique qui « avale tout » — les champs superflus sont purement et simplement rejetés, et non ignorés en silence :

• prompt et image_url sont les deux seuls champs obligatoires. image_url est au singulier — ce modèle n'accepte qu'exactement une image de référence, pas un tableau.
• duration n'accepte que 4, 6 ou 8 (secondes) — aucun autre entier.
• aspect_ratio accepte auto, 16:9 ou 9:16.
• resolution accepte 720p ou 1080p.
• Options supplémentaires : seed (entier, pour la reproductibilité), generate_audio (booléen), negative_prompt (chaîne).

Notez que l'id du modèle est un id brut, à savoir veo-3.1-lite/image-to-video — ne lui ajoutez ni préfixe ni espace de noms.

Une fois que status passe à "success", la vidéo de sortie se trouve dans data.output[0].url. Cette URL est temporaire (elle porte un expireAt), donc téléchargez-la ou réhébergez-la immédiatement plutôt que de conserver ce lien direct.

Considérations de production : callbacks, idempotence et erreurs

Sonder toutes les 5 secondes convient à un script, mais c'est du gaspillage sur un serveur qui traite de nombreuses tâches en parallèle. Pour le trafic de production, les callbacks sont préférables : passez un objet callback dans la même requête de création de tâche, et hiapi POSTera le résultat final vers votre point de terminaison, au lieu que vous ayez à le demander.

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

Le réglage clé ici est when: "final" — cela signifie que vous n'êtes notifié qu'une seule fois, lorsque la tâche atteint un état terminal (success ou fail), et non à chaque changement d'état intermédiaire. Votre gestionnaire de webhook doit vérifier l'id de la tâche, puis retrouver l'enregistrement local de la tâche que vous avez créé lors de votre appel initial à POST /v1/tasks.

Idempotence. Si votre service est susceptible de réessayer l'appel de création de tâche (délai d'attente, livraison au moins une fois, etc.), ajoutez un en-tête Idempotency-Key, de 255 octets maximum :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

Réessayer avec la même clé sous le même compte renvoie le taskId d'origine, au lieu de créer une seconde tâche (facturable) — vous pouvez donc lancer cela sereinement depuis une boucle de réessai sans facturer deux fois le client.

Sondage vs callback, en bref : pour un script, un notebook ou un outil interne à faible trafic, si vous attendez de toute façon le résultat en bloquant, utilisez le sondage. Pour tout scénario côté serveur et concurrent, utilisez les callbacks — cela évite de maintenir une connexion ouverte et passe à l'échelle sur un grand nombre de tâches en cours sans faire tourner une boucle de sondage pour chacune.

Gestion des erreurs. Une clé invalide ou révoquée renvoie un HTTP 401 et error.code: "permission_denied" — vérifiez ce cas spécifiquement, plutôt que de supposer que tout code non 2xx signifie un échec de la génération vidéo elle-même. Un input mal formé (prompt manquant, duration hors de l'énumération, champ non reconnu) renvoie un HTTP 400 et error_code: "INVALID_REQUEST", avec un message indiquant le champ problématique précis — cela vaut la peine de l'exposer directement dans vos propres journaux plutôt que de l'avaler, car le message vous dit exactement quoi corriger. Une fois la tâche acceptée, les échecs côté génération se manifestent par status: "fail" et un objet error dans la charge utile de sondage/callback — ne le considérez comme réessayable que si le message indique un problème transitoire en amont, et non un problème de schéma.

Ressources associées

• Documentation du modèle veo-3.1-lite/image-to-video — référence complète des paramètres de ce modèle spécifique
• Créer une tâche et Obtenir les détails d'une tâche — les deux points de terminaison sur lesquels ce guide repose
• Documentation d'authentification — format de clé et exigences d'en-tête
• Veo 3.1 Image-to-Video : guide de la courte vidéo — si vous voulez la sortie plus fidèle du modèle non lite, voici l'explication des cas d'usage
• Tarification — taux actuels par seconde selon la durée et la résolution

Questions fréquentes

Dois-je transmettre image_url sous forme de data URI ou de base64 ? Non — image_url doit être une URL HTTP(S) publique que le serveur hiapi peut récupérer. Ce modèle n'accepte pas les images encodées en base64.

Puis-je générer une vidéo sans image de référence ? Avec veo-3.1-lite/image-to-video, non — c'est un modèle image-vers-vidéo, et image_url est obligatoire. Si vous voulez une génération purement textuelle, utilisez plutôt un modèle texte-vers-vidéo ; la page du modèle Veo 3.1 non lite liste les modes disponibles.

Pourquoi ma requête renvoie-t-elle encore 400 alors que j'ai passé tous les champs obligatoires ? Vérifiez la présence de champs supplémentaires — le schéma d'entrée de ce modèle rejette tout ce qui ne figure pas dans la liste autorisée (prompt, image_url, duration, aspect_ratio, resolution, seed, generate_audio, negative_prompt). Le message d'erreur indique le champ exact qu'il ne reconnaît pas.

Combien de temps prend réellement la génération ? Cela varie selon la durée et la profondeur actuelle de la file d'attente, ce qui explique pourquoi un sondage à intervalle court ou un callback est la bonne approche, plutôt que de supposer un délai d'attente fixe.

La sortie peut-elle contenir de l'audio ? Oui, via le booléen generate_audio — consultez la documentation du modèle pour connaître la valeur par défaut actuelle et son impact sur le coût.

Que se passe-t-il si mon point de terminaison de callback est indisponible lorsque la tâche se termine ? Ne vous fiez pas uniquement à l'arrivée du callback — conservez le taskId renvoyé par l'appel de création, et si aucun callback n'arrive dans un délai raisonnable, revenez à un sondage via GET /v1/tasks/<id>.