Gemini 2.0 Flash est désormais prêt à être déployé en production. En savoir plus

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

Explorez les fonctionnalités visuelles de l'API Gemini

Les modèles Gemini sont capables de traiter des images et des vidéos, ce qui permet de répondre à de nombreux cas d'utilisation de pointe qui auraient auparavant 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écrire, segmenter et extraire des informations à partir de vidéos de 90 minutes maximum
Détecter des objets dans une image et renvoyer leurs coordonnées de cadre de délimitation

Gemini a été conçu dès le départ pour être multimodal, et nous continuons de repousser les limites du possible.

Saisie d'image

Pour une taille de charge utile d'image totale inférieure à 20 Mo, nous vous recommandons d'importer des images encodées en base64 ou directement des fichiers image stockés en local.

Utiliser des images locales

Si vous utilisez la bibliothèque d'images Python (Pillow ), vous pouvez également utiliser des objets d'image PIL.

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

Images encodées en base64

Vous pouvez importer des URL d'images publiques en les encodant en tant que charges utiles Base64. L'exemple de code suivant montre comment procéder en n'utilisant que les outils de bibliothèque standards:

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="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

Images multiples

Pour afficher plusieurs images dans une invite, vous pouvez fournir plusieurs images dans l'appel de generate_content. Ils peuvent être au format compatible, y compris base64 ou PIL.

from google import genai
from google.genai import types

import pathlib
import PIL.Image

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

Notez que ces appels de données intégrés n'incluent pas de nombreuses fonctionnalités disponibles via l'API File, telles que l'obtention des métadonnées de fichier, la mise en liste ou la suppression de fichiers.

Charges utiles d'images volumineuses

Lorsque la combinaison des fichiers et des instructions système que vous souhaitez envoyer dépasse 20 Mo, utilisez l'API File pour importer ces fichiers.

Utilisez la méthode media.upload de l'API File pour importer une image de n'importe quelle taille.

Après avoir importé le fichier, vous pouvez envoyer des requêtes GenerateContent qui font référence à l'URI de l'API File. Sélectionnez le modèle génératif et fournissez-lui une requête textuelle et l'image importée.

from google import genai

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

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

Compatibilité avec OpenAI

Vous pouvez accéder aux fonctionnalités de compréhension des images de Gemini à l'aide des bibliothèques OpenAI. Vous pouvez ainsi intégrer Gemini aux workflows OpenAI existants en mettant à jour trois lignes de code et en utilisant votre clé API Gemini. Consultez l'exemple d'analyse d'images pour obtenir du code illustrant comment envoyer des images encodées en tant que charges utiles Base64.

Requêtes avec des images

Dans ce tutoriel, vous allez importer des images à l'aide de l'API File ou en tant que données intégrées, et générer du contenu en fonction de ces images.

Détails techniques (images)

Gemini 1.5 Pro et Gemini 1.5 Flash acceptent un maximum de 3 600 fichiers image.

Les images doivent correspondre à l'un des types MIME de données d'image suivants:

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

Jetons

Voici comment les jetons sont calculés pour les images:

Gemini 1.0 Pro Vision: chaque image compte pour 258 jetons.
Gemini 1.5 Flash et Gemini 1.5 Pro: si les deux dimensions d'une image sont inférieures ou égales à 384 pixels, 258 jetons sont utilisés. Si l'une des dimensions d'une image est supérieure à 384 pixels, l'image est recadrée en vignettes. Chaque taille de vignette est définie par défaut sur la plus petite dimension (largeur ou hauteur), divisée par 1,5. Si nécessaire, chaque vignette est ajustée pour qu'elle ne soit pas inférieure à 256 et ne dépasse pas 768. Chaque vignette est ensuite redimensionnée au format 768x768 et utilise 258 jetons.
Gemini 2.0 Flash: les entrées d'image dont les deux dimensions sont inférieures ou égales à 384 pixels sont comptabilisées comme 258 jetons. Les images dont une ou les deux dimensions sont plus grandes sont recadrées et mises à l'échelle si nécessaire en tuiles de 768 x 768 pixels, chacune comptant pour 258 jetons.

Pour obtenir les meilleurs résultats possibles

Faites pivoter les images dans l'orientation appropriée avant de les importer.
Évitez les images floues.
Si vous utilisez une seule image, placez la requête textuelle après l'image.

Capacités

Cette section décrit les fonctionnalités de vision spécifiques du modèle Gemini, y compris la détection d'objets et les coordonnées du cadre de délimitation.

Obtenir un cadre de délimitation pour un objet

