Gemini File API

Upload and manage files for use with Gemini models through executable scripts, supporting images, audio, video, PDFs, and other file types.

When to Use This Skill

Use this skill when you need to:

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.js

Purpose: Upload files to Gemini File API

When to use:

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

Key parameters:

Parameter	Description	Example
`path`	File path (required)	`image.jpg`
`--name`, `-n`	Display name	`"my-document"`
`--wait`, `-w`	Wait for processing	Flag

Output: File name, URI, and status information

Workflows

Workflow 1: Basic File Upload

node scripts/upload.js 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

node scripts/upload.js 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

node scripts/upload.js 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
node scripts/upload.js photo.png --name "product-shot"

# 2. Use with gemini-text for analysis
node skills/gemini-text/scripts/generate.js "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
node scripts/upload.js research-paper.pdf --name "AI-Research-Paper" --wait

# 2. Extract content with gemini-text
node skills/gemini-text/scripts/generate.js "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
    node scripts/upload.js "$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
node scripts/upload.js interview.mp3 --name "interview-001" --wait

# 2. Process with gemini-text (if transcription available)
node skills/gemini-text/scripts/generate.js "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)
node scripts/upload.js product-demo.mp4 --name "demo-video" --wait

# 2. Analyze with gemini-text
node skills/gemini-text/scripts/generate.js "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

Type	Extensions	Max Size	Processing Time
Images	jpg, jpeg, png, gif, webp	20MB	Seconds
Audio	mp3, wav, aac, flac	25MB	Seconds-minutes
Video	mp4, mov, avi, webm	2GB	Minutes-hours
Documents	pdf, txt	50MB	Seconds-minutes

MIME Types

Script auto-detects based on extension:

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

State	Description	Ready for Use
`PROCESSING`	File is being analyzed	No
`ACTIVE`	File is ready	Yes
`FAILED`	Processing failed	No

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

Once uploaded, reference file by name:

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

Common Issues

"google-genai not installed"

npm install @google/genai@latest dotenv@latest

"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
node scripts/upload.js image.jpg

# With custom name
node scripts/upload.js document.pdf --name "My Document"

# Wait for processing
node scripts/upload.js video.mp4 --wait

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

File Management API

While not in scripts, you can also manage files via JavaScript:

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// List all files
for await (const file of client.files.list()) {
  console.log(`${file.name}: ${file.displayName} (${file.state})`);
}

// Get file info
const file = await client.files.get({ name: "files/abc123..." });
console.log(`State: ${file.state}`);

// Delete file
await 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)

gemini-files