Gemini API: quali dimensioni dei file e quali metodi di input sono supportati al momento?

Il 12 gennaio 2026 Google ha pubblicato un aggiornamento per sviluppatori alla Gemini API che cambia il modo in cui si inseriscono i file nel modello e la dimensione massima dei file. In breve: Gemini ora recupera i file direttamente da link esterni e da archivi cloud (quindi non è sempre necessario caricarli), e il limite di dimensione per i file inline è stato aumentato in modo sostanziale. Questi aggiornamenti eliminano attriti per le app reali che già archiviano media o documenti in bucket cloud e rendono i flussi di prototipazione rapida e di produzione più veloci ed economici.

CometAPI fornisce gemini api come Gemini 3 Pro e gemini 3 flash, e ha un prezzo interessante.

Aggiornamenti chiave — cosa c’è di nuovo nella Gemini API?

Lettura diretta di link a file esterni
— Gemini può recuperare file da:
- URL HTTPS pubblici e URL firmati (URL presigned S3, Azure SAS, ecc.).
- Google Cloud Storage (GCS) tramite registrazione dell’oggetto (registra un oggetto GCS una volta e riutilizzalo).
Aumento della dimensione dei file inline — i limiti dei payload inline (nella richiesta) passano da 20 MB → 100 MB (nota: alcuni tipi di file, come i PDF, possono avere limiti effettivi leggermente diversi indicati nella documentazione).
Files API e linee guida batch invariate per file molto grandi — per i file che intendi riutilizzare o più grandi dei limiti inline/esterni, continua a usare la Files API (massimo 2 GB per file, i progetti possono contenere fino a 20 GB di storage Files API; i file caricati sono archiviati per impostazione predefinita per 48 ore). Anche la registrazione GCS supporta file grandi (2 GB per file) e può essere registrata per il riuso.
Note sulla compatibilità dei modelli — alcune famiglie di modelli più vecchie o varianti specializzate possono avere supporti differenti (la documentazione evidenzia eccezioni come alcune famiglie Gemini 2.0 per alcuni flussi basati su URI di file). Conferma sempre la documentazione specifica del modello prima di inviare asset di grandi dimensioni.

Perché il cambiamento nelle capacità di gestione dei file della Gemini API è importante?

Prima di questo aggiornamento, se volevi che la Gemini API (il modello AI di Google) analizzasse file come: un report in PDF; un video; un file audio; o alcune immagini; dovevi prima caricare i file nello storage temporaneo di Gemini.

E inoltre:

i file caricati venivano eliminati dopo 48 ore;
i file non potevano essere troppo grandi (massimo 20 MB);
se i tuoi file erano già ospitati nel cloud (come GCS, S3 o Azure), dovevi ricaricarli—molto scomodo.

Questo raddoppiava lo sforzo degli sviluppatori, aumentava i costi di banda, introducendo latenza e a volte rendeva impraticabili casi d’uso reali (registrazioni lunghe, manuali multi-pagina, immagini ad alta risoluzione). La combinazione di payload inline più grandi e la possibilità di puntare Gemini a storage esistenti (tramite URL pubblici o firmati, o oggetti GCS registrati) accorcia drasticamente il percorso da “dato” a “output utile del modello”:

Zero-Copy Efficiency: Consentendo a Gemini di leggere direttamente dai tuoi bucket di storage esistenti (GCS) o da URL esterni (AWS S3, Azure), elimini la “tassa ETL”. Non devi più scaricare un file sul tuo backend per poi ricaricarlo su Google. È il modello che va verso i dati, non il contrario.
Stateless Architecture: Il limite inline a 100 MB consente richieste “stateless” più potenti. Non devi gestire il ciclo di vita di un file ID o preoccuparti di ripulire vecchi upload per ogni interazione.
Multi-Cloud Agnosticism: Il supporto per URL firmati consente alla Gemini API di integrarsi con data lake ospitati su AWS o Azure. Questo è un enorme vantaggio per le aziende con strategie multi-cloud, perché permette di sfruttare le capacità di ragionamento di Gemini senza migrare tutta l’infrastruttura di storage su Google Cloud.
Adatto ad applicazioni AI multimodali (come video, voce e comprensione di documenti).

Questi aggiornamenti semplificano significativamente il processo di ingestione dei dati, permettendo agli sviluppatori di accedere direttamente ai dati esistenti dal cloud o dalla rete in Gemini senza passaggi di upload aggiuntivi.

Chi ne beneficia di più?

