Back to Details

gemini-files

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gemini File API

Gemini File API

Upload and manage files for use with Gemini models through executable scripts, supporting images, audio, video, PDFs, and other file types.
通过可执行脚本上传和管理供Gemini模型使用的文件，支持图片、音频、视频、PDF及其他文件类型。

When to Use This Skill

何时使用该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.)
在以下场景中使用本Skill：
  • 上传图片用于多模态分析
  • 上传视频用于内容处理
  • 上传PDF用于文档分析
  • 上传音频用于转录或处理
  • 预上传文件以进行批量操作
  • 检查文件处理状态
  • 列出并管理已上传的文件
  • 与其他Gemini Skill（文本、图片等）结合使用文件

Available Scripts

可用脚本

scripts/upload.py

scripts/upload.py

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:
ParameterDescriptionExample
path
File path (required)
image.jpg
--name
, 
-n
Display name
"my-document"
--wait
, 
-w
Wait for processingFlag
Output: File name, URI, and status information
用途：将文件上传至Gemini File API
适用场景:
  • 上传任意文件供Gemini处理
  • 为多模态生成准备文件
  • 上传文档进行分析
  • 批量文件准备
关键参数:
参数描述示例
path
文件路径（必填）
image.jpg
--name
, 
-n
显示名称
"my-document"
--wait
, 
-w
等待处理完成标志位
输出：文件名、URI和状态信息

Workflows

工作流

Workflow 1: Basic File Upload

工作流1：基础文件上传

bash
python scripts/upload.py image.jpg
  • Best for: Quick uploads, simple files
  • Output: File name and URI for API use
  • State: PROCESSING or ACTIVE
bash
python scripts/upload.py image.jpg
  • 最佳适用：快速上传、简单文件
  • 输出：供API调用的文件名和URI
  • 状态：PROCESSING（处理中）或ACTIVE（可用）

Workflow 2: Upload with Custom Name

工作流2：自定义名称上传

bash
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
bash
python scripts/upload.py document.pdf --name "Quarterly Report Q4 2026"
  • 最佳适用：整理文件、跟踪上传记录
  • 适用场景：原文件名不够直观时
  • 显示名称会出现在文件列表中

Workflow 3: Upload and Wait for Processing

工作流3：上传并等待处理完成

bash
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
bash
python scripts/upload.py video.mp4 --wait
  • 最佳适用：大文件、视频、音频
  • 等待文件进入ACTIVE状态
  • 适用场景：需要在上传后立即使用文件时

Workflow 4: Upload Image for Analysis

工作流4：上传图片用于分析

bash
undefined
bash
undefined

1. Upload image

1. 上传图片

python scripts/upload.py photo.png --name "product-shot"
python scripts/upload.py photo.png --name "product-shot"

2. Use with gemini-text for analysis

2. 结合gemini-text进行分析

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
python skills/gemini-text/scripts/generate.py "Describe this image" --image photo.png
- 最佳适用：图片分析、图像描述、视觉问答
- 结合工具：gemini-text用于多模态处理

Workflow 5: Upload PDF for Content Extraction

工作流5：上传PDF用于内容提取

bash
undefined
bash
undefined

1. Upload PDF

1. 上传PDF

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

2. Extract content with gemini-text

2. 结合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
python skills/gemini-text/scripts/generate.py "Extract key findings from this document" --image research-paper.pdf
- 最佳适用：文档处理、内容提取
- 结合工具：gemini-text用于分析

Workflow 6: Upload Multiple Files for Batch

工作流6：上传多个文件用于批量操作

bash
undefined
bash
undefined

1. Upload multiple files

1. 上传多个文件

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

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

2. 使用已上传文件创建批量任务（gemini-batch skill）

- Best for: Preparing files for batch processing
- Combines with: gemini-batch for bulk operations
- 最佳适用：为批量处理准备文件
- 结合工具：gemini-batch用于批量操作

Workflow 7: Upload Audio for Transcription

工作流7：上传音频用于转录

bash
undefined
bash
undefined

1. Upload audio

1. 上传音频

python scripts/upload.py interview.mp3 --name "interview-001" --wait
python scripts/upload.py interview.mp3 --name "interview-001" --wait

2. Process with gemini-text (if transcription available)

2. 结合gemini-text处理（若支持转录）

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
python skills/gemini-text/scripts/generate.py "Transcribe and summarize this audio" --image interview.mp3
- 最佳适用：音频处理、转录、播客分析
- 结合工具：gemini-text用于音频分析

Workflow 8: Upload Video for Content Analysis

工作流8：上传视频用于内容分析

bash
undefined
bash
undefined

1. Upload video (may take time)

1. 上传视频（可能需要较长时间）

python scripts/upload.py product-demo.mp4 --name "demo-video" --wait
python scripts/upload.py product-demo.mp4 --name "demo-video" --wait

2. Analyze with gemini-text

2. 结合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
python skills/gemini-text/scripts/generate.py "Analyze this product demo video" --image product-demo.mp4
- 最佳适用：视频分析、内容总结
- 注意：视频可能需要大量处理时间

