Gemini Files API vs. File Search: How to Choose and Integrate

“Gemini file API” can mean two different workflows. Use the Files API to upload a file and attach it to a model request—for example, to summarize a PDF. Use File Search when you want Gemini to retrieve relevant material from a collection of indexed files to answer questions. They are related, but they are not interchangeable. (Files API guide)

Files API vs. File Search: which should you use?

Choose	Best for	What happens to the file
Files API	Sending a file as input to one or more model requests	Upload it, then reference it in a prompt. Uploaded files are available for a limited period.
File Search	Asking questions across a reusable document collection	Import files into a store; Gemini indexes them and retrieves relevant context during a query.

With the Files API, the model works with the file you provide in the request. File Search is a retrieval-augmented generation (RAG) workflow: it imports, chunks, and indexes data, then uses relevant retrieved material as model context. (Files API guide)

Rule of thumb: If your app needs to process a particular upload, start with the Files API. If it needs to answer recurring questions over a knowledge base, evaluate File Search.

Upload a PDF and use it in a Gemini request with Python

This example uses Google’s google-genai Python SDK and the generateContent surface. The Files API guide demonstrates uploading a file and passing the returned file reference in contents; its guide says the basic file operations apply to documents and other supported file types as well. (Files API guide)

1. Install the SDK and configure your API key

pip install -U google-genai

Set GEMINI_API_KEY in your environment before running the program. The SDK reads the key when it creates the client. Keep the key on your server; do not expose it in browser or mobile-app code. (API key guide)

2. Upload the PDF and generate a response

from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="report.pdf")

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Summarize this report in five bullet points.", uploaded_file],
)

print(response.text)

Replace report.pdf with the path to the PDF you want to process. client.files.upload returns the file reference; pass that reference in contents alongside your prompt. The Files API guide demonstrates an upload followed by a generateContent call without a separate polling step in that example. It does not explicitly state that every PDF upload or model request is guaranteed to need no readiness handling. You can call client.files.get(name=uploaded_file.name) to retrieve the stored file’s metadata. (Files API guide)

PDF size and page limits: Google’s Files API guide states a 50 MB limit for PDF files. The separate Files API storage quota is 2 GB per file and 20 GB per project; that storage maximum is not the same as the PDF limit for model processing. Google’s document guide describes PDF processing for documents up to 1,000 pages, subject to applicable file-size and model/input constraints. (Files API guide; document understanding guide)

When File Search is the better fit

Choose File Search when users need to ask questions across multiple documents, rather than pass one particular file with each request. Its integration has three main steps: (File Search guide)

1. Create a File Search store; the returned store resource has a name you will use in later calls.
2. Upload files directly to that store or import uploaded files, then wait for the ingestion operation to finish before querying.
3. Call generate_content with a file_search tool configured with the store name, so Gemini can retrieve from that store while generating its answer. Google’s announcement demonstrates this store-and-tool pattern. (File Search guide)

For example, File Search fits a product-manual collection where users ask, “Which manual explains how to reset the device?” For a single manual that needs a one-time summary, the Files API is the more direct choice.

File Search also supports text and image/multimodal retrieval, custom metadata filters, and page-level citations; audio and video formats are not currently supported. The full File Search guide contains the current SDK examples and conditions. (File Search guide)

File limits and lifecycle

For the Files API, Google documents a maximum of 2 GB per file, up to 20 GB of files per project, and automatic deletion after 48 hours. Files can also be deleted manually. These are Files API storage limits—not File Search store limits. (Files API guide)

File Search has a different lifecycle: Google’s File Search documentation says data imported into a store remains there until you manually delete it. Do not assume the Files API’s 48-hour expiry also cleans up File Search data; manage deletion of the store separately. (File Search guide)

Bottom line

Use Files API + generateContent to upload a file and use it as input to a model request. Use File Search for indexed retrieval over a reusable collection. Keep their input limits and retention behavior separate, and keep API credentials out of client-side code.

Sources

Files API - Gemini API | Google AI Studio

Document understanding | Gemini API | Google AI for Developers

Gemini 3.8 Flash | Gemini API | Google AI for Developers

File search - Gemini API | Google AI Studio

Using Gemini API keys | Google AI for Developers

Gemini API File Search is now multimodal