Blog

Tutoriel

Comment utiliser gemini-omni-flash/text-to-video via l'API HiAPI : guide curl et Python

Nov 12, 2026
Image de couverture : des feuilles de papier beige superposées et décalées, avec une page ocre en accent, offrant un rythme stratifié sobre.
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 :

  1. Rédigez l'invite au palier le plus bas.
  2. Générez deux ou trois variantes et comparez.
  3. 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 →

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