Parameters Reference

参数参考

Supported File Types

支持的文件类型

TypeExtensionsMax SizeProcessing Time
Imagesjpg, jpeg, png, gif, webp20MBSeconds
Audiomp3, wav, aac, flac25MBSeconds-minutes
Videomp4, mov, avi, webm2GBMinutes-hours
Documentspdf, txt50MBSeconds-minutes
类型扩展名最大大小处理时间
图片jpg, jpeg, png, gif, webp20MB数秒
音频mp3, wav, aac, flac25MB数秒至数分钟
视频mp4, mov, avi, webm2GB数分钟至数小时
文档pdf, txt50MB数秒至数分钟

MIME Types

MIME类型

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
脚本会根据扩展名自动检测：
  • 图片：image/jpeg, image/png, image/gif, image/webp
  • 音频：audio/mpeg, audio/wav
  • 视频：video/mp4, video/quicktime, video/webm
  • 文档：application/pdf, text/plain

File States

文件状态

StateDescriptionReady for Use
PROCESSING
File is being analyzedNo
ACTIVE
File is readyYes
FAILED
Processing failedNo
状态描述是否可用
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
Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
  • 文件名：用于API调用
  • URI：Google Cloud Storage内部引用
  • 状态：PROCESSING = 等待，ACTIVE = 就绪

With --wait Flag

使用--wait标志

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
Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!
  • 脚本会轮询直到状态变为ACTIVE
  • 适用于需要处理的大文件
  • 视频可能需要数分钟时间

Using Uploaded Files

使用已上传文件

Once uploaded, reference file by name:
bash
undefined
上传完成后，通过文件名引用文件：
bash
undefined

With gemini-text

结合gemini-text

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

Common Issues

常见问题

"google-genai not installed"

"google-genai not installed"

bash
pip install google-genai
bash
pip install google-genai

"File not found"

"File not found"

  • Verify file path is correct
  • Use absolute paths if relative paths fail
  • Check file extension matches supported types
  • 验证文件路径是否正确
  • 若相对路径失败，使用绝对路径
  • 检查文件扩展名是否在支持列表中

"File too large"

"File too large"

  • Check size limits for file type
  • Compress images/videos if possible
  • Split large files into smaller parts
  • 检查对应文件类型的大小限制
  • 如有可能，压缩图片/视频
  • 将大文件拆分为较小部分

"Unsupported file type"

"Unsupported file type"

  • Check supported extensions
  • Convert to supported format if possible
  • Images: jpg, png, gif, webp
  • Videos: mp4, mov, avi, webm
  • 检查支持的扩展名
  • 如有可能，转换为支持的格式
  • 图片：jpg, png, gif, webp
  • 视频：mp4, mov, avi, webm

"Processing failed"

"Processing failed"

  • Check file is not corrupted
  • Try re-uploading the file
  • Verify file format is valid
  • Check API quota limits
  • 检查文件是否损坏
  • 尝试重新上传文件
  • 验证文件格式是否有效
  • 检查API配额限制

"File still processing" (without --wait)

"File still processing"（未使用--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
  • 文件状态为PROCESSING，而非ACTIVE
  • 使用
    --wait
    标志或稍后检查状态
  • 大文件（尤其是视频）需要较长时间
  • 处理可能需要数分钟至数小时

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
  • 对于需要立即使用的文件，使用
    --wait
  • 批量上传时跳过
    --wait
    以节省时间
  • 使用描述性的
    --name
    来整理文件
  • 记录文件名以便后续使用

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
  • 并行上传多个文件（独立进程）
  • 预上传文件以进行批量操作
  • 在API调用前检查文件状态
  • 删除旧文件以管理存储空间

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

与其他Skill集成

  • 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
  • gemini-text：多模态分析、文档处理
  • gemini-image：基于上传的参考图生成图片
  • gemini-batch：在批量任务中使用已上传文件
  • gemini-embeddings：从文件内容创建嵌入向量

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
  • 上传 → PROCESSING → ACTIVE → 在API中使用
  • 删除旧文件以释放存储空间
  • 文件可能会在一段时间后过期
  • 下载重要文件进行备份

Related Skills

相关Skill

  • 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
  • gemini-text：通过文本生成分析已上传文件
  • gemini-image：基于上传的参考图创建图片
  • gemini-batch：在批量处理中使用已上传文件
  • gemini-embeddings：从文件内容生成嵌入向量

Quick Reference

快速参考

bash
undefined
bash
undefined

Basic upload

基础上传

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

With custom name

自定义名称上传

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

Wait for processing

等待处理完成

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

Multiple files

批量上传文件

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

File Management API

文件管理API

While not in scripts, you can also manage files via Python:
python
from google import genai

client = genai.Client()
虽然未包含在脚本中，你也可以通过Python管理文件：
python
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})")
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}")
file = client.files.get(name="files/abc123...") print(f"State: {file.state}")

Delete file

删除文件

client.files.delete(name="files/abc123...")
undefined
client.files.delete(name="files/abc123...")
undefined

Reference

参考链接