La version Preview de Gemini 2.5 Pro est désormais disponible pour un usage en production. En savoir plus

Cette page a été traduite par l'API Cloud Translation.

Compréhension des images

Les modèles Gemini peuvent traiter des images, ce qui permet de prendre en charge de nombreux cas d'utilisation de pointe qui auraient traditionnellement nécessité des modèles spécifiques au domaine. Voici quelques-unes des fonctionnalités de vision de Gemini:

Ajouter des légendes et répondre à des questions sur des images
Transcrire et raisonner sur des PDF, y compris jusqu'à deux millions de jetons
Détecter des objets dans une image et renvoyer leurs coordonnées de cadre de délimitation
Segmenter des objets dans une image

Gemini a été conçu dès le départ pour être multimodal, et nous continuons de repousser les limites du possible. Ce guide explique comment utiliser l'API Gemini pour générer des réponses textuelles basées sur des entrées d'images et effectuer des tâches courantes de compréhension des images.

Avant de commencer

Avant d'appeler l'API Gemini, assurez-vous d'avoir installé le SDK de votre choix et d'avoir configuré une clé API Gemini prête à l'emploi.

Saisie d'image

Vous pouvez fournir des images à Gemini de différentes manières:

Importez un fichier image à l'aide de l'API File avant d'envoyer une requête à generateContent. Utilisez cette méthode pour les fichiers de plus de 20 Mo ou lorsque vous souhaitez réutiliser le fichier dans plusieurs requêtes.
Transmettez des données d'image intégrées avec la requête à generateContent. Utilisez cette méthode pour les fichiers plus petits (< 20 Mo de taille de requête totale) ou les images extraites directement à partir d'URL.

Importer un fichier image

Vous pouvez utiliser l'API Files pour importer un fichier image. Utilisez toujours l'API Files lorsque la taille totale de la requête (y compris le fichier, l'invite de texte, les instructions système, etc.) dépasse 20 Mo ou si vous prévoyez d'utiliser la même image dans plusieurs invites.

Le code suivant importe un fichier image, puis l'utilise dans un appel à generateContent.

Python

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

myfile = client.files.upload(file="path/to/sample.jpg")

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[myfile, "Caption this image."])

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.jpg",
    config: { mimeType: "image/jpeg" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Caption this image.",
    ]),
  });
  console.log(response.text);
}

await main();

Go

file, err := client.UploadFileFromPath(ctx, "path/to/sample.jpg", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Caption this image."))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)

REST

IMAGE_PATH="path/to/sample.jpg"
MIME_TYPE=$(file -b --mime-type "${IMAGE_PATH}")
NUM_BYTES=$(wc -c < "${IMAGE_PATH}")
DISPLAY_NAME=IMAGE

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${IMAGE_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}},
          {"text": "Caption this image."}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

Pour en savoir plus sur l'utilisation des fichiers multimédias, consultez la section API Files.

Transmettre des données d'image de manière intégrée

Au lieu d'importer un fichier image, vous pouvez transmettre des données d'image intégrées dans la requête à generateContent. Cette méthode convient aux images plus petites (taille de requête totale inférieure à 20 Mo) ou aux images extraites directement à partir d'URL.

Vous pouvez fournir des données d'image sous forme de chaînes encodées en base64 ou en lisant directement des fichiers locaux (selon le SDK).

Fichier image local :

Python

  from google.genai import types

  with open('path/to/small-sample.jpg', 'rb') as f:
      img_bytes = f.read()

  response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=[
      types.Part.from_bytes(
        data=img_bytes,
        mime_type='image/jpeg',
      ),
      'Caption this image.'
    ]
  )

  print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const base64ImageFile = fs.readFileSync("path/to/small-sample.jpg", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "image/jpeg",
      data: base64ImageFile,
    },
  },
  { text: "Caption this image." },
];

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(response.text);

Go

model := client.GenerativeModel("gemini-2.0-flash")

bytes, err := os.ReadFile("path/to/small-sample.jpg")
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.Blob{MIMEType: "image/jpeg", Data: bytes},
  genai.Text("Caption this image."),
}

resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

REST

IMG_PATH=/path/to/your/image1.jpg

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"image/jpeg",
                "data": "'\$(base64 \$B64FLAGS \$IMG_PATH)'"
              }
            },
            {"text": "Caption this image."},
        ]
      }]
    }' 2> /dev/null

