> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/googleapis/python-genai/llms.txt
> Use this file to discover all available pages before exploring further.

# files.upload

> Upload files to the Gemini API for use in prompts

Uploads a file to the Gemini File API, making it available for use in generation requests with large files, videos, or audio.

## Method Signature

```python theme={null}
client.files.upload(
    file: Union[str, os.PathLike[str], io.IOBase],
    config: Optional[UploadFileConfigOrDict] = None
) -> File
```

## Parameters

<ParamField path="file" type="string | PathLike | IOBase" required>
  The file to upload.

  Can be:

  * A file path as a string: `"/path/to/file.pdf"`
  * A PathLike object: `Path("document.pdf")`
  * An IOBase object (file handle): Must be opened in binary mode (`'rb'`) and be seekable

  <Warning>
    When using an IOBase object (file handle), ensure:

    * The file is opened in **binary mode** (not text mode)
    * The file is opened in **blocking mode** (the default)
    * The stream is **seekable** (supports `seek()` operations)
  </Warning>
</ParamField>

<ParamField path="config" type="UploadFileConfig">
  Optional configuration for the upload.

  Available options:

  * `display_name`: Human-readable name for the file
  * `mime_type`: MIME type (auto-detected if not provided)
  * `name`: Custom resource name
  * `http_options`: Custom HTTP request options
</ParamField>

## Returns

<ResponseField name="file" type="File">
  A File object containing:

  * `name`: The resource name (e.g., `"files/abc123"`)
  * `uri`: The URI to reference in API calls
  * `display_name`: Human-readable name
  * `mime_type`: The file's MIME type
  * `size_bytes`: File size in bytes
  * `create_time`: When the file was uploaded
  * `update_time`: Last update time
  * `expiration_time`: When the file will be deleted
  * `state`: Upload state (`PROCESSING`, `ACTIVE`, or `FAILED`)
</ResponseField>

## Examples

### Upload PDF Document

```python theme={null}
from google import genai

client = genai.Client(api_key='your-api-key')

# Upload file
file = client.files.upload(file='research_paper.pdf')

print(f"Uploaded file: {file.name}")
print(f"URI: {file.uri}")
print(f"Size: {file.size_bytes} bytes")
```

### Upload with Display Name

```python theme={null}
# Upload with custom display name
file = client.files.upload(
    file='document.pdf',
    config={'display_name': 'Q4 Financial Report'}
)

print(f"File: {file.display_name}")
print(f"MIME type: {file.mime_type}")
```

### Upload Video File

```python theme={null}
# Upload video
video_file = client.files.upload(
    file='presentation.mp4',
    config={'display_name': 'Product Demo Video'}
)

print(f"Video uploaded: {video_file.name}")
print(f"State: {video_file.state}")
```

### Upload from File Handle

```python theme={null}
# Upload using file handle
with open('data.json', 'rb') as f:
    file = client.files.upload(
        file=f,
        config={
            'display_name': 'User Data',
            'mime_type': 'application/json'
        }
    )

print(f"Uploaded: {file.name}")
```

### Upload and Use in Prompt

```python theme={null}
from google.genai import types

# Upload file
file = client.files.upload(file='annual_report.pdf')

# Wait for processing if needed
import time
while file.state == 'PROCESSING':
    time.sleep(1)
    file = client.files.get(name=file.name)

# Use in generation
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=[
        types.Part(file_data=types.FileData(file_uri=file.uri)),
        'Summarize the key points from this report'
    ]
)

print(response.text)
```

### Upload Multiple Files

```python theme={null}
# Upload multiple documents
file_paths = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf']
files = []

for path in file_paths:
    file = client.files.upload(file=path)
    files.append(file)
    print(f"Uploaded: {file.display_name or file.name}")

# Use all files in one prompt
parts = [
    types.Part(file_data=types.FileData(file_uri=f.uri)) 
    for f in files
]
parts.append('Compare and contrast these documents')

response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=parts
)
print(response.text)
```

### Async Upload

```python theme={null}
import asyncio
from google import genai

client = genai.Client(api_key='your-api-key')

async def upload_example():
    # Upload file asynchronously
    file = await client.aio.files.upload(file='document.pdf')
    print(f"Uploaded: {file.name}")
    return file

asyncio.run(upload_example())
```

### Upload with Custom MIME Type

```python theme={null}
# Explicitly set MIME type
file = client.files.upload(
    file='data.custom',
    config={'mime_type': 'application/octet-stream'}
)
```

### Upload Audio File

```python theme={null}
# Upload audio for transcription or analysis
audio = client.files.upload(
    file='podcast.mp3',
    config={'display_name': 'Podcast Episode 1'}
)

# Use in prompt
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=[
        types.Part(file_data=types.FileData(file_uri=audio.uri)),
        'Transcribe this audio and provide a summary'
    ]
)
print(response.text)
```

## File Lifecycle

<Info>
  Uploaded files are automatically deleted after 48 hours. Plan your workflows accordingly or re-upload files as needed.
</Info>

## Error Handling

```python theme={null}
try:
    file = client.files.upload(file='document.pdf')
    print(f"Success: {file.name}")
except FileNotFoundError:
    print("File not found")
except Exception as e:
    print(f"Upload failed: {e}")
```

## API Availability

<Warning>
  This method is **only available in the Gemini API** (not Vertex AI).

  For Vertex AI, you should:

  * Store files in Google Cloud Storage (GCS)
  * Use `files.register_files()` to register GCS URIs
  * Or use direct GCS URIs in prompts
</Warning>

## Related Methods

* [files.get](/api/files/get) - Retrieve file metadata
* [files.list](/api/files/list) - List uploaded files
* [files.delete](/api/files/delete) - Delete a file
* [files.download](/api/files/download) - Download generated files