Nano Banana (modèles d'image Gemini)

Informations communes

• URL de base : https://api.routeapi.ai
• Authentification : Authorization: Bearer $ROUTEAPI_KEY avec une clé API commençant par sk- (à créer sur la page Clés API). Les clés de gestion commençant par rat_ ne peuvent pas appeler de modèle.
• Format d’erreur : {"error": {"message": "...", "type": "...", "code": "..."}} ; voir Erreurs courantes pour la signification des codes de statut.

Modèles d’image Gemini en vente : gemini-3.1-flash-image-preview, gemini-3-pro-image-preview et gemini-3.1-flash-lite-image. Ce sont des modèles de génération d’images servis par des canaux Gemini, et il y a deux façons de les atteindre (vérifiez supported_endpoint_types dans Modèles pour la liste exacte de chaque modèle) :

Chemin	Point de terminaison	Corps que vous envoyez
Format image OpenAI	POST /v1/images/generations	JSON d’image OpenAI, décrit dans Format d’image OpenAI
Gemini natif	POST /v1beta/models/{model}:generateContent	contents + generationConfig de Gemini

Utilisez le chemin natif si vous parlez déjà le protocole Gemini (SDK Google GenAI) et avez besoin d’un contrôle complet sur responseModalities et imageConfig ; utilisez /v1/images/generations si votre client ne parle que l’API image OpenAI.

Via /v1/images/generations

L’enveloppe, l’authentification et le corps d’erreur sont identiques à Format d’image OpenAI. RouteAPI convertit votre requête d’image en appel Gemini generateContent.

Paramètres de requête

Champ	Type	Requis	Description
model	string	Oui	ID de modèle d’image Gemini tel que gemini-3.1-flash-image-preview
prompt	string	Oui	Envoyé comme une seule partie texte dans un tour user
size	string	Non	Mappé sur generationConfig.imageConfig.aspectRatio (voir le tableau ci-dessous)
n	integer	Non	Les valeurs supérieures à 1 sont envoyées comme generationConfig.candidateCount ; 1 ou omis n’envoie rien
quality, response_format, style, user, watermark	—	Non	Non convertis sur ce chemin ; ils sont ignorés par l’adaptateur Gemini

RouteAPI remplit lui-même responseModalities avec ["TEXT", "IMAGE"], vous n’avez donc pas à le transmettre via ce point de terminaison. Les paramètres de sécurité proviennent de la configuration Gemini de la plateforme.

Taille vers ratio d’aspect

Seules ces valeurs exactes de size correspondent à un ratio d’aspect :

size	aspectRatio
256x256, 512x512, 1024x1024	1:1
1536x1024	3:2
1024x1536	2:3
1024x1792	9:16
1792x1024	16:9

Une valeur contenant déjà : est transmise comme ratio d’aspect. Toute autre valeur (par exemple 2K ou auto) n’envoie aucun imageConfig, et la valeur par défaut de l’amont s’applique. Les dimensions en pixels ne sont pas demandées sur ce chemin — le ratio est le seul contrôle de taille.

Exemple de requête

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A nano banana wearing sunglasses, studio product shot",
    "size": "1536x1024"
  }'

Réponse

La réponse est convertie en objet image OpenAI ; seules les parties image inline survivent, et tout texte renvoyé par le modèle est abandonné.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

Aucune URL n’est produite sur ce chemin — lisez toujours data[].b64_json. Si la réponse ne contient aucune partie image, la requête échoue avec 500 ; si Gemini bloque le prompt, elle échoue avec 400 et la raison du blocage est enregistrée sur la requête.

Attention

N’utilisez pas /v1/images/edits pour envoyer des images de référence à un modèle d’image Gemini. La requête passe par le chemin de chat texte : seul prompt est converti, image / images / mask sont ignorés, et la réponse est un chat completion OpenAI dont le contenu contient une image Markdown, pas l’objet images. Envoyez la requête native ci-dessous lorsque vous avez besoin d’une entrée image.

