Gemini File API

When to Use This Skill

• Upload images for multimodal analysis
• Upload videos for content processing
• Upload PDFs for document analysis
• Upload audio for transcription or processing
• Pre-upload files for batch operations
• Check file processing status
• List and manage uploaded files
• Use files with other Gemini skills (text, image, etc.)

Available Scripts

scripts/upload.py

• Uploading any file for Gemini processing
• Preparing files for multimodal generation
• Uploading documents for analysis
• Batch file preparation

path

image.jpg

--name

-n

"my-document"

--wait

-w

Workflows

Workflow 1: Basic File Upload

python scripts/upload.py image.jpg

• Best for: Quick uploads, simple files
• Output: File name and URI for API use
• State: PROCESSING or ACTIVE

Workflow 2: Upload with Custom Name

python scripts/upload.py document.pdf --name "Quarterly Report Q4 2026"

• Best for: Organizing files, tracking uploads
• Use when: Original filename not descriptive enough
• Display name appears in file listings

Workflow 3: Upload and Wait for Processing

python scripts/upload.py video.mp4 --wait

• Best for: Large files, videos, audio
• Waits for file to be ACTIVE state
• Use when: You need to use file immediately after upload

Workflow 4: Upload Image for Analysis

# 1. Upload image
python scripts/upload.py photo.png --name "product-shot"

# 2. Use with gemini-text for analysis
python skills/gemini-text/scripts/generate.py "Describe this image" --image photo.png

• Best for: Image analysis, captioning, visual Q&A
• Combines with: gemini-text for multimodal processing

Workflow 5: Upload PDF for Content Extraction

# 1. Upload PDF
python scripts/upload.py research-paper.pdf --name "AI-Research-Paper" --wait

# 2. Extract content with gemini-text
python skills/gemini-text/scripts/generate.py "Extract key findings from this document" --image research-paper.pdf

• Best for: Document processing, content extraction
• Combines with: gemini-text for analysis

Workflow 6: Upload Multiple Files for Batch

# 1. Upload multiple files
for file in *.jpg; do
    python scripts/upload.py "$file"
done

# 2. Create batch job using uploaded files (gemini-batch skill)

• Best for: Preparing files for batch processing
• Combines with: gemini-batch for bulk operations

Workflow 7: Upload Audio for Transcription

# 1. Upload audio
python scripts/upload.py interview.mp3 --name "interview-001" --wait

# 2. Process with gemini-text (if transcription available)
python skills/gemini-text/scripts/generate.py "Transcribe and summarize this audio" --image interview.mp3

• Best for: Audio processing, transcription, podcast analysis
• Combines with: gemini-text for audio analysis

Workflow 8: Upload Video for Content Analysis

# 1. Upload video (may take time)
python scripts/upload.py product-demo.mp4 --name "demo-video" --wait

# 2. Analyze with gemini-text
python skills/gemini-text/scripts/generate.py "Analyze this product demo video" --image product-demo.mp4

• Best for: Video analysis, content summarization
• Note: Videos may require significant processing time

Parameters Reference

Supported File Types

MIME Types

• Images: image/jpeg, image/png, image/gif, image/webp
• Audio: audio/mpeg, audio/wav
• Video: video/mp4, video/quicktime, video/webm
• Documents: application/pdf, text/plain

File States

PROCESSING

ACTIVE

FAILED

Output Interpretation

Upload Response

Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING

• File name: Use in API calls
• URI: Internal Google Cloud Storage reference
• State: PROCESSING = wait, ACTIVE = ready

With --wait Flag

Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!

• Script polls until state is ACTIVE
• Use for large files requiring processing
• May take minutes for videos

Using Uploaded Files

# With gemini-text
python skills/gemini-text/scripts/generate.py "Analyze" --image <uploaded-file-path>

Common Issues

"google-genai not installed"

pip install google-genai

"File not found"

• Verify file path is correct
• Use absolute paths if relative paths fail
• Check file extension matches supported types

"File too large"

• Check size limits for file type
• Compress images/videos if possible
• Split large files into smaller parts

"Unsupported file type"

• Check supported extensions
• Convert to supported format if possible
• Images: jpg, png, gif, webp
• Videos: mp4, mov, avi, webm

"Processing failed"

• Check file is not corrupted
• Try re-uploading the file
• Verify file format is valid
• Check API quota limits

"File still processing" (without --wait)

• File state is PROCESSING, not ACTIVE
• Use

  --wait

  flag or check status later
• Large files (especially videos) take time
• Processing can take minutes to hours

Best Practices

Upload Strategy

• Use

  --wait

  for files you'll use immediately
• Skip

  --wait

  for batch uploads to save time
• Use descriptive

  --name

  for organization
• Keep track of file names for later use

File Organization

• Use consistent naming conventions
• Include dates or versions in names
• Group related files together
• Document file names in your code

Performance Tips

• Upload multiple files in parallel (separate processes)
• Pre-upload files for batch operations
• Check file state before using in API calls
• Delete old files to manage storage

Error Handling

• Check return state after upload
• Retry failed uploads
• Verify file integrity before upload
• Log file names for audit trails

Integration with Other Skills

• gemini-text: Multimodal analysis, document processing
• gemini-image: Generate images based on uploaded reference
• gemini-batch: Use uploaded files in batch jobs
• gemini-embeddings: Create embeddings from file content

File Lifecycle

• Upload → PROCESSING → ACTIVE → Use in API
• Delete old files to free storage
• Files may expire after certain period
• Download important files for backup

Related Skills

• gemini-text: Analyze uploaded files with text generation
• gemini-image: Create images based on uploaded references
• gemini-batch: Use uploaded files in batch processing
• gemini-embeddings: Generate embeddings from file content

Quick Reference

# Basic upload
python scripts/upload.py image.jpg

# With custom name
python scripts/upload.py document.pdf --name "My Document"

# Wait for processing
python scripts/upload.py video.mp4 --wait

# Multiple files
for file in *.jpg; do python scripts/upload.py "$file"; done

File Management API

from google import genai

client = genai.Client()

# List all files
for file in client.files.list():
    print(f"{file.name}: {file.display_name} ({file.state})")

# Get file info
file = client.files.get(name="files/abc123...")
print(f"State: {file.state}")

# Delete file
client.files.delete(name="files/abc123...")

Reference

• Get API key: https://aistudio.google.com/apikey
• Documentation: https://ai.google.dev/gemini-api/docs/file-upload
• File API: https://ai.google.dev/gemini-api/docs/files
• Supported formats: Images, audio, video, documents (see table above)