API des modèles d’image Gemini
Formats de requête de Gemini 3.1 Flash Image, Nano Banana 2.1 et Gemini 3 Pro Image via le protocole compatible OpenAI et le protocole natif Gemini, avec les formats d’image, résolutions et images de référence.
Champ d’application
Cette page présente les modèles d’image Gemini. Pour les modèles d’image OpenAI, consultez API des modèles d’image OpenAI ; pour les modèles d’image Grok, consultez API des modèles d’image Grok.
Différence essentielle
Les modèles d’image Gemini ne sont pas des modèles de l’API OpenAI Images. Utilisez /v1/chat/completions ou le point de terminaison natif Gemini /v1beta/models/{model}:generateContent, et n’envoyez pas de requêtes à /v1/images/generations ni à /v1/images/edits.
Modèles et capacités
| Modèle | Résolution | Images de référence | Images par requête | Facturation |
|---|---|---|---|---|
gemini-3.1-flash-image | 1K (par défaut) / 2K / 4Kimage_config | jusqu’à 14 (data URI / URL publique) | toujours 1 | par requête |
gemini-nano-banana-2.1 | 1K (par défaut) / 2K / 4Kimage_config | jusqu’à 6 (data URI / URL publique) | toujours 1 | par requête |
gemini-3-pro-image | 1K (par défaut) / 2K / 4Kimage_config | jusqu’à 14 (data URI / URL publique) | toujours 1 | par requête |
Formats pris en charge : 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9
- Les trois modèles sont facturés à la requête, au même prix quels que soient la résolution et le nombre d’images de référence.
- Chaque requête ne renvoie qu’une seule image ;
netcandidateCountsont sans effet. Pour obtenir plusieurs images, envoyez plusieurs requêtes en parallèle. - Pour
gemini-nano-banana-2.1, nous recommandons au maximum 6 images de référence par requête ; au-delà, les images supplémentaires risquent de ne pas être prises en compte.
Les modèles réellement disponibles sont ceux de la liste de modèles renvoyée par la console.
Protocoles pris en charge
| Protocole | Point de terminaison | Corps de la requête | Cas d’usage |
|---|---|---|---|
| Compatible OpenAI (recommandé) | POST /v1/chat/completions | model + messages | SDK OpenAI, clients unifiés et la plupart des applications |
| Natif Gemini | POST /v1beta/models/{model}:generateContent | contents + generationConfig | Utilisation directe du SDK Gemini ou besoin des champs natifs |
Authentification
Pour le protocole compatible OpenAI, utilisez :
Authorization: Bearer $API_KEY
Content-Type: application/jsonAvec le protocole natif Gemini, vous pouvez aussi utiliser l’en-tête x-goog-api-key, comme le font habituellement les clients Gemini ; sa valeur reste votre jeton 88API. N’incluez jamais une vraie clé dans du code front-end, des journaux ou des exemples publics.
Format d’image et résolution
Le format d’image et la résolution se définissent via image_config :
aspect_ratio: voir le tableau des capacités ci-dessus.image_size:1K(par défaut),2Kou4K, avec unKmajuscule.
Pixels de sortie pour chaque niveau :
| Format | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 3:4 | 896x1200 | 1792x2400 | 3584x4800 |
| 4:3 | 1200x896 | 2400x1792 | 4800x3584 |
| 4:5 | 928x1152 | 1856x2304 | 3712x4608 |
| 5:4 | 1152x928 | 2304x1856 | 4608x3712 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 21:9 | 1584x672 | 3168x1344 | 6336x2688 |
- Sans format d’image indiqué, le modèle choisit le cadrage en fonction du prompt ; avec des images de référence, il reprend par défaut le format de la première image de référence. Si vous avez besoin d’une taille fixe, indiquez
aspect_ratioexplicitement. - La sortie peut être en JPEG ou en PNG. Enregistrez le fichier selon le type MIME renvoyé, sans présumer de l’extension.
Protocole compatible OpenAI (recommandé)
Texte vers image
curl https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"messages": [
{
"role": "user",
"content": "Générer une image d’un chat roux assis près d’une fenêtre, lumière naturelle d’après-midi, style photographie réaliste"
}
],
"extra_body": {
"google": {
"image_config": {
"aspect_ratio": "16:9",
"image_size": "2K"
}
}
}
}'Comment écrire image_config
Le format d’image et la résolution doivent figurer dans extra_body.google.image_config, avec les noms de champs en snake_case aspect_ratio et image_size. Les champs image_config, aspect_ratio ou size placés au niveau supérieur de la requête sont ignorés ; les écritures en camelCase comme imageConfig ou aspectRatio sont refusées.
Avec des images de référence
curl https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "En s’inspirant de la personne de la première image, créer une affiche de film avec cette même personne" },
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
]
}
],
"extra_body": {
"google": { "image_config": { "aspect_ratio": "2:3", "image_size": "2K" } }
}
}'image_url.urlpeut être une Data URI ou l’URL publique d’une image. Une Data URI doit comporter le préfixe complet du type de média, par exempledata:image/png;base64,....- Les formats PNG, JPEG, WebP et GIF sont pris en charge, mais pas BMP. Nous recommandons de ne pas dépasser 7 Mo par image.
- Les images de référence sont prises dans l’ordre ; dans le prompt, vous pouvez y faire référence par « la première image », « la deuxième image », etc.
Champs de la requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
model | string | Oui | Nom du modèle d’image Gemini. |
messages | array | Oui | Tableau de messages OpenAI Chat Completions, généralement un seul message user. |
messages[].content | string ou array | Oui | Une chaîne pour du texte seul ; un tableau de contenus pour combiner texte et images de référence. |
content[].image_url.url | string | Non | Image de référence, en Data URI ou URL publique. |
extra_body.google.image_config.aspect_ratio | string | Non | Format d’image. |
extra_body.google.image_config.image_size | string | Non | 1K, 2K ou 4K. |
Réponse
L’image est renvoyée sous forme d’image Markdown dans choices[0].message.content :
{
"choices": [
{
"message": {
"role": "assistant",
"content": ""
},
"finish_reason": "stop"
}
]
}Extrayez la partie data:<mime>;base64,... de content pour obtenir l’image. N’analysez pas la réponse comme le tableau data de /v1/images/generations.
Protocole natif Gemini
Texte vers image
curl "https://api.88api.ai/v1beta/models/gemini-3-pro-image:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Générer une image d’un chat roux assis près d’une fenêtre, lumière naturelle d’après-midi, style photographie réaliste" }
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
}
}'Images de référence
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "En s’inspirant de cette image, créer une affiche de film avec la même personne" },
{ "inlineData": { "mimeType": "image/png", "data": "<BASE64_DATA>" } }
]
}
],
"generationConfig": {
"imageConfig": { "aspectRatio": "2:3" }
}
}Les images publiques peuvent aussi être transmises avec fileData : { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }.
Réponse
L’image se trouve dans candidates[0].content.parts[].inlineData : mimeType indique le type d’image et data contient les données en Base64.
Streaming et délais d’expiration
stream: true fonctionne, mais l’image est renvoyée en une seule fois dans un seul événement, sans aperçu progressif. Nous recommandons les requêtes sans streaming et un délai d’expiration client d’au moins 5 minutes : une image 4K prend généralement 30 à 60 secondes, et davantage aux heures de pointe.
À ne pas faire
# Erreur : n’utilisez pas le chemin de l’API OpenAI Images pour les modèles d’image Gemini
curl https://api.88api.ai/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "Un chat roux"
}'Ce type de requête renvoie 请使用 Gemini 原生接口调用 / please use the Gemini native API. Utilisez plutôt le format Chat Completions ou le format natif generateContent décrits sur cette page.
Erreurs courantes
| Erreur | Cause |
|---|---|
请使用 Gemini 原生接口调用 (veuillez utiliser l’API native Gemini) | La requête a été envoyée à /v1/images/*. |
extra_body.google.imageConfig is not supported, use extra_body.google.image_config instead | image_config a été écrit en camelCase. |
mime type is not supported by Gemini | Le format de l’image de référence n’est pas pris en charge, par exemple BMP. |
failed to download file | L’URL de l’image de référence n’a pas pu être téléchargée ; vérifiez que le lien est accessible publiquement. |
| Message d’échec de la modération du contenu | Le prompt ou l’image de référence n’a pas passé le contrôle de sécurité, ou le modèle a répondu uniquement par du texte sans générer d’image. Modifiez le prompt puis réessayez. |
Les requêtes en échec ci-dessus ne sont pas facturées.
API des modèles d’image OpenAI
Points de terminaison, tailles, niveaux de qualité, images de référence et arrière-plans transparents pour les familles de modèles d’image gpt-image-2, gpt-image-2.5 et az-gpt-image.
API des modèles d’image Grok
Interfaces texte vers image et édition d’image, formats d’image, résolutions, images de référence et erreurs des modèles d’image Grok Imagine (grok-imagine-image, 2.0, quality, edit).