Metodi di input dei file

Questa guida spiega i diversi modi in cui puoi includere file multimediali come immagini, audio, video e documenti quando effettui richieste all'API Gemini. La scelta del metodo giusto dipende dalle dimensioni del file, dalla posizione in cui sono attualmente archiviati i dati e dalla frequenza con cui prevedi di utilizzare il file.

Il modo più semplice per includere un file come input è leggere un file locale e includerlo in un prompt. L'esempio seguente mostra come leggere un file PDF locale. I PDF sono limitati a 50 MB per questo metodo. Consulta la tabella di confronto dei metodi di input per un elenco completo dei tipi di input e dei limiti dei file.

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}"'"
            }
          }
        ]
      }
    ]
  }'

Confronto dei metodi di immissione

La tabella seguente mette a confronto ciascun metodo di input con i limiti dei file e i casi d'uso migliori. Tieni presente che il limite di dimensioni del file può variare a seconda del tipo di file e del modello/tokenizer utilizzato per elaborarlo.

Dati in linea

Per i file più piccoli (inferiori a 100 MB o 50 MB per i PDF), puoi trasmettere i dati direttamente nel payload della richiesta. Questo è il metodo più semplice per test rapidi o applicazioni che gestiscono dati temporanei in tempo reale. Puoi fornire i dati come stringhe con codifica base64 o leggendo direttamente i file locali.

Per un esempio di lettura da un file locale, consulta l'esempio all'inizio di questa pagina.

Recuperare da un URL

Puoi anche recuperare un file da un URL, convertirlo in byte e includerlo nell'input.

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 File

L'API File è progettata per file più grandi (fino a 2 GB) o file che intendi utilizzare in più richieste.

Caricamento standard dei file

Carica un file locale nell'API Gemini. I file caricati in questo modo vengono archiviati temporaneamente (48 ore) ed elaborati per un recupero efficiente da parte del modello.

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

Registra i file Google Cloud Storage

Se i dati si trovano già in Google Cloud Storage, non devi scaricarli e ricaricarli. Puoi registrarlo direttamente con l'API File.

1. Concedi l'accesso al service agent a ogni bucket

   1. Abilita l'API Gemini nel tuo progetto Google Cloud.

   2. Crea l'agente di servizio:

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

   3. Concedi al service agent dell'API Gemini le autorizzazioni per leggere i tuoi bucket di archiviazione.

      L'utente deve assegnare il Storage Object Viewer ruolo IAM a questo service agent nei bucket di archiviazione specifici che intende utilizzare.

   Questo accesso non scade per impostazione predefinita, ma può essere modificato in qualsiasi momento. Puoi anche utilizzare i comandi dell'SDK Google Cloud Storage IAM per concedere le autorizzazioni.

2. Autenticare il servizio

   Prerequisiti

   • Abilita API
   • Crea un service account/agente con le autorizzazioni appropriate.

   Devi prima autenticarti come servizio con autorizzazioni di visualizzazione degli oggetti Storage. La modalità dipende dall'ambiente in cui verrà eseguito il codice di gestione dei file.

   Al di fuori di Google Cloud

   Se il tuo codice viene eseguito al di fuori di Google Cloud, ad esempio dal tuo computer, scarica le credenziali dell'account dalla console Google Cloud seguendo i seguenti passaggi:

   1. Vai alla console Service Account.
   2. Seleziona il service account pertinente.
   3. Seleziona la scheda Chiavi e scegli Aggiungi chiave, Crea nuova chiave.
   4. Scegli il tipo di chiave JSON e annota la posizione in cui è stato scaricato il file sul tuo computer.

   Per maggiori dettagli, consulta la documentazione ufficiale di Google Cloud sulla gestione delle chiavi del service account.

   Poi utilizza i seguenti comandi per l'autenticazione. Questi comandi presuppongono che il file dell'account di servizio si trovi nella directory corrente e sia denominato 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
   });
   

   Interfaccia a riga di comando

   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'
   

   Su Google Cloud

   Se esegui l'applicazione direttamente in Google Cloud, ad esempio utilizzando le funzioni Cloud Run o un'istanza Compute Engine, avrai credenziali implicite, ma dovrai eseguire nuovamente l'autenticazione per concedere gli ambiti appropriati.

   Python

   Questo codice prevede che il servizio sia in esecuzione in un ambiente in cui le credenziali predefinite dell'applicazione possono essere ottenute automaticamente, ad esempio Cloud Run o 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

   Questo codice prevede che il servizio sia in esecuzione in un ambiente in cui le credenziali predefinite dell'applicazione possono essere ottenute automaticamente, ad esempio Cloud Run o 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'
     ]
   });
   

   Interfaccia a riga di comando

   Questo è un comando interattivo. Per servizi come Compute Engine, puoi collegare gli ambiti al servizio in esecuzione a livello di configurazione. Per un esempio, consulta la documentazione sul service account gestito dall'utente.

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

