Utiliser un relais API pour les images Gemini

Un relais API d’images Gemini est une passerelle entre votre application et un modèle d’images Gemini. Il faut un identifiant de modèle capable de produire des images, le format de requête du relais et un moyen de récupérer le fichier. Modifier l’URL de base d’un client texte ne suffit pas à vérifier la génération d’images.

Le parcours documenté d’OmniaKey est créer une tâche → consulter son état → télécharger le résultat, à partir de POST /v1/media/tasks. Ce guide détaille ce parcours et les différences avec l’API native de Google et les interfaces compatibles OpenAI.

Quel type de relais choisir ?

Il s’agit ici d’un service API qui traite les requêtes, l’authentification et les réponses du modèle. Un proxy réseau transmet le trafic, mais ne convertit pas à lui seul les formats d’API. Fondez votre choix sur la spécification du service.

Le guide actuel de Google utilise des exemples de l’Interactions API. La référence GenerateContent décrit un contrat distinct. Ne mélangez pas leurs champs et leurs méthodes de lecture des réponses, et ne supposez pas qu’un relais propose les deux.

Comprendre une image et en générer une sont également deux capacités différentes. Un modèle peut décrire une photo tout en produisant uniquement du texte. Un appel texte réussi ne valide donc ni la génération ni la retouche. La mention « compatible OpenAI » ne prouve pas non plus que toutes les méthodes du SDK sont disponibles pour une route d’images.

Choisir un véritable modèle d’images

La documentation de Google distingue notamment ces identifiants :

• Nano Banana 2.1 : gemini-nano-banana-2.1, le point de départ recommandé par Google pour de nouveaux usages généraux d’images.
• Nano Banana Pro : gemini-3-pro-image, une option distincte pour des tâches visuelles plus exigeantes.
• Nano Banana 2 : gemini-3.1-flash-image, la génération précédente, et non un alias de 2.1.

Copiez l’identifiant depuis le service que vous appellerez. Vérifiez les droits, la génération ou la retouche, la taille et l’unité de facturation. Pour 2.1, OmniaKey documente parameters.aspect_ratio et parameters.image_size, avec les niveaux 1K, 2K et 4K. Ces champs ne sont pas interchangeables avec imageConfig de Google ou size et quality de GPT Image.

Consultez la fiche Nano Banana 2.1 pour l’offre actuelle et le comparatif 2.1 et Pro pour le choix du modèle.

Générer une image avec OmniaKey

Il vous faut Bash, cURL, jq et une clé OmniaKey dans la variable locale OMNIAKEY_API_KEY. Exécutez ces commandes côté serveur ou sur votre poste de développement. N’exposez pas la clé dans le navigateur. Le prompt d’exemple, volontairement simple et conservé en anglais, sert d’abord à vérifier le fonctionnement de l’API.

1. Créer et enregistrer la tâche

Choisissez un Idempotency-Key unique pour cette demande logique. La valeur d’exemple est destinée à la démonstration : remplacez-la pour une nouvelle tâche, puis conservez exactement la même clé et le même corps lors des nouvelles tentatives. Enregistrez les deux avant l’envoi.

curl --fail-with-body --silent --show-error \
  https://api.omniakey.com/v1/media/tasks \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-image-demo-20261014-001" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "type": "image",
    "operation": "generate",
    "input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
    "parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
  }' -o task.json

Continuez uniquement si cURL réussit et si task.json contient un id. Une nouvelle tâche renvoie 202 Accepted. Répéter la clé et le corps récupère la tâche initiale avec 200. L’acceptation ne signifie pas que l’image est terminée. Voir le cycle de vie des tâches, en anglais.

2. Interroger l’identifiant enregistré

Cet exemple Bash limite le nombre de consultations. Une fois cette limite atteinte, l’identifiant reste disponible pour reprendre plus tard. Aucune annulation ni nouvelle création n’est déclenchée.

TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
  curl --fail-with-body --silent --show-error \
    "https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
    -o result.json || exit 1
  STATUS="$(jq -er '.status' result.json)" || exit 1
  case "$STATUS" in
    succeeded) break ;;
    failed|canceled) jq '.error' result.json; exit 1 ;;
    queued|processing) sleep 3 ;;
    *) exit 1 ;;
  esac
