Comment utiliser gemini-omni-1.2-flash via l'API HiAPI : curl et Python

À quoi ressemble une requête gemini-omni-1.2-flash

Avant d'écrire la première ligne de code, il est utile de comprendre ce qui compose réellement un appel à gemini-omni-1.2-flash sur HiAPI. Chaque requête que vous envoyez est un objet JSON, livré à un point de terminaison unique et authentifié avec votre clé API HiAPI. Cette structure reste cohérente d'un modèle à l'autre, ce qui signifie qu'une fois que vous la maîtrisez pour ce modèle, vous pouvez réutiliser le même schéma ailleurs.

À un niveau élevé, une requête contient quatre types d'informations :

• L'identifiant du modèle — la chaîne gemini-omni-1.2-flash, qui indique à HiAPI vers quel modèle router votre tâche.
• L'entrée — le contenu que vous souhaitez que le modèle traite. Selon la modalité visée, elle se présente sous forme de prompt ou de champs d'entrée structurés.
• Les paramètres de génération — les options qui façonnent la sortie, comme la durée et la résolution. Ce sont les réglages que vous ajusterez plus loin dans ce guide.
• Les métadonnées de requête — toute information dont la plateforme a besoin pour identifier et suivre votre tâche, par exemple une référence côté client utilisable pour la corrélation.

Structure de la réponse

La réponse est tout aussi prévisible. Les appels synchrones renvoient directement le résultat dans un champ de résultat. Les appels asynchrones renvoient un handle de tâche — un identifiant servant à interroger l'état et, à terme, à récupérer la sortie. Savoir dès le départ auquel de ces deux cas vous avez affaire vous épargnera beaucoup de temps de débogage.

Pourquoi la structure compte

La plupart des échecs d'intégration initiale proviennent de la structure de la requête : champs manquants, types de paramètres incorrects, ou l'hypothèse erronée qu'un appel est synchrone alors qu'il ne l'est pas. Si vous intériorisez cette anatomie avant d'écrire du code, les exemples curl et Python qui suivent ne sont qu'une traduction directe, et non des incantations mystérieuses.

Une habitude utile : conservez le corps JSON exact que vous envoyez dans une variable ou un fichier. En cas d'erreur, vous voulez voir ce qui a réellement été envoyé, pas le reconstruire de mémoire.

L'authentification en une ligne

Chaque requête porte votre clé API dans l'en-tête d'autorisation. Traitez la clé comme un secret : chargez-la depuis une variable d'environnement plutôt que de la coder en dur, et ne la validez jamais dans le contrôle de version. Cette seule discipline évite l'erreur de sécurité la plus courante des intégrations d'API.

Envoyer votre première requête fonctionnelle avec curl

