Files - Crewai — ContextQMD

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"),
    }
)