Files ↗
noOriginal Documentation
Documentation Index#
Fetch the complete documentation index at: https://docs.crewai.com/llms.txt Use this file to discover all available pages before exploring further.
Pass images, PDFs, audio, video, and text files to your agents for multimodal processing.
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.
uv add 'crewai[file-processing]'The file processing API is currently in early access.
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 |
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 |
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#
from crewai_files import ImageFile
image = ImageFile(source="./images/chart.png")From URL#
from crewai_files import ImageFile
image = ImageFile(source="https://example.com/image.png")From Bytes#
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:
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:
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:
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:
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_filesFor 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 | 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) | ✓ | ✓ |
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.
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 | ✓ | ✓ |
File Handling Modes#
Control how files are processed when they exceed provider limits:
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:
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"),
}
)