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. Les nouvelles méthodes sont compatibles avec tous les points de terminaison de l'API Gemini, y compris les API Batch, Interactions et Live. Le choix de la méthode dépend de la taille de votre fichier, de l'emplacement de vos donné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
import pathlib

client = genai.Client()

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

prompt = "Summarize this document"
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "data": filepath.read_bytes(), "mime_type": "application/pdf"}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

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

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

async function main() {
    const filePath = 'my_local_file.pdf';

    const interaction = await client.interactions.create({
        model: "gemini-3-flash-preview",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: fs.readFileSync(filePath).toString("base64"),
                mimeType: "application/pdf"
            }
        ]
    });
    const modelStep = interaction.steps.find(s => s.type === 'model_output');
    if (modelStep) {
      for (const contentBlock of modelStep.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.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/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": [
      {"type": "text", "text": "Summarize this document"},
      {
        "type": "document",
        "data": "'${B64_CONTENT}'",
        "mimeType": "application/pdf"
      }
    ]
  }'

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 taille du fichier peut varier en fonction du type de fichier, du modèle ou du 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
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"

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "document", "data": doc_data, "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

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

const client = 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 interaction = await client.interactions.create({
        model: "gemini-3-flash-preview",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: Buffer.from(pdfResp).toString("base64"),
                mimeType: "application/pdf"
            }
        ]
    });
    const modelStep = interaction.steps.find(s => s.type === 'model_output');
    if (modelStep) {
      for (const contentBlock of modelStep.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.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 interactions
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": [
        {"type": "document", "data": "'$ENCODED_PDF'", "mimeType": "application/pdf"},
        {"type": "text", "text": "'$PROMPT'"}
      ]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".steps[] | select(.type == \"model_output\") | .content[] | select(.type == \"text\") | .text" response.json

API Gemini File

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 an interaction
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": prompt},
        {"type": "audio", "uri": audio_file.uri, "mime_type": audio_file.mime_type}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

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

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

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

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

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
        { type: "text", text: prompt },
        { type: "audio", uri: myfile.uri, mimeType: myfile.mimeType }
    ]
  });
  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.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.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -D "${tmp_header_file}" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -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)

# Now use in an interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": [
        {"type": "text", "text": "Describe this audio clip"},
        {"type": "audio", "uri": '$file_uri', "mimeType": "'${MIME_TYPE}'"}
      ]
    }'

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 Storage.

      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.

   Cet accès n'expire pas par défaut, 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 ou un agent disposant des 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
   
   # 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(credentials=credentials)
   
   registered_gcs_files = client.files.register_files(
       uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
   )
   prompt = "Summarize this file."
   
   # call interactions.create for each file
   for f in registered_gcs_files.files:
     print(f.name)
     interaction = client.interactions.create(
       model="gemini-3-flash-preview",
       input=[
         {"type": "text", "text": prompt},
         {"type": "document", "uri": f.uri, "mime_type": f.mime_type}
       ],
     )
     # Print the model's text response
     for step in interaction.steps:
         if step.type == "model_output":
             for content_block in step.content:
                 if content_block.type == "text":
                     print(content_block.text)
   

   JavaScript

   import { GoogleGenAI } from "@google/genai";
   
   const ai = new GoogleGenAI({ auth: auth });
   
   async function main() {
       const registeredGcsFiles = await ai.files.registerFiles({
           uris: ["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
       });
   
       const prompt = "Summarize this file.";
   
       for (const file of registeredGcsFiles.files) {
           console.log(file.name);
           const interaction = await ai.interactions.create({
               model: "gemini-3-flash-preview",
               input: [
                   { type: "text", text: prompt },
                   { type: "document", uri: file.uri, mimeType: file.mimeType }
               ]
           });
   
           const modelStep = interaction.steps.find(s => s.type === 'model_output');
           if (modelStep) {
               for (const contentBlock of modelStep.content) {
                   if (contentBlock.type === 'text') console.log(contentBlock.text);
               }
           }
       }
   }
   
   main();
   

   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 directement dans votre requête. L'API Gemini récupère 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.

from google import genai

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "document", "uri": uri, "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

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

const client = new GoogleGenAI({});

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

async function main() {
  const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: [
      { type: "document", uri: uri, mimeType: "application/pdf" },
      { type: "text", text: "summarize this file" }
    ]
  });

  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.text);
    }
  }
}

main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
          "model": "gemini-3-flash-preview",
          "input": [
            {"type": "text", "text": "Summarize this pdf"},
            {
              "type": "document",
              "uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
              "mimeType": "application/pdf"
            }
          ]
        }'

Accessibilité

Vérifiez que les URL que vous fournissez ne redirigent pas vers des pages qui nécessitent une 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 modération du contenu de l'URL pour confirmer qu'elle respecte les normes de sécurité et les règles. Si l'URL é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 possible qu'avec des URL accessibles au public.

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 : indiquez 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.

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.

É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.