Team di prodotto che costruiscono funzionalità incentrate sui documenti (riassunto, Q&A su manuali, revisione contratti).
App di media/intrattenimento che analizzano immagini, audio o video già archiviati nel cloud.
Enterprise con grandi data lake in GCS che vogliono che il modello faccia riferimento a copie canoniche invece di duplicarle.
Ricercatori e ingegneri che vogliono prototipare con dataset più grandi e reali senza costruire pipeline di storage complicate.

In breve: dal prototipo alla produzione diventa più semplice ed economico.

Quale dimensione di file puoi caricare nella Gemini API ora?

Il numero di copertina è un aumento di capacità di cinque volte, ma la vera novità sta nella flessibilità che offre.

Quanto grande può essere un file che puoi caricare nella Gemini API ora tramite metodi diversi?

Inline in una richiesta (base64 o Part.from_bytes): fino a 100 MB (50 MB per alcuni flussi specifici dei PDF). Usalo quando vuoi un flusso semplice di singola richiesta e il file è ≤100 MB.
HTTP esterno / URL firmato recuperato da Gemini: fino a 100 MB (Gemini recupererà l’URL durante l’elaborazione). Usalo per evitare di ricaricare contenuti da cloud esterni.
Files API (upload): fino a 2 GB per file, storage Files del progetto fino a 20 GB, file archiviati per 48 ore. Usalo per file grandi che riutilizzerai o che superano il limite di 100 MB inline/esterno.
Registrazione di oggetti GCS: supporta fino a 2 GB per oggetto ed è pensata per file grandi già ospitati su Google Cloud; la registrazione consente il riuso senza upload ripetuti. La registrazione una tantum può garantire l’accesso per un periodo limitato.

(La scelta esatta dipende dalla dimensione del file, dalla frequenza di riuso e dal fatto che il file sia già nel cloud storage.)

file di Google

Il nuovo standard da 100 MB

Effettivo immediatamente, la Gemini API ha aumentato il limite di dimensione dei dati inline da 20 MB a 100 MB.

In precedenza, gli sviluppatori che lavoravano con immagini ad alta risoluzione, contratti PDF complessi o clip audio di lunghezza moderata spesso raggiungevano il tetto dei 20 MB. Questo li obbligava a implementare workaround complessi, come il chunking dei dati, il downsampling dei media o la gestione di un flusso di upload separato tramite la Files API anche per interazioni relativamente piccole.

Con il nuovo limite di 100 MB, ora puoi inviare payload significativamente più grandi direttamente nella richiesta API (codificati in base64). Si tratta di un miglioramento fondamentale per:

Applicazioni in tempo reale: elaborare un video caricato dall’utente da 50 MB per un’analisi istantanea del sentiment senza aspettare il completamento di un job di upload asincrono.
Prototipazione rapida: inserire un dataset complesso o un PDF di un libro completo nella finestra di contesto per testare subito una strategia di prompt.
Multimodalità complessa: inviare una combinazione di immagini 4K e segmenti audio ad alta fedeltà in una singola turnazione senza preoccuparsi di superare un limite restrittivo.

È importante notare che, sebbene il limite inline sia 100 MB, la capacità della Gemini API di elaborare dataset massivi (terabyte di dati) resta disponibile tramite la Files API e il nuovo supporto per link esterni, rimuovendo di fatto il limite superiore per i carichi di lavoro pesanti.

Flusso decisionale consigliato

Se il file è ≤ 100 MB e preferisci la semplicità della singola richiesta: usa inline (Part.from_bytes o fornisci base64). Ideale per demo veloci o funzioni serverless.
Se il file è ≤ 100 MB ed è già ospitato da qualche parte in modo pubblico o tramite URL pre-firmato: passa il file_uri (HTTPS o URL firmato). Nessun upload richiesto.
Se il file è > 100 MB (e ≤ 2 GB) o pensi di riutilizzarlo: si consiglia l’upload tramite Files API o registrazione di oggetti GCS — riduce gli upload ripetuti e migliora la latenza per generazioni ripetute.

Come funziona il nuovo supporto per link a file esterni?

Il cambiamento architetturale più significativo è la capacità della Gemini API di “recuperare” i dati in autonomia. Questa capacità consiste nella lettura diretta di link a file esterni, con supporto per fonti di dati integrate.

L’API ora può ingerire dati direttamente da URL. Questo supporto copre due scenari distinti:

(1) Supporto URL esterni (Pubblici / URL firmati):

Ora puoi passare un normale URL HTTPS che punta a un file (come un PDF, un’immagine o un video) direttamente nella tua richiesta di generazione.

URL pubblici: Ideali per analizzare contenuti già sul web aperto, come un PDF di un articolo di news o un’immagine ospitata pubblicamente.