Image à partir d'une URL:

Python

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GOOGLE_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(data=image.content, mime_type="image/jpeg")])

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {
  const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });

  const imageUrl = "https://goo.gle/instrument-img";

  const response = await fetch(imageUrl);
  const imageArrayBuffer = await response.arrayBuffer();
  const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

  const result = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: [
    {
      inlineData: {
        mimeType: 'image/jpeg',
        data: base64ImageData,
      },
    },
    { text: "Caption this image." }
  ],
  });
  console.log(result.text);
}

main();

Go

func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-2.0-flash")

// Download the image.
imageResp, err := http.Get("https://goo.gle/instrument-img")
if err != nil {
  panic(err)
}
defer imageResp.Body.Close()

imageBytes, err := io.ReadAll(imageResp.Body)
if err != nil {
  panic(err)
}

// Create the request.
req := []genai.Part{
  genai.ImageData("jpeg", imageBytes),

  genai.Text("Caption this image."),
}

// Generate content.
resp, err := model.GenerateContent(ctx, req...)
if err != nil {
  panic(err)
}

// Handle the response of generated text.
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

}

REST

IMG_URL="https://goo.gle/instrument-img"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"'"$MIME_TYPE"'",
                "data": "'$(curl -sL "$IMG_URL" | base64 $B64FLAGS)'"
              }
            },
            {"text": "Caption this image."}
        ]
      }]
    }' 2> /dev/null

Voici quelques points à retenir concernant les données d'image intégrées:

La taille totale maximale de la requête est de 20 Mo, ce qui inclut les requêtes textuelles, les instructions système et tous les fichiers fournis en ligne. Si la taille de votre fichier fait que la taille totale de la requête dépasse 20 Mo, utilisez l'API Files pour importer un fichier image à utiliser dans la requête.
Si vous utilisez un exemple d'image plusieurs fois, il est plus efficace d'importer un fichier image à l'aide de l'API File.

Utiliser plusieurs images pour les requêtes

Vous pouvez fournir plusieurs images dans une seule invite en incluant plusieurs objets Part d'image dans le tableau contents. Il peut s'agir d'un mélange de données intégrées (fichiers ou URL locaux) et de références à l'API File.

Python

from google import genai
from google.genai import types

client = genai.Client(api_key="GOOGLE_API_KEY")

# Upload the first image
image1_path = "path/to/image1.jpg"
uploaded_file = client.files.upload(file=image1_path)

# Prepare the second image as inline data
image2_path = "path/to/image2.png"
with open(image2_path, 'rb') as f:
    img2_bytes = f.read()

# Create the prompt with text and multiple images
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[
        "What is different between these two images?",
        uploaded_file,  # Use the uploaded file reference
        types.Part.from_bytes(
            data=img2_bytes,
            mime_type='image/png'
        )
    ]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });

async function main() {
  // Upload the first image
  const image1_path = "path/to/image1.jpg";
  const uploadedFile = await ai.files.upload({
    file: image1_path,
    config: { mimeType: "image/jpeg" },
  });

  // Prepare the second image as inline data
  const image2_path = "path/to/image2.png";
  const base64Image2File = fs.readFileSync(image2_path, {
    encoding: "base64",
  });

  // Create the prompt with text and multiple images
  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: createUserContent([
      "What is different between these two images?",
      createPartFromUri(uploadedFile.uri, uploadedFile.mimeType),
      {
        inlineData: {
          mimeType: "image/png",
          data: base64Image2File,
        },
      },
    ]),
  });
  console.log(response.text);
}

await main();

Go

+    // Upload the first image
image1Path := "path/to/image1.jpg"
uploadedFile, err := client.UploadFileFromPath(ctx, image1Path, nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, uploadedFile.Name)

// Prepare the second image as inline data
image2Path := "path/to/image2.png"
img2Bytes, err := os.ReadFile(image2Path)
if err != nil {
  log.Fatal(err)
}

// Create the prompt with text and multiple images
model := client.GenerativeModel("gemini-2.0-flash")
prompt := []genai.Part{
  genai.Text("What is different between these two images?"),
  genai.FileData{URI: uploadedFile.URI},
  genai.Blob{MIMEType: "image/png", Data: img2Bytes},
}

resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

printResponse(resp)

REST

# Upload the first image
IMAGE1_PATH="path/to/image1.jpg"
MIME1_TYPE=$(file -b --mime-type "${IMAGE1_PATH}")
NUM1_BYTES=$(wc -c < "${IMAGE1_PATH}")
DISPLAY_NAME1=IMAGE1

tmp_header_file1=upload-header1.tmp

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header1.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM1_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME1_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME1}'}}" 2> /dev/null

upload_url1=$(grep -i "x-goog-upload-url: " "${tmp_header_file1}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file1}"

curl "${upload_url1}" \
  -H "Content-Length: ${NUM1_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${IMAGE1_PATH}" 2> /dev/null > file_info1.json

file1_uri=$(jq ".file.uri" file_info1.json)
echo file1_uri=$file1_uri

# Prepare the second image (inline)
IMAGE2_PATH="path/to/image2.png"
MIME2_TYPE=$(file -b --mime-type "${IMAGE2_PATH}")

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
IMAGE2_BASE64=$(base64 $B64FLAGS $IMAGE2_PATH)

# Now generate content using both images
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "What is different between these two images?"},
          {"file_data":{"mime_type": "'"${MIME1_TYPE}"'", "file_uri": '$file1_uri'}},
          {
            "inline_data": {
              "mime_type":"'"${MIME2_TYPE}"'",
              "data": "'"$IMAGE2_BASE64"'"
            }
          }
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

Obtenir un cadre de délimitation pour un objet

Les modèles Gemini sont entraînés pour identifier les objets d'une image et fournir les coordonnées de leur cadre de délimitation. Les coordonnées sont renvoyées par rapport aux dimensions de l'image, mises à l'échelle sur [0, 1 000]. Vous devez redimensionner ces coordonnées en fonction de la taille de votre image d'origine.

Python

prompt = "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."

JavaScript

const prompt = "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000.";

Go

prompt := []genai.Part{
    genai.FileData{URI: sampleImage.URI},
    genai.Text("Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."),
}

REST

PROMPT="Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."

Vous pouvez utiliser des cadres de délimitation pour la détection et la localisation d'objets dans des images et des vidéos. En identifiant et en délimitant précisément des objets à l'aide de cadres de délimitation, vous pouvez débloquer un large éventail d'applications et améliorer l'intelligence de vos projets.

Principaux avantages

Simplicité:intégrez facilement des fonctionnalités de détection d'objets dans vos applications, quel que soit votre niveau d'expertise en vision par ordinateur.
Personnalisable:produit des cadres de délimitation en fonction d'instructions personnalisées (par exemple, "Je souhaite voir les cadres de délimitation de tous les objets verts de cette image"), sans avoir à entraîner un modèle personnalisé.

Détails techniques

Données:votre requête et les images ou les images vidéo associées.
Résultat:cadres de délimitation au format [y_min, x_min, y_max, x_max]. Le coin supérieur gauche correspond à l'origine. Les axes x et y vont horizontalement et verticalement, respectivement. Les valeurs des coordonnées sont normalisées sur la plage 0-1000 pour chaque image.
Visualisation:les utilisateurs d'AI Studio verront des rectangles de délimitation tracés dans l'interface utilisateur.

Pour les développeurs Python, essayez le notebook sur la compréhension spatiale en 2D ou le notebook expérimental sur le pointage en 3D.

Normaliser les coordonnées

Le modèle renvoie les coordonnées du cadre de délimitation au format [y_min, x_min, y_max, x_max]. Pour convertir ces coordonnées normalisées en coordonnées de pixel de votre image d'origine, procédez comme suit:

Divisez chaque coordonnée de sortie par 1 000.
Multipliez les coordonnées X par la largeur de l'image d'origine.
Multipliez les coordonnées Y par la hauteur de l'image d'origine.

Pour obtenir des exemples plus détaillés de génération de coordonnées de cadre de délimitation et de visualisation sur des images, consultez l'exemple de guide de cuisine sur la détection d'objets.

Segmentation d'image

À partir des modèles Gemini 2.5, les modèles Gemini sont entraînés non seulement à détecter des éléments, mais aussi à les segmenter et à fournir un masque de leurs contours.

