Repository Public
1# File input methods23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67This guide explains the different ways you can include media files such as8images, audio, video, and documents when making requests to the Gemini API.9The new methods are supported in all of the Gemini API endpoints, including10Batch, Interactions and Live API.11Choosing the right method depends on the size of your file, where your data is12stored, and how frequently you plan to use the file.1314The simplest way to include a file as your input is to read a local file and15include it in a prompt. The following example shows how to read a local PDF16file. PDFs are limited to 50MB for this method. See the17[Input method comparison table](https://ai.google.dev/gemini-api/docs/interactions/file-input-methods#method-comparison) for a complete list of file18input types and limits.1920### Python2122 from google import genai23 import pathlib24 import base642526 client = genai.Client()2728 filepath = pathlib.Path('my_local_file.pdf')2930 prompt = "Summarize this document"31 interaction = client.interactions.create(32 model="gemini-3.5-flash",33 input=[34 {"type": "text", "text": prompt},35 {"type": "document", "data": base64.b64encode(filepath.read_bytes()).decode('utf-8'), "mime_type": "application/pdf"}36 ]37 )38 print(interaction.output_text)3940### JavaScript4142 import { GoogleGenAI } from "@google/genai";43 import * as fs from 'node:fs';4445 const client = new GoogleGenAI({});46 const prompt = "Summarize this document";4748 async function main() {49 const filePath = 'my_local_file.pdf';5051 const interaction = await client.interactions.create({52 model: "gemini-3.5-flash",53 input: [54 { type: "text", text: prompt },55 {56 type: "document",57 data: fs.readFileSync(filePath).toString("base64"),58 mime_type: "application/pdf"59 }60 ]61 });62 console.log(interaction.output_text);63 }6465 main();6667### REST6869 # Encode the local file to base6470 B64_CONTENT=$(base64 -w 0 my_local_file.pdf)7172 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \73 -H "x-goog-api-key: $GEMINI_API_KEY" \74 -H 'Content-Type: application/json' \75 -H "Api-Revision: 2026-05-20" \76 -d '{77 "model": "gemini-3.5-flash",78 "input": [79 {"type": "text", "text": "Summarize this document"},80 {81 "type": "document",82 "data": "'${B64_CONTENT}'",83 "mime_type": "application/pdf"84 }85 ]86 }'8788## Input method comparison8990The following table compares each input method with file limits and best use91cases. Note that the file size limit may vary depending on the file type and92model or tokenizer used to process the file.9394| Method | Best for | Max file size | Persistence |95|---|---|---|---|96| **Inline data** | Quick testing, small files, real-time applications. | 100 MB per request or payload (**50 MB for PDFs**) | None (sent with every request) |97| **File API upload** | Large files, files used multiple times. | 2 GB per file, up to 20GB per project | 48 Hours |98| **File API GCS URI registration** | Large files already in Google Cloud Storage, files used multiple times. | 2 GB per file, no overall storage limits | None (fetched per request). One time registration can give access for up to 30 days. |99| **External URLs** | Public data or data in cloud buckets (AWS, Azure, GCS) without re-uploading. | 100 MB per request/payload | None (fetched per request) |100101## Inline data102103For smaller files (under 100MB, or 50MB for PDFs), you can pass the data104directly in the request payload. This is the simplest method for quick tests or105applications handling real-time, transient data. You can provide data as106base64 encoded strings or by reading local files directly.107108For an example of reading from a local file, see the example at the beginning of109this page.110111### Fetch from a URL112113You can also fetch a file from a URL, convert it to bytes, and include it in the114input.115116### Python117118 from google import genai119 import httpx120 import base64121122 client = genai.Client()123124 doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"125 doc_data = httpx.get(doc_url).content126127 prompt = "Summarize this document"128129 interaction = client.interactions.create(130 model="gemini-3.5-flash",131 input=[132 {"type": "document", "data": base64.b64encode(doc_data).decode('utf-8'), "mime_type": "application/pdf"},133 {"type": "text", "text": prompt}134 ]135 )136 print(interaction.output_text)137138### JavaScript139140 import { GoogleGenAI } from "@google/genai";141142 const client = new GoogleGenAI({});143 const docUrl = 'https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf';144 const prompt = "Summarize this document";145146 async function main() {147 const pdfResp = await fetch(docUrl)148 .then((response) => response.arrayBuffer());149150 const interaction = await client.interactions.create({151 model: "gemini-3.5-flash",152 input: [153 { type: "text", text: prompt },154 {155 type: "document",156 data: Buffer.from(pdfResp).toString("base64"),157 mime_type: "application/pdf"158 }159 ]160 });161 console.log(interaction.output_text);162 }163164 main();165166### REST167168 DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"169 PROMPT="Summarize this document"170 DISPLAY_NAME="base64_pdf"171172 # Download the PDF173 wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"174175 # Check for FreeBSD base64 and set flags accordingly176 if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then177 B64FLAGS="--input"178 else179 B64FLAGS="-w0"180 fi181182 # Base64 encode the PDF183 ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")184185 # Create JSON payload file186 cat <<EOF > payload.json187 {188 "model": "gemini-3.5-flash",189 "input": [190 {"type": "document", "data": "${ENCODED_PDF}", "mime_type": "application/pdf"},191 {"type": "text", "text": "${PROMPT}"}192 ]193 }194 EOF195196 # Generate content using interactions197 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \198 -H "x-goog-api-key: $GEMINI_API_KEY" \199 -H 'Content-Type: application/json' \200 -H "Api-Revision: 2026-05-20" \201 -d @payload.json 2> /dev/null > response.json202203 cat response.json204 echo205206 jq ".outputs[] | select(.type == \"text\") | .text" response.json207208## Gemini File API209210The File API is designed for larger files (up to 2GB) or files you intend to211use in multiple requests.212213### Standard file upload214215Upload a local file to the Gemini API. Files uploaded this way are stored216temporarily (48 hours) and processed for efficient retrieval by the model.217218### Python219220 from google import genai221222 client = genai.Client()223224 doc_file = client.files.upload(file="path/to/your/sample.pdf")225 prompt = "Summarize this document"226227 interaction = client.interactions.create(228 model="gemini-3.5-flash",229 input=[230 {"type": "text", "text": prompt},231 {"type": "document", "uri": doc_file.uri, "mime_type": doc_file.mime_type}232 ]233 )234 print(interaction.output_text)235236### JavaScript237238 import { GoogleGenAI } from "@google/genai";239240 const client = new GoogleGenAI({});241 const prompt = "Summarize this document";242243 async function main() {244 const filePath = "path/to/your/sample.pdf";245246 const myfile = await client.files.upload({247 file: filePath,248 config: { mime_type: "application/pdf" },249 });250251 const interaction = await client.interactions.create({252 model: "gemini-3.5-flash",253 input: [254 { type: "text", text: prompt },255 { type: "document", uri: myfile.uri, mime_type: myfile.mimeType }256 ]257 });258 console.log(interaction.output_text);259 }260261 await main();262263### REST264265 FILE_PATH="path/to/sample.pdf"266 MIME_TYPE=$(file -b --mime-type "${FILE_PATH}")267 NUM_BYTES=$(wc -c < "${FILE_PATH}")268 DISPLAY_NAME=DOCUMENT269270 tmp_header_file=upload-header.tmp271272 # Initial resumable request defining metadata.273 curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \274 -D "${tmp_header_file}" \275 -H "x-goog-api-key: $GEMINI_API_KEY" \276 -H "X-Goog-Upload-Protocol: resumable" \277 -H "X-Goog-Upload-Command: start" \278 -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \279 -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \280 -H "Content-Type: application/json" \281 -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null282283 upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")284 rm "${tmp_header_file}"285286 # Upload the actual bytes.287 curl "${upload_url}" \288 -H "Content-Length: ${NUM_BYTES}" \289 -H "X-Goog-Upload-Offset: 0" \290 -H "X-Goog-Upload-Command: upload, finalize" \291 --data-binary "@${FILE_PATH}" 2> /dev/null > file_info.json292293 file_uri=$(jq ".file.uri" file_info.json)294295 # Now use in an interaction296 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \297 -H "x-goog-api-key: $GEMINI_API_KEY" \298 -H 'Content-Type: application/json' \299 -H "Api-Revision: 2026-05-20" \300 -d '{301 "model": "gemini-3.5-flash",302 "input": [303 {"type": "text", "text": "Summarize this document"},304 {"type": "document", "uri": '$file_uri', "mime_type": "'${MIME_TYPE}'"}305 ]306 }'307308### Register Google Cloud Storage files309310If your data is already in Google Cloud Storage, you don't need to311download and re-upload it. You can register it directly with the File API.3123131. Grant **Service Agent** access to each bucket314315 1. Enable the Gemini API in your Google Cloud project.316317 2. Create the Service Agent:318319 `gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>`320 3. **Grant the Gemini API Service Agent permissions** to read your storage321 buckets.322323 The user needs to assign the `Storage Object Viewer`324 [IAM role](https://docs.cloud.google.com/storage/docs/access-control/iam-roles#storage.objectViewer)325 to this service agent on the specific storage buckets they intend to use.326327 This access doesn't expire by default, but can be changed at any time. You can328 also use the329 [Google Cloud Storage IAM SDK](https://cloud.google.com/iam/docs/write-policy-client-libraries)330 commands to grant permissions.3312. Authenticate your service332333 **Prerequisites**334 - Enable API335 - Create a service account or agent with appropriate permissions.336337 You first need to authenticate as the service that has storage object viewer338 permissions. How this happens depends on the environment in which your file339 management code will be running.340341 **Outside of Google Cloud**342343 If your code is running from outside of Google Cloud, such as your desktop,344 download the account credentials from the Google Cloud Console with the345 following steps:346 1. Browse to the [Service Account console](https://console.cloud.google.com/iam-admin/serviceaccounts)347 2. Select the relevant service account348 3. Select the **Keys** tab and choose **Add key, Create new key**349 4. Choose the **JSON** key type, and note where the file was downloaded to on your machine.350351 For more details, see the official Google Cloud documentation on352 [service account key management](https://docs.cloud.google.com/iam/docs/keys-create-delete).353354 Then use the following commands to authenticate. These commands assume your355 service account file is in the current directory, named356 `service-account.json`.357358 ### Python359360 from google.oauth2.service_account import Credentials361362 GCS_READ_SCOPES = [ 363 'https://www.googleapis.com/auth/devstorage.read_only',364 'https://www.googleapis.com/auth/cloud-platform'365 ]366367 SERVICE_ACCOUNT_FILE = 'service-account.json'368369 credentials = Credentials.from_service_account_file(370 SERVICE_ACCOUNT_FILE,371 scopes=GCS_READ_SCOPES372 )373374 ### Javascript375376 const { GoogleAuth } = require('google-auth-library');377378 const GCS_READ_SCOPES = [379 'https://www.googleapis.com/auth/devstorage.read_only',380 'https://www.googleapis.com/auth/cloud-platform'381 ];382383 const SERVICE_ACCOUNT_FILE = 'service-account.json';384385 const auth = new GoogleAuth({386 keyFile: SERVICE_ACCOUNT_FILE,387 scopes: GCS_READ_SCOPES388 });389390 ### CLI391392 gcloud auth application-default login \393 --client-id-file=service-account.json \394 --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only'395396 **On Google Cloud**397398 If you are running directly in Google Cloud, for example by using [Cloud399 Run functions](https://cloud.google.com/functions) or a400 [Compute Engine instance](https://cloud.google.com/products/compute), you will401 have implicit credentials but will need to re-authenticate to grant the402 appropriate scopes.403404 ### Python405406 This code expects that the service is running in an environment where407 [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials)408 can be obtained automatically, such as Cloud Run or Compute Engine.409410 import google.auth411412 GCS_READ_SCOPES = [ 413 'https://www.googleapis.com/auth/devstorage.read_only',414 'https://www.googleapis.com/auth/cloud-platform'415 ]416417 credentials, project = google.auth.default(scopes=GCS_READ_SCOPES)418419 ### JavaScript420421 This code expects that the service is running in an environment where422 [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials)423 can be obtained automatically, such as Cloud Run or Compute Engine.424425 const { GoogleAuth } = require('google-auth-library');426427 const auth = new GoogleAuth({428 scopes: [429 'https://www.googleapis.com/auth/devstorage.read_only',430 'https://www.googleapis.com/auth/cloud-platform'431 ]432 });433434 ### CLI435436 This is an interactive command. For services like Compute Engine you can attach scopes to437 the running service at the config level. See the [user-managed service438 docs](https://docs.cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#using)439 for an example.440441 gcloud auth application-default login \442 --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"4434443. File registration (Files API)445446 Use the Files API to register files and produce a Files API path that can447 directly be used in the Gemini API.448449 ### Python450451 from google import genai452453 client = genai.Client(credentials=credentials)454455 registered_gcs_files = client.files.register_files(456 uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]457 )458 prompt = "Summarize this file."459460 for f in registered_gcs_files.files:461 print(f.name)462 interaction = client.interactions.create(463 model="gemini-3.5-flash",464 input=[465 {"type": "text", "text": prompt},466 {"type": "document", "uri": f.uri, "mime_type": f.mime_type}467 ],468 )469 print(interaction.output_text)470471 ### JavaScript472473 import { GoogleGenAI } from "@google/genai";474475 const ai = new GoogleGenAI({ auth: auth });476477 async function main() {478 const registeredGcsFiles = await ai.files.registerFiles({479 uris: ["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]480 });481482 const prompt = "Summarize this file.";483484 for (const file of registeredGcsFiles.files) {485 console.log(file.name);486 const interaction = await ai.interactions.create({487 model: "gemini-3.5-flash",488 input: [489 { type: "text", text: prompt },490 { type: "document", uri: file.uri, mime_type: file.mimeType }491 ]492 });493494 console.log(interaction.output_text);495 }496 }497498 main();499500 ### CLI501502 access_token=$(gcloud auth application-default print-access-token)503 project_id=$(gcloud config get-value project)504 curl -X POST https://generativelanguage.googleapis.com/v1beta/files:register \505 -H 'Content-Type: application/json' \506 -H "Authorization: Bearer ${access_token}" \507 -H "x-goog-user-project: ${project_id}" \508 -d '{"uris": ["gs://bucket/object1", "gs://bucket/object2"]}'509510## External HTTP / Signed URLs511512You can pass publicly accessible HTTPS URLs or pre-signed URLs directly in your513request. The Gemini API will fetch the content securely during processing.514This is ideal for files up to 100MB that you don't want to re-upload.515516> [!NOTE]517> **Note:** Gemini 2.0 family of models are not supported518519### Python520521 from google import genai522523 uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"524 prompt = "Summarize this file"525526 client = genai.Client()527528 interaction = client.interactions.create(529 model="gemini-3.5-flash",530 input=[531 {"type": "document", "uri": uri, "mime_type": "application/pdf"},532 {"type": "text", "text": prompt}533 ]534 )535 print(interaction.output_text)536537### Javascript538539 import { GoogleGenAI } from '@google/genai';540541 const client = new GoogleGenAI({});542543 const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";544545 async function main() {546 const interaction = await client.interactions.create({547 model: 'gemini-3.5-flash',548 input: [549 { type: "document", uri: uri, mime_type: "application/pdf" },550 { type: "text", text: "summarize this file" }551 ]552 });553554 console.log(interaction.output_text);555 }556557 main();558559### REST560561 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \562 -H 'x-goog-api-key: $GEMINI_API_KEY' \563 -H 'Content-Type: application/json' \564 -H "Api-Revision: 2026-05-20" \565 -d '{566 "model": "gemini-3.5-flash",567 "input": [568 {"type": "text", "text": "Summarize this pdf"},569 {570 "type": "document",571 "uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",572 "mime_type": "application/pdf"573 }574 ]575 }'576577### Accessibility578579Verify that the URLs you provide don't lead to pages that require a login or580are behind a paywall. For private databases, ensure you create a signed URL581with the correct access permissions and expiry.582583### Safety checks584585The system performs a content moderation check on the URL to confirm they meet586safety and policy standards. If the URL fails this check, you will get an587`url_retrieval_status` of `URL_RETRIEVAL_STATUS_UNSAFE`.588589### Supported content types590591This list of supported file types and limitations is intended as initial592guidance and is not comprehensive. The effective593set of supported types is subject to change and can vary based on the specific594model and tokenizer version in use. Unsupported types will result in an error.595Additionally, content retrieval for these file types596only supports publicly accessible URLs.597598#### Text file types599600- `text/html`601- `text/css`602- `text/plain`603- `text/xml`604- `text/csv`605- `text/rtf`606- `text/javascript`607608#### Application file types609610- `application/json`611- `application/pdf`612613#### Image file types614615- `image/bmp`616- `image/jpeg`617- `image/png`618- `image/webp`619620## Best practices621622- **Choose the right method:** Use inline data for small, transient files. Use the File API for larger or frequently used files. Use external URLs for data already hosted online.623- **Specify MIME Types:** Always provide the correct MIME type for the file data to ensure proper processing.624- **Handle Errors:** Implement error handling in your code to manage potential issues like network failures, file access problems, or API errors.625626## Limitations627628- File size limits vary by method (see [comparison table](https://ai.google.dev/gemini-api/docs/interactions/file-input-methods#method-comparison)) and file type.629- Inline data increases request payload size.630- File API uploads are temporary and expire after 48 hours.631- External URL fetching is limited to 100MB per payload and supports specific content types.632633## What's next634635- Try writing your own multimodal prompts using [Google AI Studio](http://aistudio.google.com/).636- For information on including files in your prompts, see the [Vision](https://ai.google.dev/gemini-api/docs/interactions/vision), [Audio](https://ai.google.dev/gemini-api/docs/interactions/audio), and [Document processing](https://ai.google.dev/gemini-api/docs/interactions/document-processing) guides.