Méthodes de saisie de fichiers

Ce guide explique les différentes façons d'inclure des fichiers multimédias tels que des images, des fichiers audio, des vidéos et des documents lorsque vous envoyez des requêtes à l'API Gemini. Le choix de la méthode appropriée dépend de la taille de votre fichier, de l'emplacement où vos données sont actuellement stockées et de la fréquence à laquelle vous prévoyez d'utiliser le fichier.

Le moyen le plus simple d'inclure un fichier comme entrée consiste à lire un fichier local et à l'inclure dans une requête. L'exemple suivant montre comment lire un fichier PDF local. Les PDF sont limités à 50 Mo pour cette méthode. Consultez le tableau comparatif des méthodes de saisie pour obtenir la liste complète des types et limites de saisie de fichiers.

from google import genai
from google.genai import types
import pathlib

client = genai.Client()

filepath = pathlib.Path('my_local_file.pdf')

prompt = "Summarize this document"
response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=filepath.read_bytes(),
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

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

const ai = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
    const filePath = path.join('content', 'my_local_file.pdf'); // Adjust path as needed

    const contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: fs.readFileSync(filePath).toString("base64")
            }
        }
    ];

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

main();

# Encode the local file to base64
B64_CONTENT=$(base64 -w 0 my_local_file.pdf)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Summarize this document"}
        ]
      },
      {
        "parts": [
          {
            "inlineData": {
              "mimeType": "application/pdf",
              "data": "'"${B64_CONTENT}"'"
            }
          }
        ]
      }
    ]
  }'

Comparaison des méthodes de saisie

Le tableau suivant compare chaque méthode d'importation en fonction des limites de fichiers et des cas d'utilisation les plus adaptés. Notez que la limite de taille des fichiers peut varier en fonction du type de fichier et du modèle/tokenizer utilisé pour le traiter.

Données intégrées

Pour les fichiers plus petits (moins de 100 Mo ou 50 Mo pour les PDF), vous pouvez transmettre les données directement dans la charge utile de la requête. Il s'agit de la méthode la plus simple pour les tests rapides ou les applications qui gèrent des données transitoires en temps réel. Vous pouvez fournir des données sous forme de chaînes encodées en base64 ou en lisant directement les fichiers locaux.

Pour obtenir un exemple de lecture à partir d'un fichier local, consultez l'exemple au début de cette page.

Récupérer à partir d'une URL

Vous pouvez également récupérer un fichier à partir d'une URL, le convertir en octets et l'inclure dans l'entrée.

from google import genai
from google.genai import types
import httpx

client = genai.Client()

doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
doc_data = httpx.get(doc_url).content

prompt = "Summarize this document"

response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=doc_data,
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

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

const ai = new GoogleGenAI({});
const docUrl = 'https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf';
const prompt = "Summarize this document";

async function main() {
    const pdfResp = await fetch(docUrl);
      .then((response) => response.arrayBuffer());

    const contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: Buffer.from(pdfResp).toString("base64")
            }
        }
    ];

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

main();

DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

# Generate content using the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

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

API Gemini Files

L'API File est conçue pour les fichiers volumineux (jusqu'à 2 Go) ou les fichiers que vous prévoyez d'utiliser dans plusieurs requêtes.

Importation standard de fichiers

Importez un fichier local dans l'API Gemini. Les fichiers importés de cette manière sont stockés temporairement (48 heures) et traités pour être récupérés efficacement par le modèle.

from google import genai
client = genai.Client()

# Upload the file
audio_file = client.files.upload(file="path/to/your/sample.mp3")
prompt = "Describe this audio clip"

# Use the uploaded file in a prompt
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[prompt, audio_file]
)
print(response.text)

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

const ai = new GoogleGenAI({});
const prompt = "Describe this audio clip";

async function main() {
  const filePath = "path/to/your/sample.mp3"; // Adjust path as needed

  const myfile = await ai.files.upload({
    file: filePath,
    config: { mimeType: "audio/mpeg" },
  });

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

}
await main();

AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

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 "${BASE_URL}/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D "${tmp_header_file}" \
  -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 "@${AUDIO_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-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

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

Enregistrer des fichiers Google Cloud Storage

Si vos données se trouvent déjà dans Google Cloud Storage, vous n'avez pas besoin de les télécharger ni de les réimporter. Vous pouvez l'enregistrer directement avec l'API File.

1. Accorder l'accès Agent de service à chaque bucket

   1. Activez l'API Gemini dans votre projet Google Cloud.

   2. Créez l'agent de service :

      gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>

   3. Accordez à l'agent de service de l'API Gemini les autorisations nécessaires pour lire vos buckets de stockage.

      L'utilisateur doit attribuer le rôle IAM Storage Object Viewer à cet agent de service sur les buckets de stockage spécifiques qu'il compte utiliser.

   Par défaut, cet accès n'expire pas, mais vous pouvez le modifier à tout moment. Vous pouvez également utiliser les commandes du SDK IAM Google Cloud Storage pour accorder des autorisations.

2. Authentifier votre service

   Prérequis

   • Activer l'API
   • Créez un compte de service/agent avec les autorisations appropriées.

   Vous devez d'abord vous authentifier en tant que service disposant des autorisations de lecteur des objets de l'espace de stockage. La procédure dépend de l'environnement dans lequel votre code de gestion des fichiers s'exécutera.

   En dehors de Google Cloud

   Si votre code s'exécute en dehors de Google Cloud, par exemple sur votre ordinateur, téléchargez les identifiants du compte depuis la console Google Cloud en procédant comme suit :

   1. Accédez à la console des comptes de service.
   2. Sélectionnez le compte de service concerné.
   3. Sélectionnez l'onglet Clés, puis Ajouter une clé > Créer une clé.
   4. Choisissez le type de clé JSON et notez l'emplacement où le fichier a été téléchargé sur votre ordinateur.

   Pour en savoir plus, consultez la documentation officielle Google Cloud sur la gestion des clés de compte de service.

   Utilisez ensuite les commandes suivantes pour vous authentifier. Ces commandes supposent que votre fichier de compte de service se trouve dans le répertoire actuel et qu'il est nommé service-account.json.

   Python

   from google.oauth2.service_account import Credentials
   
   GCS_READ_SCOPES = [       
     'https://www.googleapis.com/auth/devstorage.read_only',
     'https://www.googleapis.com/auth/cloud-platform'
   ]
   
   SERVICE_ACCOUNT_FILE = 'service-account.json'
   
   credentials = Credentials.from_service_account_file(
       SERVICE_ACCOUNT_FILE,
       scopes=GCS_READ_SCOPES
   )
   

   JavaScript

   const { GoogleAuth } = require('google-auth-library');
   
   const GCS_READ_SCOPES = [
     'https://www.googleapis.com/auth/devstorage.read_only',
     'https://www.googleapis.com/auth/cloud-platform'
   ];
   
   const SERVICE_ACCOUNT_FILE = 'service-account.json';
   
   const auth = new GoogleAuth({
     keyFile: SERVICE_ACCOUNT_FILE,
     scopes: GCS_READ_SCOPES
   });
   

   CLI

   gcloud auth application-default login \
     --client-id-file=service-account.json \
     --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only'
   

   Sur Google Cloud

   Si vous exécutez directement dans Google Cloud, par exemple en utilisant des fonctions Cloud Run ou une instance Compute Engine, vous disposerez d'identifiants implicites, mais vous devrez vous réauthentifier pour accorder les niveaux d'accès appropriés.

   Python

   Ce code suppose que le service s'exécute dans un environnement où les identifiants par défaut de l'application peuvent être obtenus automatiquement, comme Cloud Run ou Compute Engine.

   import google.auth
   
   GCS_READ_SCOPES = [       
     'https://www.googleapis.com/auth/devstorage.read_only',
     'https://www.googleapis.com/auth/cloud-platform'
   ]
   
   credentials, project = google.auth.default(scopes=GCS_READ_SCOPES)
   

   JavaScript

   Ce code suppose que le service s'exécute dans un environnement où les identifiants par défaut de l'application peuvent être obtenus automatiquement, comme Cloud Run ou Compute Engine.

   const { GoogleAuth } = require('google-auth-library');
   
   const auth = new GoogleAuth({
     scopes: [
       'https://www.googleapis.com/auth/devstorage.read_only',
       'https://www.googleapis.com/auth/cloud-platform'
     ]
   });
   

   CLI

   Il s'agit d'une commande interactive. Pour les services tels que Compute Engine, vous pouvez associer des niveaux d'accès au service en cours d'exécution au niveau de la configuration. Pour obtenir un exemple, consultez la documentation sur le service géré par l'utilisateur.

   gcloud auth application-default login \
   --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
   

3. Enregistrement de fichiers (API Files)

   Utilisez l'API Files pour enregistrer des fichiers et générer un chemin d'accès à l'API Files qui peut être utilisé directement dans l'API Gemini.

   Python

   from google import genai
   from google.genai.types import Part
   
   # Note that you must provide an API key in the GEMINI_API_KEY
   # environment variable, but it is unused for the registration endpoint.
   client = genai.Client()
   
   registered_gcs_files = client.files.register_files(
       uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"],
       # Use the credentials obtained in the previous step.
       auth=credentials
   )
   prompt = "Summarize this file."
   
   # call generateContent for each file
   for f in registered_gcs_files.files:
     print(f.name)
     response = client.models.generate_content(
       model="gemini-3-flash-preview",
       contents=[Part.from_uri(
         file_uri=f.uri,
         mime_type=f.mime_type,
       ),
       prompt],
     )
     print(response.text)
   

   CLI

   access_token=$(gcloud auth application-default print-access-token)
   project_id=$(gcloud config get-value project)
   curl -X POST https://generativelanguage.googleapis.com/v1beta/files:register \
       -H 'Content-Type: application/json' \
       -H "Authorization: Bearer ${access_token}" \
       -H "x-goog-user-project: ${project_id}" \
       -d '{"uris": ["gs://bucket/object1", "gs://bucket/object2"]}'
   

URL HTTP externes / signées

Vous pouvez transmettre des URL HTTPS accessibles au public ou des URL pré-signées (compatibles avec les URL pré-signées S3 et les SAS Azure) directement dans votre demande de génération. L'API Gemini récupérera le contenu de manière sécurisée lors du traitement. Cette option est idéale pour les fichiers de moins de 100 Mo que vous ne souhaitez pas importer à nouveau.

Vous pouvez utiliser des URL publiques ou signées comme entrée en les saisissant dans le champ file_uri.

from google import genai
from google.genai.types import Part

uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
prompt = "Summarize this file"

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        Part.from_uri(
            file_uri=uri,
            mime_type="application/pdf",
        ),
        prompt
    ],
)
print(response.text)

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

