crewAI/docs/en/concepts/files.mdx

---
title: Files
description: Pass images, PDFs, audio, video, and text files to your agents for multimodal processing.
icon: file-image
---

## Overview

CrewAI supports native multimodal file inputs, allowing you to pass images, PDFs, audio, video, and text files directly to your agents. Files are automatically formatted for each LLM provider's API requirements.

<Note type="info" title="Optional Dependency">
File support requires the optional `crewai-files` package. Install it with:

```bash
uv add 'crewai[file-processing]'
```
</Note>

<Note type="warning" title="Early Access">
The file processing API is currently in early access.
</Note>

## File Types

CrewAI supports five specific file types plus a generic `File` class that auto-detects the type:

| Type | Class | Use Cases |
|:-----|:------|:----------|
| **Image** | `ImageFile` | Photos, screenshots, diagrams, charts |
| **PDF** | `PDFFile` | Documents, reports, papers |
| **Audio** | `AudioFile` | Voice recordings, podcasts, meetings |
| **Video** | `VideoFile` | Screen recordings, presentations |
| **Text** | `TextFile` | Code files, logs, data files |
| **Generic** | `File` | Auto-detect type from content |

```python
from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile

image = ImageFile(source="screenshot.png")
pdf = PDFFile(source="report.pdf")
audio = AudioFile(source="meeting.mp3")
video = VideoFile(source="demo.mp4")
text = TextFile(source="data.csv")

file = File(source="document.pdf")
```

## File Sources

The `source` parameter accepts multiple input types and auto-detects the appropriate handler:

### From Path

```python
from crewai_files import ImageFile

image = ImageFile(source="./images/chart.png")
```

### From URL

```python
from crewai_files import ImageFile

image = ImageFile(source="https://example.com/image.png")
```

### From Bytes

```python
from crewai_files import ImageFile, FileBytes

image_bytes = download_image_from_api()
image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
image = ImageFile(source=image_bytes)
```

## Using Files

Files can be passed at multiple levels, with more specific levels taking precedence.

### With Crews

Pass files when kicking off a crew:

```python
from crewai import Crew
from crewai_files import ImageFile

crew = Crew(agents=[analyst], tasks=[analysis_task])

result = crew.kickoff(
    inputs={"topic": "Q4 Sales"},
    input_files={
        "chart": ImageFile(source="sales_chart.png"),
        "report": PDFFile(source="quarterly_report.pdf"),
    }
)
```

### With Tasks

Attach files to specific tasks:

```python
from crewai import Task
from crewai_files import ImageFile

task = Task(
    description="Analyze the sales chart and identify trends in {chart}",
    expected_output="A summary of key trends",
    input_files={
        "chart": ImageFile(source="sales_chart.png"),
    }
)
```

### With Flows

Pass files to flows, which automatically inherit to crews:

```python
from crewai.flow.flow import Flow, start
from crewai_files import ImageFile

class AnalysisFlow(Flow):
    @start()
    def analyze(self):
        return self.analysis_crew.kickoff()

flow = AnalysisFlow()
result = flow.kickoff(
    input_files={"image": ImageFile(source="data.png")}
)
```

### With Standalone Agents

Pass files directly to agent kickoff:

```python
from crewai import Agent
from crewai_files import ImageFile

agent = Agent(
    role="Image Analyst",
    goal="Analyze images",
    backstory="Expert at visual analysis",
    llm="gpt-4o",
)

result = agent.kickoff(
    messages="What's in this image?",
    input_files={"photo": ImageFile(source="photo.jpg")},
)
```

## File Precedence

When files are passed at multiple levels, more specific levels override broader ones:

```
Flow input_files < Crew input_files < Task input_files
```

For example, if both Flow and Task define a file named `"chart"`, the Task's version is used.

## Provider Support

Different providers support different file types. CrewAI automatically formats files for each provider's API.

| Provider | Image | PDF | Audio | Video | Text |
|:---------|:-----:|:---:|:-----:|:-----:|:----:|
| **OpenAI** (completions API) | ✓ | | | | |
| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | |
| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |

<Note type="info" title="Gemini for Maximum File Support">
Google Gemini models support all file types including video (up to 1 hour, 2GB). Use Gemini when you need to process video content.
</Note>

<Note type="warning" title="Unsupported File Types">
If you pass a file type that the provider doesn't support (e.g., video to OpenAI), you'll receive an `UnsupportedFileTypeError`. Choose your provider based on the file types you need to process.
</Note>

## How Files Are Sent

CrewAI automatically chooses the optimal method to send files to each provider:

| Method | Description | Used When |
|:-------|:------------|:----------|
| **Inline Base64** | File embedded directly in the request | Small files (< 5MB typically) |
| **File Upload API** | File uploaded separately, referenced by ID | Large files that exceed threshold |
| **URL Reference** | Direct URL passed to the model | File source is already a URL |

### Provider Transmission Methods

| Provider | Inline Base64 | File Upload API | URL References |
|:---------|:-------------:|:---------------:|:--------------:|
| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) |
| **Azure OpenAI** | ✓ | | ✓ |

<Note type="info" title="Automatic Optimization">
You don't need to manage this yourself. CrewAI automatically uses the most efficient method based on file size and provider capabilities. Providers without file upload APIs use inline base64 for all files.
</Note>

## File Handling Modes

Control how files are processed when they exceed provider limits:

```python
from crewai_files import ImageFile, PDFFile

image = ImageFile(source="large.png", mode="strict")
image = ImageFile(source="large.png", mode="auto")
image = ImageFile(source="large.png", mode="warn")
pdf = PDFFile(source="large.pdf", mode="chunk")
```

## Provider Constraints

Each provider has specific limits for file sizes and dimensions:

### OpenAI
- **Images**: Max 20 MB, up to 10 images per request
- **PDFs**: Max 32 MB, up to 100 pages
- **Audio**: Max 25 MB, up to 25 minutes

### Anthropic
- **Images**: Max 5 MB, max 8000x8000 pixels, up to 100 images
- **PDFs**: Max 32 MB, up to 100 pages

### Google Gemini
- **Images**: Max 100 MB
- **PDFs**: Max 50 MB
- **Audio**: Max 100 MB, up to 9.5 hours
- **Video**: Max 2 GB, up to 1 hour

### AWS Bedrock
- **Images**: Max 4.5 MB, max 8000x8000 pixels
- **PDFs**: Max 3.75 MB, up to 100 pages

## Referencing Files in Prompts

Use the file's key name in your task descriptions to reference files:

```python
task = Task(
    description="""
    Analyze the provided materials:
    1. Review the chart in {sales_chart}
    2. Cross-reference with data in {quarterly_report}
    3. Summarize key findings
    """,
    expected_output="Analysis summary with key insights",
    input_files={
        "sales_chart": ImageFile(source="chart.png"),
        "quarterly_report": PDFFile(source="report.pdf"),
    }
)
```