Tutoriel
Comment générer des vidéos avec gemini-omni-flash via l'API HiAPI
Les chemins de requête de la génération vidéo à partir de texte et à partir d'image, le choix du modèle, et une liste de vérification d'intégration utilisable
Sur cette page
Pourquoi gemini-omni-flash possède deux points de terminaison vidéo
Avant d'écrire la première ligne de code, la décision la plus importante est la suivante : lequel des deux points de terminaison vidéo vous avez réellement besoin. Sur HiAPI, gemini-omni-flash est proposé sous la forme de deux modèles distincts, et non d'un seul point de terminaison doté d'un indicateur de mode :
gemini-omni-flash/text-to-video— génère une vidéo uniquement à partir d'un prompt textuel.gemini-omni-flash/image-to-video— utilise l'image source fournie comme ancrage visuel et génère une vidéo guidée par un prompt textuel.
Cette séparation existe parce que ces deux tâches ont des entrées différentes, des règles de validation différentes et des modes d'échec différents. La génération à partir de texte n'a qu'une chaîne de prompt à valider. La génération à partir d'image doit en plus récupérer et décoder votre image source, ce qui ajoute toute une catégorie d'erreurs qui n'apparaissent jamais sur le chemin textuel (URL inaccessible, format non pris en charge, ressource trop volumineuse).
Règle empirique : si vous disposez déjà d'une image statique — visuel produit, image de storyboard, photo — utilisez la génération à partir d'image, car le modèle part de votre contenu visuel au lieu de créer à partir de rien. Si vous n'avez qu'une idée, sans aucun élément de référence, utilisez la génération à partir de texte.
Distinguez ces deux identifiants de modèle dans votre base de code dès le premier jour. Les traiter comme un seul concept « vidéo » puis ajouter un indicateur if has_image plus tard est précisément ce qui finit par produire des charges utiles confuses et des bugs difficiles à comprendre.
Ce qui reste identique
Les deux points de terminaison partagent le même schéma d'authentification, la même URL de base, les mêmes conventions générales de requête/réponse et le même modèle de facturation (la vidéo est facturée sur la sortie générée, et non sur le nombre de requêtes). Ce sont ces éléments communs qui rendent viable un constructeur de requête unique — détaillé plus loin.
Ce qui diffère
Seules la structure de la charge utile et la validation des entrées diffèrent. L'écart est suffisamment faible pour vous permettre de prendre en charge les deux points de terminaison sans dupliquer toute l'intégration.
Prérequis et configuration de l'API
Avant le premier appel, il vous faut trois choses.
1. La clé API
Créez une clé dans votre compte HiAPI et stockez-la dans une variable d'environnement plutôt que de la coder en dur :
export HIAPI_API_KEY="your_key_here"
Chaque requête s'authentifie via un bearer token dans l'en-tête Authorization. Il n'y a pas d'étape de signature séparée, ni de nonce par requête.
2. L'URL de base et la convention de nommage des modèles
Tous les appels sont envoyés vers la même URL de base HiAPI, le modèle étant choisi par le champ model du corps de la requête. Les identifiants de modèle suivent le schéma family/variant, donc les modèles vidéo s'écrivent gemini-omni-flash/text-to-video et gemini-omni-flash/image-to-video. Pour changer de point de terminaison, vous ne modifiez qu'une chaîne, pas d'hôte.
3. L'outil pour émettre les requêtes
curl suffit pour vérifier la connectivité, et Python (avec requests) suffit pour construire une véritable intégration. Aucun des deux ne nécessite de SDK propriétaire — l'API n'est que du JSON ordinaire sur HTTPS.
Vérification de la connectivité
Avant de générer la moindre vidéo, appelez un point de terminaison léger (par exemple la liste des modèles disponibles) pour confirmer que la clé fonctionne et que le chemin réseau est correct. Si cette étape échoue, vous déboguez des identifiants ou la connectivité, pas la génération vidéo — savoir lequel des deux vous fait gagner beaucoup de temps.
Liste de vérification rapide :
- La clé est exportée dans le shell qui exécutera la requête.
- L'URL de base est notée et utilisée de manière cohérente partout (pas de dérive de barre oblique finale entre les scripts).
Content-Type: application/jsonest défini sur chaque POST.- Vous avez un moyen de consulter la réponse JSON brute sans la tronquer.
Émettre une requête de génération vidéo à partir de texte
Commencez par la requête la plus petite possible qui ait une chance de réussir. Ne remplissez pas d'emblée tous les paramètres optionnels — si la requête minimale échoue, vous savez que le problème est structurel ; si elle réussit, chaque paramètre ajouté ensuite est une modification isolable.
Structure minimale
Une requête de génération à partir de texte envoie l'identifiant de modèle et le prompt :
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,湿沥青上的反光,电影感"
}
C'est la charge utile complète. Envoyez-la, confirmez la réception d'un objet de réponse réussi, puis seulement enrichissez le contenu.
Faire évoluer la requête progressivement
Une fois l'appel minimal réussi, ajoutez un paramètre à la fois et revalidez après chaque ajout. Ajouts typiques sur le chemin textuel :
- Précision du prompt — sujet, mouvement, comportement de la caméra, éclairage et ambiance. Un prompt vague produit un mouvement vague ; décrivez ce qui bouge et comment la caméra se déplace.
- Durée / longueur de sortie — la vidéo est facturée sur la sortie générée, donc la longueur influence directement le coût. Fixez-la explicitement plutôt que de dépendre d'une valeur par défaut que vous n'avez pas vérifiée.
- Format d'image ou résolution (si le modèle le prend en charge), pour correspondre au lecteur en aval ou au format des réseaux sociaux.
Les points d'écriture de prompt qui comptent vraiment
La qualité de la génération à partir de texte dépend principalement de la précision du prompt. Trois bonnes habitudes :
- Décrivez le mouvement, pas seulement le contenu. « Un bateau en papier dérive le long d'une gouttière » donne au modèle quelque chose à animer ; « un bateau en papier » ne donne rien.
- Précisez la caméra. Fixe, panoramique, travelling avant, caméra à l'épaule — le langage cinématographique lève beaucoup d'ambiguïté.
- Limitez-vous à une seule scène. Décrire plusieurs plans dans un seul plan court produit souvent un résultat brouillon.
Quand le résultat de la génération à partir de texte est médiocre, modifiez d'abord le prompt avant de toucher au moindre paramètre technique.
Émettre une requête de génération vidéo à partir d'image
Le chemin image est structurellement identique au chemin textuel, avec un élément de plus : l'image source. La méthode de test « le minimum d'abord » que vous avez apprise s'applique également ici.
Structure minimale
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "轻柔的手持漂移,主体略微转向镜头,柔和的窗光",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
Ici, le prompt décrit le mouvement et le comportement de la caméra par rapport à l'image, et non le contenu de la scène — l'image fournit déjà le contenu. C'est l'erreur conceptuelle la plus fréquente : les gens écrivent une description complète de scène, puis se demandent pourquoi la sortie ignore leur image source.
Comment fournir l'image source
L'image est transmise sous forme de référence, et le service doit pouvoir la récupérer. Deux conséquences pratiques :
- La ressource doit être accessible publiquement par le service, et non se trouver derrière votre localhost, un VPN ou un bucket authentifié. Une URL signée à expiration courte convient, à condition qu'elle soit encore valide au moment de l'exécution de la requête.
- Le format et la taille doivent être pris en charge. Tenez-vous-en aux formats web courants et à des dimensions raisonnables. Un TIFF de 40 Mo, c'est un débogage qui vous attend.
Si votre image est stockée dans un stockage privé, générez une URL signée à courte durée de validité au moment de la requête, plutôt que d'essayer de rendre le bucket public.
Différences concrètes avec le chemin textuel
- Le rôle du prompt passe de décrire la scène à décrire le mouvement.
- La validation comporte une étape supplémentaire de récupération de ressource, d'où toute une nouvelle catégorie d'échecs (voir la section débogage).
- La composition de la sortie est contrainte par le format d'image de la source, ce qui influence la façon dont vous planifiez la mise en page en aval.
Testez l'URL de l'image dans un navigateur en premier. Si elle ne se charge pas proprement pour vous, elle ne se chargera pas non plus pour le service.
Appeler l'API avec curl et Python
Faites fonctionner la même requête à deux endroits : le terminal (pour l'itération rapide et la visibilité brute) et votre base de code (pour l'usage réel).
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,电影感"
}'
Remplacez la chaîne model par gemini-omni-flash/image-to-video et ajoutez le champ image pour atteindre l'autre point de terminaison — rien d'autre à changer.
Utilisez -sS pour que les erreurs ne soient pas avalées silencieusement ; lors de l'inspection de la réponse, passez-la dans un formateur JSON pour rendre les champs imbriqués lisibles.
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "夜晚雨湿的霓虹街道上缓慢推进的镜头,电影感",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
Deux détails qui valent la peine d'être repris tels quels : lisez la clé depuis une variable d'environnement et définissez un délai d'attente suffisamment large. La génération vidéo n'est pas une requête instantanée — un délai par défaut de 10 secondes produit de faux échecs qui ressemblent à des erreurs d'API alors que votre client a simplement abandonné trop tôt.
Pour la génération à partir d'image, ajoutez une ligne :
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
En cas de code de statut non 2xx, imprimez ou journalisez toujours le corps de réponse brut avant de lever une exception. Le texte d'erreur nomme généralement directement le champ problématique.
Organiser votre code d'intégration
Une fois les deux chemins opérationnels, il est tentant de laisser dans la base de code deux fonctions presque identiques. Une structure légèrement meilleure ne coûte presque rien et s'amortit dès que vous ajoutez un deuxième modèle vidéo.
Deux composants partagés
Un constructeur de requête. Une fonction qui reçoit des paramètres au niveau de l'intention et renvoie le dictionnaire de charge utile :
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
La sélection du point de terminaison devient le résultat de « ai-je une image ? », ce qui correspond à la décision produit réelle. Les appelants ne touchent jamais directement aux identifiants de modèle.
Un gestionnaire de réponse. Une fonction qui traite séparément les erreurs de transport, les erreurs de charge utile et les échecs au niveau du modèle, et renvoie un objet de résultat normalisé (statut, référence vidéo, corps de réponse brut pour les journaux). Tous les appelants passent par lui, de sorte que la sémantique des erreurs reste cohérente entre les deux points de terminaison.
Pourquoi cela vaut la peine
- Un seul endroit pour changer l'identifiant de modèle. Lorsque vous migrez vers un autre modèle vidéo, vous modifiez le constructeur, pas quinze points d'appel.
- Gestion des erreurs cohérente. Un échec de récupération d'image et un échec de validation de prompt se présentent de la même manière dans votre UI.
- Tests sans réseau. Le constructeur est une fonction pure ; vous pouvez tester unitairement la structure de la charge utile à faible coût.
- Visibilité de la facturation. Comme la vidéo est facturée sur la sortie générée, un gestionnaire unique est l'endroit naturel pour consigner la durée et la taille de sortie afin de suivre les coûts.
Gardez le constructeur léger. La logique métier concernant ce qu'il faut générer appartient à l'appelant ; le constructeur n'a besoin que de savoir exprimer cette intention sous la forme attendue par l'API.
Déboguer les échecs de requête courants
Presque tous les échecs précoces tombent dans l'une de trois catégories. Identifiez d'abord la catégorie, puis corrigez.
Catégorie 1 : structure de la requête
Symptômes : un 4xx immédiat, un message d'erreur mentionnant un champ manquant ou inconnu, ou une plainte sur un JSON mal formé.
Vérifiez dans l'ordre :
- Le JSON est-il valide ? Collez le corps de la requête dans un linter. Une virgule finale laissée par une édition manuelle de la charge utile est un classique.
- L'identifiant de modèle est-il exactement identique ?
gemini-omni-flash/text-to-videoetgemini-omni-flash-text-to-videone sont pas la même chaîne. Une faute de frappe ici produit une erreur « modèle introuvable » qui se lit comme un problème d'authentification. - Les en-têtes sont-ils complets ?
AuthorizationetContent-Type: application/jsonsont tous deux définis. - Le modèle correspond-il au point de terminaison ? Envoyer le champ
imageau point de terminaison textuel ne donnera pas le résultat escompté — le champ sera soit rejeté, soit ignoré, et dans les deux cas vous obtiendrez un mauvais résultat.
Catégorie 2 : ressource d'entrée (chemin image uniquement)
Symptômes : la requête est acceptée mais échoue pendant le traitement, ou l'erreur mentionne la récupération ou le décodage de l'image.
Vérifiez :
- Ouvrez l'URL de l'image dans une fenêtre de navigation privée sans cookies. Si elle ne se charge pas pour vous, le service ne pourra pas la charger non plus.
- Confirmez que l'URL n'est pas une adresse localhost, un hôte de réseau privé ou un lien signé expiré.
- Confirmez que le format est un format web courant et que la taille du fichier est raisonnable.
- Confirmez que la réponse est bien une image — un CDN qui renvoie un code 200 avec une page d'erreur HTML comme contenu est un piège étonnamment courant.
Catégorie 3 : l'appel au modèle lui-même
Symptômes : la requête est valide, la ressource est accessible, mais la génération échoue ou est refusée — souvent lié à la politique de contenu ou à la capacité.
Vérifiez :
- Réduisez au prompt minimal et réessayez. Si cela réussit, votre prompt est la variable.
- Vérifiez que le délai d'attente du client est suffisamment long — dans les journaux, un délai d'attente client ressemble exactement à un échec serveur, sauf si vous vérifiez si une réponse a été reçue.
- Activez la journalisation complète requête/réponse (avec les clés masquées), afin de pouvoir distinguer ces trois catégories d'un coup d'œil.
Un ordre de débogage efficace
Charge utile minimale → vérification → ajout de l'image → vérification → ajout des paramètres optionnels un par un → vérification. En cas de problème, la dernière modification effectuée est la coupable. Tant que vous vous tenez à ne déboguer qu'une variable à la fois, l'essentiel de la douleur d'intégration disparaît.
Commencez par l'appel minimal fonctionnel de chaque point de terminaison, enveloppez-le dans un constructeur et un gestionnaire partagés, puis étendez progressivement — ce chemin vous permet de garder la génération à partir de texte et à partir d'image prévisibles à mesure que l'intégration grandit.
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