done

Si la création dépasse le délai avant de fournir un identifiant, répétez le même corps avec la même clé d’idempotence. Si vous avez déjà un identifiant, consultez cette tâche. Une nouvelle clé peut créer une seconde tâche facturable. La reprise reste soumise à la conservation des données : les tâches sont conservées 24 heures après leur création.

3. Télécharger uniquement un résultat réussi

jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
  "$ASSET_URL" -o generated-image

Utilisez mime_type pour choisir l’extension, puis vérifiez que le fichier s’ouvre et possède les dimensions attendues. Les URL signées expirent. Une nouvelle consultation peut fournir un nouveau lien tant que la tâche et le fichier restent disponibles. Téléchargez les images à conserver : une URL signée n’est pas un stockage permanent.

Retoucher une image de référence

Utilisez operation: "edit" avec des données Base64 intégrées dans input.image, ou input.images pour plusieurs références lorsque le modèle le permet. L’instruction de retouche reste dans input.prompt. La documentation de l’API d’images, en anglais fournit le format complet.

Le corps entier de la requête est limité à 1 MiB, Base64 compris. Compressez ou redimensionnez la référence si nécessaire. Les limites de téléversement de Google ne remplacent pas celles du relais. Commencez avec une petite image et une modification précise, puis contrôlez les éléments qui devaient être préservés.

Changer le prompt, la référence, le modèle ou un paramètre crée une nouvelle demande : utilisez une nouvelle clé. Un corps différent avec la même clé produit 409 idempotency_key_reused.

Identifier la couche en échec

Le guide de dépannage Google décrit son propre comportement. Le relais ajoute une couche. Conservez le statut HTTP, le code d’erreur, l’identifiant et les durées dans des journaux expurgés, sans clé ni référence privée. Un JSON renvoyé avec 200 ne prouve pas qu’une image exploitable existe.

Comparer les coûts et valider l’intégration

La facturation directe de Google et celle d’un relais correspondent à deux offres distinctes. Avant un lot, vérifiez les tarifs actuels d’OmniaKey et l’unité du modèle. N’appliquez pas un tarif de tokens texte à une image et ne supposez pas qu’un abonnement grand public Gemini finance les appels du relais.

Une mesure utile est montant total facturé ÷ nombre d’images retenues. Incluez les nouvelles tentatives facturées et les images rejetées à la vérification. Il s’agit d’une formule de prévision, pas d’un résultat mesuré ni d’une garantie de prix inférieur.

Avant d’augmenter le volume, testez cinq cas simples :

1. Un prompt fournit une image qui s’ouvre, au format et aux dimensions attendus.
2. La retouche d’une référence effectue la modification et préserve les détails requis.
3. La répétition de la même clé et du même corps renvoie le même identifiant.
4. Une consultation interrompue reprend avec l’identifiant sans nouvelle création.
5. Un paramètre invalide ou un modèle indisponible produit une erreur compréhensible, sans faux succès.

Notez modèle, paramètres, durée, état final, montant et décision de validation. Vérifiez le traitement des prompts et des références avant d’envoyer des éléments de production.

Questions fréquentes

Suffit-il de changer l’URL de base du SDK ?

Uniquement si le relais documente le point de terminaison, les champs et la réponse d’image attendus par ce SDK. Testez l’opération d’image elle-même ; un appel de chat ne suffit pas.

Un relais supprime-t-il les limites de Gemini ?

Non. Les limites du fournisseur, du modèle, du relais et du compte peuvent se cumuler. Une passerelle ne garantit ni une génération illimitée ni une disponibilité régionale.

Par quel modèle commencer ?

Consultez le catalogue actuel, puis évaluez un modèle compatible avec une petite tâche. Le guide Nano Banana 2.1 détaille les évolutions du modèle ; cet article se concentre sur l’intégration.

Sources et prochaine étape

Les références principales sont le guide d’images, la référence GenerateContent et le dépannage de Google, ainsi que les documents OmniaKey liés dans le texte. Ces ressources sont en anglais. Spécifications vérifiées le 14 octobre 2026 ; confirmez vos droits avant d’exécuter l’exemple.