Tutoriel
Comment appeler gemini-omni-1.1-flash via l'API HiAPI : guide curl et Python
Sur cette page
Ce qu'il faut préparer avant la première requête
Avant d'écrire la moindre ligne de code, vérifiez quatre points. Chacun vous épargnera un aller-retour de débogage.
Une clé API
Chaque requête vers HiAPI doit être authentifiée avec une clé API. Générez-en une dans la console de votre compte et assurez-vous qu'elle n'entre pas dans la gestion de versions. Les exemples ci-dessous la lisent depuis une variable d'environnement, afin que la clé n'apparaisse ni dans l'historique du shell ni dans les fichiers commités :
export HIAPI_API_KEY="your_key_here"
L'URL de base et le chemin de l'endpoint
L'URL de base est identique pour tous les modèles HiAPI ; seul l'identifiant du modèle change. Récupérez le chemin de l'endpoint et la méthode HTTP depuis la documentation de référence de l'API, et non depuis un article de blog, car les chemins sont versionnés et peuvent évoluer. Définissez l'URL de base comme une constante dans votre client, ainsi une future modification ne nécessitera qu'une seule ligne à changer.
L'identifiant du modèle
gemini-omni-1.1-flash est transmis sous forme de chaîne dans le corps de la requête. Copiez-le exactement — les traits d'union et le suffixe de version comptent. En cas de faute de frappe, l'erreur est généralement un échec de validation plutôt qu'un échec de routage, ce qui peut dérouter ; consultez la section de débogage plus bas.
Mettez la page du modèle en favori
La page du modèle gemini-omni-1.1-flash est la source de référence pour savoir quels paramètres existent, quelles valeurs sont acceptées et quelle est la structure de la réponse. Considérez-la comme une référence à vérifier avant chaque modification, et non comme un document à lire une seule fois.
Une fois ces quatre points prêts, vous pouvez lancer l'appel.
Envoyer une requête minimale avec curl
Commencez par la requête la plus petite possible. Son but n'est pas de produire un bon résultat — mais de prouver que votre clé, votre endpoint et la structure de votre corps de requête concordent. Une fois qu'elle fonctionne, chaque modification ultérieure est incrémentale.
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Un léger travelling avant vers une tasse en céramique sur une table en bois, douce lumière du matin"
}
}'
Voici ce que signifie chaque partie :
- Méthode et URL — l'appel est un
POSTvers le chemin de l'endpoint obtenu depuis la documentation de référence de l'API, préfixé par votre URL de base. - En-tête
Authorization— porte le jeton bearer. Une variable absente ou vide ici est la cause la plus fréquente des 401. - En-tête
Content-Type— doit valoirapplication/json. Sans lui, le serveur peut ne pas analyser le corps de la requête du tout. model— la chaîne exacte de l'identifiant du modèle.input— un objet contenant les paramètres de génération. Le prompt s'y trouve ; la résolution et la durée s'y ajoutent également, comme détaillé plus bas.
Si l'appel renvoie un identifiant de tâche ou une réponse d'état accepté plutôt que la sortie finale, c'est normal — la génération est asynchrone. Conservez cet identifiant ; il sera utilisé à l'étape d'interrogation.
Porter le même appel en Python
La version Python doit envoyer exactement le même corps JSON. Garder le corps identique rend ce portage fiable : si curl réussit et que Python échoue, le problème vient de votre code Python, et non de votre compréhension de l'API.
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Un léger travelling avant vers une tasse en céramique sur une table en bois, douce lumière du matin"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
Quelques habitudes à adopter immédiatement :
- Construisez l'URL à partir de constantes, au lieu de disperser des concaténations de chaînes dans tout le code.
- Définissez un timeout explicite. Sans cela, une requête bloquée peut suspendre indéfiniment un processus de travail.
- Appelez
raise_for_status(), afin que les réponses d'erreur se manifestent sous forme d'exceptions plutôt que d'être silencieusement analysées comme des corps de réponse réussis. - Sérialisez avec
json.dumps, sans vous fier à l'encodage de formulaire, qui ne peut pas produire correctement l'objetinputimbriqué.
Une fois que cela fonctionne, vous disposez d'une structure de requête réutilisable. Les deux sections suivantes ajoutent les paramètres qui contrôlent réellement la sortie.
Configurer la résolution et la durée dans la requête
La résolution et la durée sont des champs ordinaires de l'objet input, au même niveau que le prompt. Conceptuellement, le corps de requête ressemble à ceci :
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
Règle essentielle : ne codez pas ces valeurs en dur de mémoire ou d'après un tutoriel lu il y a plusieurs mois. Les valeurs prises en charge évoluent avec les mises à jour du modèle, et transmettre une valeur non prise en charge produit des erreurs de validation qui ressemblent à des erreurs de corps de requête. Avant de les définir, vérifiez toujours les valeurs actuellement acceptées sur la page du modèle.
Un schéma utile
Placez les valeurs dans la configuration, et non dans le code :
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
Cela apporte trois avantages. Vous pouvez ajuster la qualité de sortie sans modifier la logique. Vous pouvez lancer des tests à basse résolution peu coûteux pendant le développement et n'augmenter la qualité qu'au rendu final. Lorsque la plateforme ajoute une valeur prise en charge, vous ne changez qu'un seul champ de configuration au lieu de parcourir toute la base de code.
Deux pièges plus subtils méritent d'être signalés. Premièrement, la résolution et la durée sont généralement liées au coût — la facturation dépend souvent de la sortie produite, donc des clips plus longs et en plus haute résolution ne sont pas gratuits. Deuxièmement, si un champ est facultatif, omettez-le plutôt que d'envoyer une chaîne vide ou null ; certains validateurs rejettent un null explicite même lorsque le champ lui-même est facultatif.
Gérer la génération asynchrone : soumettre, puis interroger
La génération prend du temps, l'API adopte donc un schéma soumettre puis interroger. Votre client doit les traiter comme deux opérations distinctes avec des sémantiques de nouvelle tentative différentes.
Étape 1 : soumettre
L'appel de soumission est la requête que vous avez déjà construite. Il renvoie l'identifiant de la tâche — selon l'endpoint, il peut s'agir de l'ID de tâche, de task ID ou d'un champ similaire. Analysez-le de manière défensive :
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
Étape 2 : interroger
Interrogez ensuite l'endpoint de statut avec cet identifiant, jusqu'à ce que la tâche atteigne un état terminal. Une boucle robuste comporte quatre caractéristiques : un temps d'attente maximal, un backoff, une vérification d'état terminal et une vérification d'échec.
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
Pourquoi ces détails comptent
- Le backoff exponentiel évite de marteler l'endpoint de statut pour une tâche qui nécessite une minute de rendu et reste encore en file d'attente.
- Une échéance stricte empêche une tâche bloquée de bloquer indéfiniment un processus de travail. En cas de timeout, journalisez l'ID de la tâche pour pouvoir l'inspecter manuellement.
- Des états terminaux explicites signifient que vous ne bouclerez jamais à l'infini sur un état imprévu. Traitez un état inconnu comme « continuer d'attendre », mais journalisez-le une fois.
- Des stratégies de nouvelle tentative séparées : réessayer l'appel de soumission est plus risqué que réessayer un appel de statut, car cela peut créer des tâches en double. Vous pouvez réessayer l'interrogation sans crainte ; ne réessayez la soumission qu'en cas d'erreur de transport explicite.
Diagnostiquer les modes de défaillance courants
La plupart des défaillances se rangent dans quelques catégories. Diagnostiquez dans cet ordre, car les symptômes ultérieurs sont souvent causés par les problèmes précédents.
Erreurs d'authentification
Symptôme : 401 ou 403.
À vérifier d'abord : la clé existe-t-elle réellement dans l'environnement où le processus s'exécute ? Afficher len(API_KEY) permet de repérer le cas classique d'une variable non définie qui rend le jeton bearer vide. Vérifiez ensuite que le format de l'en-tête est Bearer <key>, avec un seul espace, et que la clé n'a pas été révoquée ni restreinte à un autre projet.
Corps de requête mal formé
Symptôme : 400, avec une plainte concernant le corps de la requête ou un champ manquant.
À vérifier d'abord : comparez votre corps de requête à la requête curl qui fonctionne. Les causes fréquentes incluent l'absence de l'en-tête Content-Type: application/json, l'envoi de données encodées en formulaire au lieu de JSON, un objet input à plat alors que l'API attend de l'imbrication (ou l'inverse), et des conversions de types involontaires — une durée numérique envoyée sous forme de chaîne entre guillemets peut échouer à la validation.
Valeurs de paramètres non prises en charge
Symptôme : 400 ou 422, désignant un champ précis comme resolution ou duration.
À vérifier d'abord : la page du modèle, qui liste les valeurs actuellement prises en charge. Il s'agit presque toujours d'une valeur codée en dur devenue obsolète, et non d'un bug du code. Si une valeur qui fonctionnait auparavant échoue désormais, supposez d'abord que le modèle a été mis à jour et relisez la documentation, avant de supposer une panne du service.
Faute de frappe dans l'identifiant du modèle
Symptôme : une erreur de validation ou « introuvable », sans mention de votre prompt.
À vérifier d'abord : affichez la chaîne model et comparez-la caractère par caractère avec la documentation. Un espace superflu en fin de chaîne ou un numéro de version inversé se repèrent facilement.
Timeouts et défaillances transitoires
Symptôme : timeout de connexion, réponses 429 ou 5xx. À vérifier d'abord : avez-vous défini un timeout ? Ajoutez-en un, puis n'ajoutez des nouvelles tentatives bornées avec backoff que pour les 429 et les 5xx — ne réessayez pas les erreurs 4xx autres que 429, car la requête échouera de la même manière à chaque fois. Pour les tâches longues, rappelez-vous que le résultat final s'obtient par interrogation ; un timeout sur l'appel de soumission ne signifie pas que la génération a échoué.
Techniquement valide mais résultat incorrect
La requête réussit mais la sortie n'est pas celle attendue. C'est un problème de prompt, pas un problème d'API. Rendez le prompt explicite sur le sujet, le mouvement de caméra, l'éclairage et le rythme, et ne modifiez qu'une variable à la fois pour pouvoir attribuer les différences.
Envelopper le tout dans une fonction client réutilisable
L'objectif de l'encapsulation est simple : votre logique métier ne doit contenir ni identifiant de modèle, ni nom de paramètre, ni boucle d'interrogation. Tous les détails liés au modèle sont regroupés en un seul endroit.
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
Ce que cela vous apporte
- Changer de modèle ne demande qu'une ligne. Lorsqu'un modèle plus récent arrive, vous modifiez la constante et les paramètres par défaut ; les points d'appel ne sont pas affectés.
- Les paramètres facultatifs sont gérés correctement. Les valeurs omises ne sont pas envoyées, ce qui évite le problème de rejet des null décrit plus haut.
- L'interrogation est invisible pour l'appelant. L'appelant obtient soit un résultat, soit une exception, jamais un ID de tâche qu'il doit gérer lui-même.
- Les tests deviennent faciles. Vous pouvez mocker séparément
post_jsonetwait_for_jobpour tester isolément la construction du corps de requête et la logique d'interrogation.
Organisation en couches
Gardez une structure plate et explicite : la couche de transport (HTTP, en-têtes, timeouts, nouvelles tentatives), la couche modèle (construction du corps de requête pour gemini-omni-1.1-flash) et la couche tâche (soumission et interrogation). Une seule fonction generate_video les combine, et chaque couche est suffisamment petite pour être raisonnée facilement en cas de problème.
Validez d'abord la configuration de connexion avec curl, passez ensuite à Python pour le travail réel, consultez la page du modèle dès que les paramètres changent, et placez la boucle d'interrogation derrière une interface afin qu'elle ne fuite jamais dans le code applicatif.
Articles similaires
Voir tous les articles →-
Tutoriel
kling-image-4.0 en pratique : 5 cas d'usage à forte valeur et points d'intégration
-
Tutoriel
Comment utiliser qwen-image-2.0-pro via l'API HiAPI : curl, Python et une requête fonctionnelle
Exercice d'intégration pratique pour développeurs : premier appel réussi, anatomie de la requête et dépannage
-
Tutoriel
Comment appeler l'API veo-3.1 text-to-video : exemples curl et Python
Guide d'intégration pratique pour les développeurs