Le modèle prédit une liste JSON, où chaque élément représente un masque de segmentation. Chaque élément comporte un cadre de délimitation ("box_2d") au format [y0, x0, y1, x1] avec des coordonnées normalisées comprises entre 0 et 1 000, un libellé ("label") qui identifie l'objet, et enfin le masque de segmentation dans le cadre de délimitation, au format PNG encodé en base64, qui est une carte de probabilité avec des valeurs comprises entre 0 et 255. Le masque doit être redimensionné pour correspondre aux dimensions du cadre de délimitation, puis binarisé au seuil de confiance (127 pour le milieu).

Python

prompt = """
  Give the segmentation masks for the wooden and glass items.
  Output a JSON list of segmentation masks where each entry contains the 2D
  bounding box in the key "box_2d", the segmentation mask in key "mask", and
  the text label in the key "label". Use descriptive labels.
"""

JavaScript

const prompt = `
  Give the segmentation masks for the wooden and glass items.
  Output a JSON list of segmentation masks where each entry contains the 2D
  bounding box in the key "box_2d", the segmentation mask in key "mask", and
  the text label in the key "label". Use descriptive labels.
`;

Go

prompt := []genai.Part{
    genai.FileData{URI: sampleImage.URI},
    genai.Text(`
      Give the segmentation masks for the wooden and glass items.
      Output a JSON list of segmentation masks where each entry contains the 2D
      bounding box in the key "box_2d", the segmentation mask in key "mask", and
      the text label in the key "label". Use descriptive labels.
    `),
}

REST

PROMPT='''
  Give the segmentation masks for the wooden and glass items.
  Output a JSON list of segmentation masks where each entry contains the 2D
  bounding box in the key "box_2d", the segmentation mask in key "mask", and
  the text label in the key "label". Use descriptive labels.
'''

Table avec des cupcakes, avec les objets en bois et en verre mis en évidence — Masque des objets en bois et en verre trouvés sur la photo

Pour un exemple plus détaillé, consultez l'exemple de segmentation dans le guide de recettes.

Formats d'image compatibles

Gemini est compatible avec les types MIME de formats d'image suivants:

PNG - image/png
JPEG - image/jpeg
WEBP : image/webp
HEIC : image/heic
HEIF : image/heif

Informations techniques sur les images

Limite de fichiers: Gemini 2.5 Pro, 2.0 Flash, 1.5 Pro et 1.5 Flash acceptent un maximum de 3 600 fichiers image par requête.
Calcul des jetons :
- Gemini 1.5 Flash et Gemini 1.5 Pro: 258 jetons si les deux dimensions sont inférieures ou égales à 384 pixels. Les images plus grandes sont affichées en tuiles (taille minimale de la tuile : 256 px, taille maximale : 768 px, redimensionnement au format 768x768), et chaque tuile coûte 258 jetons.
- Gemini 2.0 Flash: 258 jetons si les deux dimensions sont inférieures ou égales à 384 pixels. Les images plus grandes sont divisées en tuiles de 768 x 768 pixels, chacune coûtant 258 jetons.
Bonnes pratiques :
- Assurez-vous que les images sont correctement pivotées.
- Utilisez des images claires et non floues.
- Lorsque vous utilisez une seule image avec du texte, placez la requête textuelle après la partie image dans le tableau contents.

Étape suivante

Ce guide explique comment importer des fichiers image et générer des sorties textuelles à partir d'entrées image. Pour en savoir plus, consultez les ressources suivantes :

Instructions système: les instructions système vous permettent d'orienter le comportement du modèle en fonction de vos besoins et de vos cas d'utilisation spécifiques.
Analyse vidéo: découvrez comment utiliser les entrées vidéo.
API Files: découvrez comment importer et gérer des fichiers à utiliser avec Gemini.
Stratégies d'invite de fichier: l'API Gemini prend en charge les invites avec des données textuelles, des images, des données audio et des données vidéo, également appelées invites multimodales.
Conseils de sécurité: Parfois, les modèles d'IA générative produisent des résultats inattendus, comme des résultats inexacts, biaisés ou choquants. Le post-traitement et l'évaluation humaine sont essentiels pour limiter le risque de préjudices liés à ces sorties.