URL firmati: Questo è il ponte per le imprese. Se i tuoi dati risiedono in un bucket privato AWS S3 o in Azure Blob Storage, puoi generare un Pre-Signed URL (un link temporaneo che concede accesso in lettura). Quando fornisci questo URL a Gemini, l’API recupera in modo sicuro il contenuto durante l’elaborazione. Questo implica che puoi usare Gemini per analizzare documenti sensibili archiviati su AWS senza spostarli permanentemente sui server di Google.

Rispetta i ruoli IAM di Google Cloud, il che significa che puoi controllare l’accesso usando le autorizzazioni standard “Storage Object Viewer”.

Vantaggi: niente file intermedi, migliore sicurezza e performance, adatto al recupero dati tra ambienti cloud.

(2) Connessione diretta a Google Cloud Storage (GCS):

Per i dati già all’interno dell’ecosistema Google, l’integrazione è ancora più stretta. Ora puoi eseguire la registrazione dell’oggetto per i file GCS.

Invece di caricare, semplicemente “registri” l’URI gs:// del file.

Questo processo è quasi istantaneo perché non avviene alcun trasferimento di dati tra il tuo client e l’API.

Come usare le nuove funzionalità? — Esempi d’uso (SDK Python)

Di seguito tre esempi pratici in Python (sincroni) che illustrano i pattern comuni: (A) bytes inline (da un file locale), (B) HTTPS esterno o URL firmato, e (C) riferimento a un URI GCS (oggetto registrato). Questi snippet usano l’SDK Python ufficiale Google Gen AI (google-genai). Regola i nomi dei modelli, l’autenticazione e le variabili d’ambiente in base alla tua configurazione. Puoi usare la chiave API di CometAPI per accedere alla Gemini API, una piattaforma di aggregazione di API AI che offre prezzi più bassi per aiutare gli sviluppatori.

Prerequisito: pip install --upgrade google-genai e imposta le tue credenziali/variabili d’ambiente (per la Developer API API_KEY, per Vertex AI imposta GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION).

Esempio A: Bytes inline (file locale → invio fino a 100 MB)

# Example A: send a local file's bytes inline (suitable up to 100 MB)from google import genaifrom google.genai import types# Create client (Developer API)client = genai.Client(api_key="YOUR_GEMINI_API_KEY")MODEL = "gemini-2.5-flash"  # choose model; production models may differfile_path = "large_document.pdf"  # local file <= ~100 MBmime_type = "application/pdf"# Read bytes and create an inline Partwith open(file_path, "rb") as f:    data = f.read()part = types.Part.from_bytes(data=data, mime_type=mime_type)# Send the file inline with a textual promptresponse = client.models.generate_content(    model=MODEL,    contents=[        "Please summarize the attached document in one paragraph.",        part,    ],)print(response.text)client.close()

Note: questo usa Part.from_bytes(...) per inserire i byte del file. I payload inline sono ora consentiti fino a ~100 MB. Se superi tale soglia, usa un approccio GCS o Files API.

Esempio B: HTTPS esterno / URL firmato (Gemini recupera il payload)

# Example B: reference a public HTTPS URL or a signed URL (Gemini fetches it)from google import genaifrom google.genai import typesclient = genai.Client(api_key="YOUR_API_KEY")MODEL = "gemini-2.5-flash"# Public or signed URL to a PDF/image/audio/etc.external_url = "https://example.com/reports/quarterly_report.pdf"# or a pre-signed S3/Azure URL:# external_url = "https://s3.amazonaws.com/yourbucket/obj?X-Amz-..."part = types.Part.from_uri(file_uri=external_url, mime_type="application/pdf")response = client.models.generate_content(    model=MODEL,    contents=[        "Give me the three key takeaways from this report.",        part,    ],)print(response.text)client.close()

Note: Gemini recupererà external_url al momento della richiesta. Usa URL firmati per provider di cloud privati (AWS/Azure). I recuperi esterni hanno limiti pratici di dimensione/formato (vedi documentazione).

