Tutoriel
Comment utiliser gemini-omni-flash/text-to-video via l'API HiAPI : guide curl et Python
Sur cette page
Ce que fait ce point de terminaison et quand l'utiliser
gemini-omni-flash/text-to-video est un point de terminaison de génération sur HiAPI qui transforme une invite textuelle — éventuellement ancrée par une image de première image — en une courte vidéo. Vous envoyez une requête, HiAPI renvoie une tâche interrogeable, et une fois la tâche terminée vous obtenez une URL de vidéo, téléchargeable ou diffusée en streaming.
Ce point de terminaison convient aux scénarios suivants :
- Clips conceptuels rapides. Générez directement à partir d'une ou deux phrases de description de courtes bandes-annonces marketing, des aperçus de storyboard ou des transitions pour réseaux sociaux.
- Mouvement guidé par image. Vous disposez déjà d'une image fixe — photo produit, design de personnage, illustration — et souhaitez l'animer plutôt que de générer à partir de zéro.
- Génération par lots dans un pipeline. Comme la génération est asynchrone, vous pouvez soumettre un grand nombre de tâches depuis un worker backend, puis récupérer les résultats plus tard, sans maintenir la connexion de requête ouverte.
Il ne convient pas aux vidéos longues, au montage image par image précis, ni à la reproduction déterministe d'un plan précis. Voyez-le comme un brouillon génératif rapide : coût d'itération faible, suffisant pour la revue, scriptable de bout en bout.
Tout ce qui suit passe par la même interface HiAPI — une clé API, une URL de base, une structure de requête — ainsi votre code écrit ici peut migrer vers d'autres points de terminaison de génération sans réapprendre l'authentification ni le polling.
Avant d'envoyer votre première requête
Quatre éléments doivent être prêts avant le premier appel réussi.
1. Clé API
Créez une clé dans votre compte HiAPI et conservez-la dans une variable d'environnement plutôt que dans le code source :
export HIAPI_API_KEY="your_key_here"
2. URL de base et chemin du point de terminaison
Toutes les requêtes sont envoyées à l'URL de base HiAPI, l'identifiant du modèle se trouvant dans le chemin. Traitez l'URL de base comme une constante unique dans votre code, afin de ne la modifier qu'à un seul endroit :
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. Corps de requête JSON
La requête est un POST avec Content-Type: application/json et un bearer token dans l'en-tête Authorization. Sauf si vous fournissez l'image de première image via une URL, il n'y a ni encodage de formulaire ni upload multipart.
4. Image de première image (facultative)
Si vous prévoyez de guider la génération par une image, assurez-vous d'abord qu'elle est accessible via une URL HTTPS publique. Les chemins du système de fichiers local ne fonctionnent pas — l'API récupère l'image côté serveur.
Un conseil pratique pour maîtriser les coûts : ce point de terminaison facture la sortie que vous générez — le palier de résolution et la durée du clip y contribuent tous deux. Consultez le panneau tarifaire HiAPI pour le prix unitaire actuel, et vérifiez-le avant de lancer des tâches par lots à grande échelle. L'habitude importante : prototyper d'abord avec les réglages minimaux, puis augmenter les réglages une fois que l'invite produit l'effet souhaité.
Construire la requête de génération
Une requête comporte conceptuellement trois parties : le chemin du modèle, l'invite (et éventuellement l'image) et les options de génération. Voici la structure :
{
"prompt": "Un lent travelling avant sur une tasse à café en verre while la vapeur s'élève, lumière du matin, faible profondeur de champ",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
Invite
Le champ prompt porte la description du plan. Rédigez-le comme des notes de réalisateur : sujet, comportement de la caméra, lumière et ambiance. Des verbes de mouvement précis (« lent travelling avant », « la caméra panoramique à gauche », « la vapeur s'élève ») orientent le résultat de manière plus fiable qu'un simple empilement d'adjectifs.
Première image facultative
Le champ image est facultatif. Omettez-le et le modèle génère tout le clip uniquement à partir du texte. Incluez-le et le clip commence à partir de cette image, l'invite décrivant ce qui doit se produire ensuite. C'est le levier le plus important pour la cohérence : une invite purement textuelle réimagine la scène à chaque exécution, tandis qu'une première image fixe maintient la composition stable sur plusieurs itérations.
Si vous fournissez les deux, assurez-vous qu'ils concordent. Une première image de paysage désertique accompagnée d'une invite sur une rue urbaine sous la pluie produira un résultat confus — le modèle doit concilier deux instructions contradictoires.
Où placer les options
resolution, duration et audio se trouvent au niveau supérieur du même corps JSON que prompt et image. Pas besoin de mémoriser un objet options imbriqué. Gardez le corps plat et lisible — cela facilite grandement la journalisation et le diff des requêtes lors du débogage de tâches par lots.
Choisir la résolution et la durée
Deux paramètres gouvernent à la fois l'apparence de la sortie et le coût de la tâche : le palier de résolution et la durée du clip.
Paliers de résolution
HiAPI expose ce point de terminaison avec plusieurs paliers de résolution. Les paliers inférieurs sont un bon défaut pendant le développement de l'invite — rendu plus rapide, vous permettant d'itérer sur la formulation sans payer des détails que vous allez jeter. Une fois que l'invite produit de manière fiable la composition souhaitée, passez à un palier supérieur pour le rendu final.
Un flux de travail pratique :
- Rédigez l'invite au palier le plus bas.
- Générez deux ou trois variantes et comparez.
- Verrouillez l'invite, puis refaites le rendu à un palier supérieur.
Durée du clip
La durée se spécifie en secondes, et ce point de terminaison est conçu autour de clips courts. Restez modéré : un clip court rend chaque tâche plus rapide, les nouvelles tentatives en cas d'échec moins coûteuses, et si vous avez besoin plus tard d'une séquence plus longue, vous pouvez assembler plusieurs clips. Si un plan nécessite huit secondes à l'écran, deux générations de quatre secondes sont souvent plus faciles à contrôler qu'une seule longue génération.
Comment cela se traduit en budget
Ce point de terminaison facture la sortie que vous produisez — une résolution plus élevée et une durée plus longue augmentent tous deux la sortie facturable d'une tâche. Comme la tarification est calculée par unité générée et que les paliers évoluent dans le temps, lisez les chiffres en temps réel sur le panneau tarifaire HiAPI plutôt que de coder en dur des prévisions. Une règle de planification valable quelle que soit l'évolution des prix : multipliez le nombre de tâches prévues par la taille de la sortie, prototypez avec les réglages minimaux et n'augmentez la résolution qu'à la fin.
Contrôler l'audio natif
Le drapeau audio détermine si la vidéo renvoyée porte une piste audio native générée avec l'image.
{
"prompt": "De la pluie battant un toit en tôle, une porte grince et s'ouvre lentement",
"audio": true
}
Ce qui change lorsqu'il est activé
Avec audio: true, le modèle génère des sons correspondant à la scène décrite dans l'invite — sons d'ambiance, textures environnementales et événements sonores suggérés par l'action. La vidéo de sortie est accompagnée d'un flux audio, de sorte que le fichier que vous téléchargez est complet, sans traitement sonore séparé nécessaire.
Ce qui change lorsqu'il est désactivé
Avec audio: false, vous obtenez une vidéo silencieuse. Cela convient lorsque :
- Vous superposerez votre propre musique ou voix off au clip dans un éditeur.
- Le clip est un élément d'arrière-plan dans une composition plus large.
- Vous n'itérez que sur l'image et ne souhaitez pas que la génération audio entre dans la boucle.
Rédiger l'invite pour l'audio
Si vous activez l'audio, décrivez le paysage sonore comme vous décrivez l'image. Les indices sonores dans l'invite — pluie, pas, bruits mécaniques, ambiance particulière d'une pièce — donnent des repères au modèle audio. Une invite purement visuelle produira tout de même de l'audio, mais un son d'ambiance générique plutôt qu'un son correspondant au plan.
Un point à tester tôt : l'audio modifie sensiblement le caractère du clip. Générez la même invite une fois avec le drapeau activé et une fois désactivé, regardez les deux, et décidez du mode réellement nécessaire au projet avant de construire des tâches par lots autour de celui-ci.
Gérer le cycle de vie des tâches asynchrones
La génération vidéo prend plus de temps qu'une requête HTTP typique ne devrait rester ouverte, c'est pourquoi ce point de terminaison est asynchrone. Chaque appel suit la même boucle en trois étapes.
Étape 1 : soumettre
Envoyez le corps JSON en POST au point de terminaison. Une soumission réussie renvoie immédiatement un identifiant de tâche — généralement l'id de la tâche — ainsi qu'un statut indiquant que la tâche est en file d'attente ou en cours de traitement. Rien n'a encore été rendu à ce stade.
Étape 2 : interroger
Avec l'id de tâche, interrogez le point de terminaison de statut de tâche à intervalle fixe. Chaque interrogation renvoie le statut actuel : queued, processing, completed ou failed. Vous devez gérer les quatre états. Un backoff exponentiel simple — commençant vers deux secondes, avec un plafond d'intervalle — évite de marteler l'API sur les tâches longues tout en capturant rapidement les tâches courtes.
Étape 3 : récupérer
Lorsque le statut indique une complétion, la réponse porte l'URL de la vidéo terminée ainsi que les métadonnées de la tâche. Téléchargez-la, stockez-la, ou transmettez l'URL au frontend. Si le statut indique un échec, capturez le message d'erreur de la réponse et décidez s'il faut réessayer après modification de l'invite ou exposer l'échec.
Garde-fous à intégrer
- Plafond de délai d'attente. Limitez le temps total d'interrogation (par exemple quelques minutes) et marquez la tâche comme échouée dans votre propre code plutôt que de boucler indéfiniment.
- Nombre maximal d'interrogations. Empêchez les boucles incontrôlées lorsque le statut reste ambigu.
- Persistez l'id de tâche. Écrivez-le en base de données ou dans les logs dès sa réception. Si le processus plante en cours d'interrogation, vous pouvez reprendre au lieu de régénérer et payer deux fois.
- Soumission idempotente. Ne resoumettez pas à cause d'un hoquet réseau avant d'avoir confirmé que la première requête a échoué ; des tâches en double consomment de la sortie réelle.
Faites cette boucle correctement une fois, et elle s'appliquera à tous les points de terminaison asynchrones de HiAPI.
Exemples curl et Python exécutables
curl : soumettre, interroger, récupérer
Définissez la clé et l'URL de base depuis les variables d'environnement, puis soumettez :
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Un lent travelling avant sur une tasse à café en verre while la vapeur s'élève, lumière du matin, faible profondeur de champ",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
La réponse contient l'id de tâche. Récupérez le point de terminaison de statut depuis la réponse et interrogez-le :
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Répétez jusqu'à ce que le statut soit completed, puis extrayez l'URL de la vidéo du corps de la réponse et téléchargez-la :
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python : la même boucle, encapsulée
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"Un lent travelling avant sur une tasse à café en verre while la vapeur s'élève, "
"lumière du matin, faible profondeur de champ",
)
print("video ready:", url)
Ce script soumet une tâche purement textuelle, interroge avec backoff, impose un plafond de délai d'attente et renvoie l'URL de la vidéo terminée. Passez image_url= pour ancrer la génération sur une première image, ou définissez audio=True pour inclure un son natif. À partir de là, vous pouvez placer generate_video dans une file de workers, une route FastAPI ou une boucle par lots — la fonction est autonome et sans état, hormis l'id de tâche qu'elle crée.
Points d'échec courants et comment les éviter
La plupart des intégrations échouées rencontrent l'un des cinq problèmes suivants.
Rejet à la soumission pour paramètres invalides
La cause la plus courante est que l'API ne parvient pas à analyser le corps de la requête : prompt manquant, durée hors plage prise en charge, ou chaîne de résolution non prise en charge. Consultez la référence du point de terminaison pour les valeurs acceptées et validez localement d'abord. Un petit utilitaire qui vérifie les valeurs autorisées avant l'appel économise un aller-retour et une erreur déroutante.
Image de première image inaccessible
L'API récupère image côté serveur, donc une URL qui fonctionne dans un navigateur peut encore échouer — les buckets privés, les liens signés qui expirent et la protection contre le hotlinking provoquent tous ce problème. Utilisez une URL HTTPS lisible publiquement et vérifiez qu'elle se résout depuis l'extérieur de votre réseau avant de soumettre.
Abandonner l'interrogation
Deux variantes de la même erreur : abandonner dès la première réponse processing en supposant un échec, ou interroger si agressivement que vous atteignez les limites de débit. Une boucle avec backoff et plafond comme montré ci-dessus résout les deux : interrogez selon un calendrier, traitez les états non terminaux comme normaux, et ne levez d'exception qu'en cas d'échec explicite ou de dépassement de délai.
Perdre l'id de tâche
Si le processus meurt après la soumission mais avant l'enregistrement du résultat, la tâche est payée mais inaccessible. Écrivez l'id de tâche dans un stockage persistant immédiatement après la soumission, et au démarrage vérifiez s'il reste des id en cours avant de soumettre de nouvelles tâches.
Sortie trop volumineuse à grande échelle
Générer de grands lots à haute résolution et longue durée amplifie rapidement le volume de sortie, et les fichiers générés coûtent cher à stocker et sont lents à servir. Prototypez à petite échelle, faites le rendu final une fois, et maintenez des règles de cycle de vie du stockage en place. Comme la facturation est liée à la sortie générée, la correction la moins chère est presque toujours une boucle d'itération de prototype plus petite.
Parcourez cette liste en environnement de préproduction, et votre chemin vers la production sera fluide.
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