Le moyen le plus rapide de vérifier que la clé, le point de terminaison et la structure de requête sont corrects est un appel curl. Il élimine toutes les couches d'abstraction entre vous et l'API, donc si cela fonctionne, vous savez que le problème (s'il y en a un) vient de votre code, et non de la configuration de votre environnement.

Étape 1 : enregistrer votre clé

Placez votre clé API HiAPI dans une variable d'environnement, afin qu'elle n'apparaisse pas dans l'historique de votre shell ou dans des scripts partagés :

export HIAPI_API_KEY="your_key_here"

Étape 2 : construire le corps de la requête

Écrivez le corps JSON dans un fichier. Cela garde la commande curl lisible et vous donne un artefact réutilisable :

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "Décrivez le contenu que vous souhaitez que le modèle génère."
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

Les valeurs de paramètres concrètes dépendent de votre cas d'usage ; ce qui compte ici, c'est la structure. Pour le premier appel, gardez duration et resolution modérés, afin d'obtenir rapidement et à faible coût un signal que le pipeline fonctionne.

Étape 3 : l'envoyer

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Étape 4 : lire la réponse

Si la requête est synchrone, vous verrez le résultat généré dans le corps de la réponse. Si elle est asynchrone, vous recevrez un handle de tâche — un identifiant de tâche accompagné d'un champ d'état. Notez cet identifiant ; vous en aurez besoin pour le polling.

Si votre terminal le permet, passez la sortie dans un formateur JSON, ou enregistrez-la dans un fichier pour l'examiner attentivement :

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

Étape 5 : confirmer avant de passer à l'échelle

Tant que cet appel brut ne réussit pas et que vous ne comprenez pas la sortie, ne commencez pas à ajuster la durée, la résolution ou le traitement par lots. La première requête réussie est votre référence ; tout le reste n'est que des changements incrémentiels auxquels la comparer.

Porter l'appel vers Python

Une fois que curl fonctionne, le portage vers Python est mécanique. L'objectif est d'écrire un petit client lisible qui reproduit exactement la requête, de sorte que si l'appel Python échoue, vous puissiez le comparer champ par champ avec la version curl.

Un client minimal

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "Décrivez le contenu que vous souhaitez que le modèle génère."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

Points d'attention

• json=payload sérialise le dictionnaire pour vous, ce qui explique pourquoi le corps correspond au fichier curl plutôt qu'à une chaîne assemblée à la main.
• raise_for_status() transforme les réponses non-2xx en exceptions, de sorte que les échecs apparaissent immédiatement au lieu de renvoyer silencieusement un corps d'erreur que vous tenteriez ensuite de parser comme un résultat.
• timeout=60 empêche le script de rester suspendu indéfiniment si la connexion stagne. Choisissez une valeur en fonction du temps que vous estimez nécessaire à la génération.

Gérer les deux structures de réponse

Comme un appel peut renvoyer soit un résultat, soit un handle de tâche, branchez sur la réponse au lieu de présumer d'une seule structure :

if "job_id" in data:
    print("Tâche asynchrone démarrée :", data["job_id"])
else:
    print("Résultat prêt")

Cette petite vérification fait la différence entre un client qui fonctionne dans les deux modes et un client qui plante dès que la plateforme décide que votre tâche doit s'exécuter en asynchrone.

Placez-le dans une fonction

Enveloppez l'appel dans une fonction prenant en paramètres le prompt, la durée et la résolution. Ainsi, lorsque vous commencerez à ajuster, exécuter le même code avec des paramètres différents devient trivial, et la structure de requête n'est définie qu'à un seul endroit.

Tâches asynchrones et polling des résultats

Certaines requêtes gemini-omni-1.2-flash se terminent assez vite pour renvoyer le résultat en ligne. D'autres prennent plus de temps, et HiAPI renvoie alors un handle de tâche. Votre intégration doit gérer les deux cas, et c'est sur le chemin asynchrone que la plupart des clients fragiles s'effondrent.

Identifier une réponse asynchrone

Une réponse asynchrone contient un identifiant de tâche et un état. Au lieu d'une sortie terminée, vous obtenez une promesse : le travail a été accepté et sera traité. Votre rôle est de revenir vérifier.

Bien faire le polling

L'approche naïve — marteler le point de terminaison d'état dans une boucle serrée while True — a deux inconvénients : elle gaspille votre budget de limite de débit et impose une charge inutile à la plateforme, sans vous obtenir le résultat plus vite.

Un meilleur schéma utilise un intervalle avec repli plafonné :

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

Trois règles pour le polling

• Commencez petit, augmentez lentement. Un intervalle initial court capture les tâches rapides à faible coût ; doubler jusqu'au plafond évite d'interroger trop fréquemment les tâches lentes.
• Fixez toujours un temps d'attente maximal. Sans cela, une tâche bloquée suspendra votre processus indéfiniment. Un délai d'attente qui lève une exception est bien préférable à une suspension silencieuse.
• Distinguez succès, échec et en attente. Seuls deux de ces états doivent arrêter la boucle, et un seul doit renvoyer un résultat.

Privilégiez les webhooks lorsqu'ils sont disponibles

Si votre charge est élevée, le polling de chaque tâche ne passe pas à l'échelle. Là où HiAPI propose des callbacks d'achèvement, utilisez-les pour recevoir le résultat au lieu de demander sans cesse. Pour les outils interactifs et les scripts à faible volume, un polling avec repli suffit amplement.

Dans tous les cas, traitez le handle de tâche comme l'identifiant durable du travail. Stockez-le, journalisez-le et utilisez-le pour réconcilier les résultats plus tard.

Choisir la durée et la résolution

La durée et la résolution sont les deux paramètres qui affectent le plus directement votre sortie — et aussi votre facture et votre temps d'attente. Aucun des deux n'a de valeur unique correcte ; le bon choix dépend de ce que vous construisez. L'important est de les choisir délibérément, plutôt que de copier des chiffres depuis un exemple.

La durée

La durée contrôle la longueur d'exécution de la sortie générée. Une durée plus longue vous donne plus de contenu, mais nécessite plus de calcul pour la génération, ce qui affecte à la fois la latence et la façon dont la requête est facturée (la facturation est basée sur la durée de sortie). Quelques conseils pratiques :

• Commencez court pour les tests. Une durée brève prouve que le pipeline fonctionne de bout en bout, sans perdre de temps à chaque itération.
• Faites correspondre la durée à l'usage. Un court extrait pour un aperçu ou une vignette n'a pas besoin de la longueur d'un livrable complet.
• N'allongez pas par spéculation. Générez la longueur que vous allez réellement utiliser ; découper après coup ne vous apporte rien.

La résolution

La résolution contrôle la fidélité de la sortie. Une résolution plus élevée signifie plus de détails et une charge plus lourde, avec une augmentation correspondante du temps de traitement et du coût. Les compromis à peser :

• Aperçus et travaux préparatoires n'ont pas besoin d'une haute résolution — c'est une vérification de justesse, pas le produit final.
• Les livrables finaux peuvent justifier un réglage plus élevé, surtout si la sortie est présentée en taille réelle.
• Bande passante et stockage comptent aussi : les sorties haute résolution sont plus lourdes à transférer et à conserver.

Ne modifiez qu'une variable à la fois

Lorsque vous ajustez des paramètres, ne changez qu'un seul élément à la fois et comparez avec votre appel curl de référence. Changer simultanément la durée et la résolution ne permet pas d'attribuer la variation de qualité, de latence ou de coût à l'un ou l'autre. Tenez une petite matrice consignant les réglages testés et le comportement observé.

Raisonner sur le coût comme une formule, pas un chiffre

Comme la tarification se trouve dans le panneau de tarification du site, considérez le coût comme une fonction : le coût total évolue avec la durée de sortie et, pour les résolutions plus élevées, avec la taille de sortie finale et le volume de traitement. Votre travail consiste à savoir quels paramètres pilotent cette fonction, puis à consulter la tarification actuelle avant de vous engager sur un volume de production. Ainsi, vos estimations restent correctes même si les prix changent.

Erreurs courantes et comment les corriger

La plupart des échecs d'intégration initiale se rangent dans quelques catégories. Vérifiez-les dans cet ordre — chaque étape dépend de l'exactitude de la précédente, donc sauter des étapes vous fera courir après des symptômes superficiels.

1. Structure de la requête

Symptôme : erreur de validation, ou message concernant un champ manquant ou inattendu.

Correction : vérifiez que le corps est un JSON valide (les virgules finales sont le coupable classique), vérifiez que le champ model vaut exactement gemini-omni-1.2-flash, et comparez ligne par ligne votre payload avec l'exemple curl qui fonctionne. Si curl fonctionne et pas Python, comparez les deux corps de requête.

2. Paramètres

Symptôme : erreur désignant duration ou resolution, ou taille de sortie inattendue.

Correction : vérifiez les types (un nombre là où un nombre est attendu, une chaîne là où une chaîne est attendue) et vérifiez que les valeurs sont dans les plages acceptées. Si un paramètre est silencieusement ignoré, vérifiez qu'il est imbriqué là où l'API l'attend, et non au niveau supérieur.

3. Authentification

Symptôme : réponse 401 ou 403.

Correction : vérifiez que la clé figure dans l'en-tête Authorization avec le préfixe Bearer, que la variable d'environnement contient bien une valeur (une chaîne vide ressemble beaucoup à une mauvaise clé), et que vous n'avez pas copié d'espaces ou de guillemets environnants dans la clé. Si vous soupçonnez une fuite de clé, régénérez-la.

4. État de la tâche

Symptôme : vous faites du polling mais ne voyez jamais de succès, ou vous traitez une tâche en attente comme un échec.

Correction : vérifiez que vous interrogez le bon identifiant de tâche, que la boucle reconnaît tous les états (pending, running, succeeded, failed) et que le temps d'attente maximal est suffisamment long pour une tâche réaliste. Journalisez chaque transition d'état pour voir où elle se bloque.

5. Limites de débit et défaillances transitoires

Symptôme : réponses 429 ou erreurs 5xx intermittentes.

Correction : réessayez avec un repli et du jitter, plutôt qu'immédiatement. Si vous interrogez de nombreuses tâches, réduisez la concurrence. Les erreurs transitoires sont normales ; un client qui réessaie intelligemment les surmonte.

Une discipline de débogage

Quand quelque chose échoue, ne changez qu'un seul élément à la fois et relancez la plus petite requête possible. Conservez le corps de réponse brut — les messages d'erreur désignent généralement le champ ou la condition exacte, et les lire attentivement fait gagner plus de temps que n'importe quelle conjecture.

Liste de vérification pour une intégration en production

Un script qui a fonctionné une fois sur votre ordinateur portable n'est pas une intégration. Avant la mise en production, comblez ces lacunes.

Réessais avec repli

Enveloppez les appels réseau dans une politique de réessai capable de gérer les défaillances transitoires — délais d'attente, réinitialisations de connexion, réponses 429 et 5xx. Utilisez un repli exponentiel avec jitter, limitez le nombre de tentatives, et ne réessayez jamais une requête qui a échoué à la validation ; réessayer un corps malformé ne fera qu'échouer plus lentement à nouveau.

Des délais d'attente partout

Définissez un délai d'attente explicite pour chaque appel HTTP. Distinguez le délai de connexion du délai de lecture, et assurez-vous que le délai d'attente des requêtes de génération est au moins aussi long que le temps de génération réel — mais avec un plafond.

Idempotence autour des tâches

Une secousse réseau peut se produire entre le moment où le serveur a accepté votre requête et celui où vous voyez la réponse. Si vous réessayez aveuglément, vous pouvez créer des tâches en double. Attachez une référence générée côté client à chaque requête logique, afin de pouvoir détecter et réutiliser une tâche existante plutôt que d'en créer une nouvelle, et stockez le handle de tâche dans un stockage persistant en le clé par cette référence.

Des journaux qui répondent aux questions

Journalisez pour chaque requête le nom du modèle, les valeurs des paramètres (durée, résolution), le handle de tâche, les transitions d'état et la latence. Ne journalisez jamais les clés API ni le contenu complet des prompts susceptibles de contenir des données sensibles. Quand un problème survient à 3 h du matin, ces journaux sont précisément ce qui vous permet de reconstituer exactement ce qui s'est passé.

Observabilité et alertes

Suivez les taux de réussite des requêtes et du cycle de vie des tâches, la répartition des erreurs par type et la latence de bout en bout. Alertez sur un taux d'erreur soutenu, pas sur un échec isolé. Un tableau de bord qui sépare les erreurs de validation des erreurs transitoires vous dit immédiatement si vous avez un bug ou si le réseau est en mauvaise posture.

Hygiène de configuration

Placez le point de terminaison, les noms de modèles et les paramètres par défaut dans la configuration, plutôt que de les disperser dans le code. Chargez la clé API depuis un gestionnaire de secrets ou une variable d'environnement. Si la tarification et les limites sont pertinentes pour votre planification, consultez le panneau de tarification au lieu de coder en dur des chiffres, car ceux-ci changent.

Une fois cette liste parcourue, votre intégration de gemini-omni-1.2-flash saura gérer le trafic réel, pas seulement le premier test. Commencez par un appel curl fonctionnel, portez-le vers Python, puis construisez à partir de là.