Esempio C: Riferimento diretto a un oggetto GCS (gs://)

# Example C: reference a GCS file (ensure service account has storage access)from google import genaifrom google.genai import types# For Vertex AI usage, standard practice is to use ADC (Application Default Credentials)client = genai.Client(vertexai=True, project="your-project-id", location="us-central1")MODEL = "gemini-3-pro"  # example model idgcs_uri = "gs://my-bucket/path/to/manual.pdf"part = types.Part.from_uri(file_uri=gcs_uri, mime_type="application/pdf")response = client.models.generate_content(    model=MODEL,    contents=[        "Extract the section titles from the attached manual and list them.",        part,    ],)print(response.text)client.close()

Note: L’accesso a GCS richiede una corretta configurazione IAM e del service account (permessi object viewer, autenticazione appropriata). Quando registri o riferisci oggetti GCS, assicurati che l’ambiente di runtime (Vertex / ADC / service account) abbia i permessi necessari.

Limitazioni e considerazioni sulla sicurezza

Vincoli di dimensione e tipo di contenuto

Dimensione del recupero esterno: il recupero di URL esterni è soggetto ai limiti documentati (in pratica 100 MB per payload recuperato) e ai tipi MIME/contenuti supportati. Se devi passare asset molto grandi (multi-GB), usa la Files API o un pipeline di elaborazione diversa.

Files API vs inline vs URL esterno: quando usare cosa

Inline (from_bytes) — il più semplice per singoli file una tantum quando la tua applicazione ha già i byte e la dimensione è ≤100 MB. Buono per sperimentazione e servizi piccoli.
URL esterno / URL firmato — ideale quando il file risiede altrove (S3, Azure, web pubblico); evita lo spostamento dei byte e riduce la banda. Usa URL firmati per asset privati.
GCS / Oggetti registrati — ideale quando i tuoi dati sono già su Google Cloud e vuoi un pattern di produzione con riferimenti stabili e controlli IAM.
Files API — usa per file persistenti o molto grandi che vuoi riutilizzare su più richieste; nota le quote per file e progetto e le policy di ritenzione/temporaneità.

Sicurezza e privacy

URL firmati: gli URL pre-firmati dovrebbero essere generati con durata limitata e permessi ristretti. Non inserire segreti a lunga durata nelle richieste.
IAM & OAuth: per l’accesso diretto a GCS, imposta service account con principio del minimo privilegio (objectViewer per accesso in lettura). Segui le best practice della tua organizzazione per rotazione chiavi e logging.
Residenza dei dati & conformità: quando lasci che l’API recuperi contenuti esterni, assicurati che ciò sia conforme alle tue policy di gestione dati e ai requisiti normativi (alcuni dati regolamentati non devono essere inviati a un servizio esterno, anche temporaneamente). Il provider del modello può persistere metadati sulle richieste nei log — consideralo nella tua analisi di privacy.

Cavilli operativi

Storage transitorio della Files API: i file caricati nella Files API possono essere effimeri (storicamente 48 ore); per storage a lungo termine usa GCS o altri archivi durevoli e riferiscili direttamente.
Recuperi ripetuti: se un file viene referenziato tramite URL ad ogni richiesta e usato frequentemente, potresti incorrere in overhead di recupero ripetuto; considera caching o la registrazione di una copia su GCS per riusi intensi.

Come cambia l’architettura dell’app — esempi pratici

Caso d’uso — assistente di conoscenza incentrato sui documenti

Se gestisci un assistente interno che legge manuali di prodotto archiviati in GCS, registra quegli oggetti GCS una volta (o punta agli URI gs://) e interrogali dinamicamente. Questo evita di ricaricare ripetutamente gli stessi PDF e mantiene il tuo backend più semplice. Usa Files API/registrazione GCS per manuali molto grandi (>100 MB).

Caso d’uso — app mobile consumer che invia foto

Per un’app mobile che invia immagini per didascalie “one-shot”, usa bytes inline per immagini piccole (<100 MB). Mantiene la UX semplice ed evita un secondo passaggio di upload. Se gli utenti riutilizzeranno o condivideranno spesso la stessa immagine, archiviala in GCS e passa un gs:// o un URL firmato.

Caso d’uso — pipeline di trascrizione audio

Note vocali brevi (<100 MB / < ~1 minuto a seconda del codec) possono essere passate inline o tramite URL firmato. Per registrazioni lunghe, carica tramite Files API e riferisci il file nelle chiamate di generazione successive per un riuso efficiente. I flussi video/audio spesso hanno ulteriori note di best practice nella documentazione media.

Conclusione

L’aggiornamento della Gemini API rende molto più semplice portare dati “esistenti” nei flussi di lavoro di AI generativa: il recupero diretto da URL pubblici o firmati e la registrazione GCS rimuovono un frequente punto di frizione operativo, e il salto da 20 MB → 100 MB per i payload inline offre agli ingegneri maggiore flessibilità per flussi semplici e di singola richiesta. Per file longevi, molto grandi o riutilizzati ripetutamente, la Files API (2 GB per file, storage predefinito di 48 ore)

Per iniziare, esplora la Gemini API tramite CometAPI, le funzionalità di Gemini 3 Pro e gemini 3 flash nel Playground e consulta la guida API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l’accesso a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore rispetto a quello ufficiale per aiutarti nell’integrazione.

Pronto a iniziare?→ Prova gratuita di Gemini 3 Pro !