const client = new GoogleGenAI({});

const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";

async function main() {
  const response = await client.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: [
      // equivalent to Part.from_uri(file_uri=uri, mime_type="...")
      createPartFromUri(uri, "application/pdf"),
      "summarize this file",
    ],
  });

  console.log(response.text);
}

main();

curl "https://autopush-generativelanguage.sandbox.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
          "contents":[
            {
              "parts":[
                {"text": "Summarize this pdf"},
                {
                  "file_data": {
                    "mime_type":"application/pdf",
                    "file_uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
                  }
                }
              ]
            }
          ]
        }'

Accessibilité

Vérifiez que les URL que vous fournissez ne redirigent pas vers des pages qui nécessitent un identifiant de connexion ou qui sont soumises à un paywall. Pour les bases de données privées, assurez-vous de créer une URL signée avec les autorisations d'accès et la date d'expiration appropriées.

Contrôles de sécurité

Le système effectue une vérification de la modération du contenu sur l'URL pour confirmer qu'elle respecte les normes de sécurité et les règles (par exemple, le contenu non désactivé et payant). Si l'URL que vous avez fournie échoue à ce contrôle, vous recevrez un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Types de contenus acceptés

Cette liste des types de fichiers et des limites acceptés est fournie à titre indicatif et n'est pas exhaustive. L'ensemble effectif des types acceptés est susceptible d'être modifié et peut varier en fonction du modèle et de la version du tokenizer utilisés. Les types non compatibles génèrent une erreur. De plus, la récupération de contenu pour ces types de fichiers n'est actuellement compatible qu'avec les URL accessibles publiquement.

Bonnes pratiques

• Choisissez la bonne méthode : utilisez les données intégrées pour les fichiers petits et temporaires. Utilisez l'API File pour les fichiers volumineux ou fréquemment utilisés. Utilisez des URL externes pour les données déjà hébergées en ligne.
• Spécifiez les types MIME : fournissez toujours le type MIME correct pour les données de fichier afin d'assurer un traitement approprié.
• Gérer les erreurs : implémentez la gestion des erreurs dans votre code pour gérer les problèmes potentiels tels que les défaillances du réseau, les problèmes d'accès aux fichiers ou les erreurs d'API.
• Gérer les autorisations GCS : lorsque vous utilisez l'enregistrement GCS, n'accordez à l'agent de service de l'API Gemini que le rôle Storage Object Viewer nécessaire sur les buckets spécifiques.
• Sécurité des URL signées : assurez-vous que les URL signées ont une durée d'expiration appropriée et des autorisations limitées.

Limites

• Les limites de taille des fichiers varient selon la méthode (voir le tableau comparatif) et le type de fichier.
• Les données intégrées augmentent la taille de la charge utile de la requête.
• Les importations de l'API File sont temporaires et expirent au bout de 48 heures.
• L'extraction d'URL externes est limitée à 100 Mo par charge utile et est compatible avec des types de contenu spécifiques.
• L'enregistrement de Google Cloud Storage nécessite une configuration IAM et une gestion des jetons OAuth appropriées.

Étape suivante

• Essayez d'écrire vos propres requêtes multimodales à l'aide de Google AI Studio.
• Pour savoir comment inclure des fichiers dans vos requêtes, consultez les guides Vision, Audio et Traitement de documents.
• Pour obtenir d'autres conseils sur la conception de requêtes, comme le réglage des paramètres d'échantillonnage, consultez le guide Stratégies de requête.