Nativement avec generateContent

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Exemple :

curl https://api.routeapi.ai/v1beta/models/gemini-3-pro-image-preview:generateContent \
  -H "x-goog-api-key: $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Draw a cat astronaut on the moon" }] }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Authentification Gemini

Sur les chemins /v1beta, la clé API peut être envoyée de trois façons : x-goog-api-key: $ROUTEAPI_KEY, ?key=$ROUTEAPI_KEY dans la chaîne de requête, ou Authorization: Bearer $ROUTEAPI_KEY. Si plusieurs sont présents, ?key= et x-goog-api-key sont appliqués à la place de Authorization.

Champs de requête

Champ	Type	Requis	Description
contents	array	Oui	Contenu de conversation Gemini ; au moins une entrée. Les rôles sont user et model
generationConfig.responseModalities	array of string	Oui en pratique	Doit inclure IMAGE, sinon le modèle ne répond qu’en texte
generationConfig.imageConfig	object	Non	Options d’image, transmises à Gemini. aspectRatio comme 1:1, 3:2, 16:9 ; imageSize comme 1K, 2K, 4K. Les valeurs acceptées dépendent du modèle
generationConfig.candidateCount	integer	Non	Nombre de candidats ; tous les modèles d’image ne le prennent pas en charge
safetySettings	array	Non	Paramètres de sécurité Gemini, transmis tels quels
systemInstruction	object	Non	Instruction système ; la forme snake_case system_instruction est aussi acceptée

generationConfig accepte les deux orthographes camelCase et snake_case de ses champs (par exemple responseModalities / response_modalities et imageConfig / image_config) ; si les deux sont présents, snake_case l’emporte. imageConfig et son contenu sont transmis sans validation, donc un imageSize non pris en charge est signalé par Gemini, pas par RouteAPI.

Note

Les requêtes natives ne sont pas réécrites comme sur le chemin OpenAI : RouteAPI n’ajoute pas responseModalities à votre place. L’omettre est la raison la plus fréquente d’une réponse en texte sans image.

Entrée image

Pour modifier ou référencer une image, ajoutez une partie image inline à côté du texte :

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Repaint this photo as a watercolor illustration" },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA..."
          }
        }
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

inlineData transporte des octets d’image en Base64, transmis tels quels à Gemini. Pour les fichiers déjà téléversés chez Google, la partie native fileData.fileUri fait aussi partie de la forme transmise. Si votre client parle le format chat OpenAI, les parties image_url sont téléchargées côté serveur et converties en parties inline avant d’atteindre Gemini.

Streaming

Le streaming est sélectionné par le paramètre de requête ?alt=sse, pas par le nom de l’action : avec lui, l’action amont devient streamGenerateContent et la réponse est un flux d’événements server-sent de Gemini. Chaque morceau a la structure standard candidates[].content.parts. Utilisez-le pour recevoir l’image progressivement ; sinon :generateContent renvoie toute la réponse en un seul corps.

Réponse

Le chemin natif renvoie la structure de réponse propre à Gemini, inchangée :

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Here is the image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1132
  }
}

Lisez l’image dans parts[].inlineData ; des parties texte l’accompagnent généralement. Lorsque Gemini bloque la requête, promptFeedback.blockReason est défini et candidates est vide.

Facturation

Les modèles d’image Gemini sont facturés au token : les images générées comptent comme tokens de sortie au prix de sortie, et le prompt ainsi que les images de référence comptent comme tokens d’entrée. Voir Tarification des modèles et la page de détail du modèle pour les tarifs actuels.

Étapes suivantes

• Format d’image OpenAI — l’enveloppe /v1/images partagée et le comportement des modifications.
• Seedream — tailles et sémantique de modification de ByteDance Seedream.
• Modèles — trouver les modèles d’image et confirmer la prise en charge de image-generation.
• Tarification des modèles — facturation au token ou à l’image.