3. Registrazione dei file (API Files)

   Utilizza l'API Files per registrare i file e produrre un percorso dell'API Files che può essere utilizzato direttamente nell'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)
   

   Interfaccia a riga di comando

   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"]}'
   

HTTP esterno / URL firmati

Puoi trasmettere URL HTTPS accessibili pubblicamente o URL pre-firmati (compatibili con URL pre-firmati S3 e SAS di Azure) direttamente nella richiesta di generazione. L'API Gemini recupererà i contenuti in modo sicuro durante l'elaborazione. È ideale per i file fino a 100 MB che non vuoi caricare nuovamente.

Puoi utilizzare URL pubblici o firmati come input utilizzando gli URL nel campo 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à

Verifica che gli URL forniti non rimandino a pagine che richiedono l'accesso o sono protette da un paywall. Per i database privati, assicurati di creare un URL firmato con le autorizzazioni di accesso e la scadenza corrette.

Controlli di sicurezza

Il sistema esegue un controllo di moderazione dei contenuti sull'URL per verificare che soddisfino gli standard di sicurezza e delle norme (ad es. contenuti non disattivati e con paywall). Se l'URL che hai fornito non supera questo controllo, riceverai un url_retrieval_status di URL_RETRIEVAL_STATUS_UNSAFE.

Tipi di contenuti supportati

Questo elenco di tipi di file supportati e limitazioni è inteso come guida iniziale e non è esaustivo. L'insieme effettivo dei tipi supportati è soggetto a modifiche e può variare in base al modello e alla versione del tokenizer specifici in uso. I tipi non supportati genereranno un errore. Inoltre, il recupero dei contenuti per questi tipi di file attualmente supporta solo gli URL accessibili pubblicamente.

Best practice

• Scegli il metodo giusto:utilizza i dati incorporati per i file piccoli e temporanei. Utilizza l'API File per i file più grandi o utilizzati di frequente. Utilizza URL esterni per i dati già ospitati online.
• Specifica i tipi MIME:fornisci sempre il tipo MIME corretto per i dati del file per garantire l'elaborazione corretta.
• Gestisci gli errori:implementa la gestione degli errori nel codice per gestire potenziali problemi come errori di rete, problemi di accesso ai file o errori dell'API.
• Gestisci le autorizzazioni GCS:quando utilizzi la registrazione GCS, concedi all'agente di servizio API Gemini solo il ruolo Storage Object Viewer necessario nei bucket specifici.
• Sicurezza degli URL firmati:assicurati che gli URL firmati abbiano un tempo di scadenza appropriato e autorizzazioni limitate.

Limitazioni

• I limiti delle dimensioni dei file variano in base al metodo (vedi la tabella di confronto) e al tipo di file.
• I dati incorporati aumentano le dimensioni del payload della richiesta.
• I caricamenti dell'API File sono temporanei e scadono dopo 48 ore.
• Il recupero di URL esterni è limitato a 100 MB per payload e supporta tipi di contenuti specifici.
• La registrazione di Google Cloud Storage richiede una configurazione IAM e una gestione dei token OAuth corrette.

Passaggi successivi

• Prova a scrivere i tuoi prompt multimodali utilizzando Google AI Studio.
• Per informazioni sull'inclusione di file nei prompt, consulta le guide Vision, Audio e Elaborazione dei documenti.
• Per ulteriori indicazioni sulla progettazione dei prompt, ad esempio sulla regolazione dei parametri di campionamento, consulta la guida alle strategie per i prompt.