Les modèles Gemini sont entraînés pour renvoyer les coordonnées du cadre de délimitation sous forme de largeurs ou de hauteurs relatives dans la plage [0, 1]. Ces valeurs sont ensuite mises à l'échelle de 1 000 et converties en entiers. En fait, les coordonnées représentent le cadre de délimitation sur une version de l'image de 1 000 x 1 000 pixels. Par conséquent, vous devez convertir ces coordonnées en fonction des dimensions de votre image d'origine pour cartographier précisément les cadres de délimitation.

from google import genai

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

prompt = (
  "Return a bounding box for each of the objects in this image "
  "in [ymin, xmin, ymax, xmax] format.")

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

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

Entrée: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 découvrir des exemples plus détaillés de génération de coordonnées de cadre de délimitation et de visualisation sur des images, nous vous invitons à consulter notre exemple de guide de cuisine sur la détection d'objets.

Insérer des invites avec une vidéo

Dans ce tutoriel, vous allez importer une vidéo à l'aide de l'API File et générer du contenu à partir de ces images.

Détails techniques (vidéo)

Gemini 1.5 Pro et Flash acceptent jusqu'à environ une heure de données vidéo.

La vidéo doit correspondre à l'un des types MIME de format vidéo suivants:

video/mp4
video/mpeg
video/mov
video/avi
video/x-flv
video/mpg
video/webm
video/wmv
video/3gpp

Le service de l'API File extrait des images des vidéos à 1 image par seconde (FPS) et de l'audio à 1 kbit/s, sur un seul canal, en ajoutant des codes temporels toutes les secondes. Ces tarifs sont susceptibles d'être modifiés à l'avenir pour améliorer les inférences.

Chaque image équivaut à 258 jetons, et l'audio à 32 jetons par seconde. Avec les métadonnées, chaque seconde de vidéo correspond à environ 300 jetons, ce qui signifie qu'une fenêtre de contexte de 1 million de jetons peut contenir un peu moins d'une heure de vidéo.

Pour poser des questions sur des emplacements avec code temporel, utilisez le format MM:SS, où les deux premiers chiffres représentent les minutes et les deux derniers les secondes.

Pour des résultats optimaux, procédez comme suit :

Utilisez une vidéo par requête.
Si vous n'utilisez qu'une seule vidéo, placez la requête textuelle après la vidéo.

Importer un fichier vidéo à l'aide de l'API File

L'API File accepte directement les formats de fichiers vidéo. Cet exemple utilise le court-métrage de la NASA "La Grande Tache rouge de Jupiter se rétrécit et se développe". Crédit: Goddard Space Flight Center (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" est dans le domaine public et ne montre pas de personnes identifiables. (Consignes d'utilisation des images et des contenus multimédias de la NASA)

Commencez par récupérer la courte vidéo:

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

Importez la vidéo à l'aide de l'API File et imprimez l'URI.

from google import genai

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

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
print(f"Completed upload: {video_file.uri}")

Vérifier l'importation de fichiers et l'état

Vérifiez que l'API a bien reçu les fichiers en appelant la méthode files.get.

import time

# Check whether the file is ready to be used.
while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(1)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

print('Done')

Requête avec une vidéo et du texte

Une fois la vidéo mise en ligne dans l'état ACTIVE, vous pouvez envoyer des requêtes GenerateContent qui spécifient l'URI de l'API File pour cette vidéo. Sélectionnez le modèle génératif et fournissez-lui la vidéo importée et une requête textuelle.

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

# Print the response, rendering any Markdown
Markdown(response.text)

Se reporter aux codes temporels du contenu

Vous pouvez utiliser des codes temporels au format HH:MM:SS pour faire référence à des moments spécifiques de la vidéo.

prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Transcrire des vidéos et fournir des descriptions visuelles

Les modèles Gemini peuvent transcrire et fournir des descriptions visuelles du contenu vidéo en traitant à la fois la piste audio et les images. Pour les descriptions visuelles, le modèle échantillonne la vidéo à un taux de 1 image par seconde. Ce taux d'échantillonnage peut affecter le niveau de détail des descriptions, en particulier pour les vidéos dont les visuels changent rapidement.

prompt = (
    "Transcribe the audio from this video, giving timestamps for "
    "salient events in the video. Also provide visual descriptions.")

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

Répertorier les fichiers

Vous pouvez lister tous les fichiers importés à l'aide de l'API File et leurs URI à l'aide de files.list.

from google import genai

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

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

Supprimer des fichiers

Les fichiers importés à l'aide de l'API File sont automatiquement supprimés au bout de deux jours. Vous pouvez également les supprimer manuellement à l'aide de files.delete.

from google import genai

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

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

Étape suivante

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

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.
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.
Conseils de sécurité: Les modèles d'IA générative produisent parfois 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.