Gemini 文件 API 是做什么的？
通过可执行脚本上传和管理用于 Gemini 模型的文件，支持图片、音频、视频、PDF 等文件类型。
何时使用此技能
当您需要执行以下操作时，请使用此技能：
- 上传图片用于多模态分析
- 上传视频用于内容处理
- 上传 PDF 用于文档分析
- 上传音频用于转录或处理
- 预上传文件用于批量操作
- 检查文件处理状态
- 列出和管理已上传的文件
- 与其他 Gemini 技能（文本、图片等）配合使用文件
可用脚本
scripts/upload.py
用途：上传文件至 Gemini 文件 API
使用场景：
- 上传任何文件供 Gemini 处理
- 准备用于多模态生成的文件
- 上传文档供分析
- 批量文件准备
关键参数：
| 参数 | 描述 | 示例 |
|---|---|---|
path | 文件路径（必填） | image.jpg |
--name, -n | 显示名称 | "my-document" |
--wait, -w | 等待处理完成 | 标志位 |
输出：文件名、URI 和状态信息
工作流程
工作流程 1：基本文件上传
python scripts/upload.py image.jpg
- 适用场景：快速上传、简单文件
- 输出：文件名和供 API 使用的 URI
- 状态：PROCESSING 或 ACTIVE
工作流程 2：使用自定义名称上传
python scripts/upload.py document.pdf --name "2026 年第四季度报告"
- 适用场景：组织文件、跟踪上传
- 何时使用：原始文件名不够描述性
- 显示名称会出现在文件列表中
工作流程 3：上传并等待处理
python scripts/upload.py video.mp4 --wait
- 适用场景：大文件、视频、音频
- 等待文件变为 ACTIVE 状态
- 何时使用：上传后需要立即使用文件
工作流程 4：上传图片供分析
# 1. 上传图片
python scripts/upload.py photo.png --name "产品照片"
# 2. 与 gemini-text 配合用于分析
python skills/gemini-text/scripts/generate.py "描述这张图片" --image photo.png
- 适用场景：图片分析、生成字幕、视觉问答
- 结合使用：gemini-text 用于多模态处理
工作流程 5：上传 PDF 用于内容提取
# 1. 上传 PDF
python scripts/upload.py research-paper.pdf --name "AI-研究论文" --wait
# 2. 使用 gemini-text 提取内容
python skills/gemini-text/scripts/generate.py "提取本文档的关键发现" --image research-paper.pdf
- 适用场景：文档处理、内容提取
- 结合使用：gemini-text 用于分析
工作流程 6：批量上传多个文件
# 1. 上传多个文件
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. 使用已上传的文件创建批处理作业（gemini-batch 技能）
- 适用场景：准备用于批处理的文件
- 结合使用：gemini-batch 用于批量操作
工作流程 7：上传音频用于转录
# 1. 上传音频
python scripts/upload.py interview.mp3 --name "采访-001" --wait
# 2. 使用 gemini-text 处理（如果支持转录）
python skills/gemini-text/scripts/generate.py "转录并总结此音频" --image interview.mp3
- 适用场景：音频处理、转录、播客分析
- 结合使用：gemini-text 用于音频分析
工作流程 8：上传视频用于内容分析
# 1. 上传视频（可能需要较长时间）
python scripts/upload.py product-demo.mp4 --name "演示视频" --wait
# 2. 使用 gemini-text 分析
python skills/gemini-text/scripts/generate.py "分析此产品演示视频" --image product-demo.mp4
- 适用场景：视频分析、内容总结
- 注意：视频可能需要较长的处理时间
参数参考
支持的文件类型
| 类型 | 扩展名 | 最大大小 | 处理时间 |
|---|---|---|---|
| 图片 | jpg, jpeg, png, gif, webp | 20MB | 秒级 |
| 音频 | mp3, wav, aac, flac | 25MB | 秒至分钟级 |
| 视频 | mp4, mov, avi, webm | 2GB | 分钟至小时级 |
| 文档 | pdf, txt | 50MB | 秒至分钟级 |
MIME 类型
脚本根据扩展名自动检测：
- 图片：image/jpeg, image/png, image/gif, image/webp
- 音频：audio/mpeg, audio/wav
- 视频：video/mp4, video/quicktime, video/webm
- 文档：application/pdf, text/plain
文件状态
| 状态 | 描述 | 准备好使用 |
|---|---|---|
PROCESSING | 文件正在分析中 | 否 |
ACTIVE | 文件已准备好 | 是 |
FAILED | 处理失败 | 否 |
输出解释
上传响应
Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
- 文件名：用于 API 调用
- URI：内部 Google Cloud Storage 引用
- 状态：PROCESSING = 等待，ACTIVE = 就绪
使用 --wait 标志
Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!
- 脚本轮询直至状态变为 ACTIVE
- 适用于需要处理的大文件
- 视频可能需要几分钟
使用已上传的文件
上传后，通过文件名引用文件：
# 与 gemini-text 配合使用
python skills/gemini-text/scripts/generate.py "分析" --image <已上传的文件路径>
常见问题
"google-genai 未安装"
pip install google-genai
"文件未找到"
- 确认文件路径正确
- 如果相对路径失败，请使用绝对路径
- 检查文件扩展名是否属于支持的类型
"文件过大"
- 检查对应文件类型的大小限制
- 如有可能，压缩图片/视频
- 将大文件拆分为多个小部分
"不支持的文件类型"
- 检查支持的扩展名
- 如有可能，转换为支持的格式
- 图片：jpg, png, gif, webp
- 视频：mp4, mov, avi, webm
"处理失败"
- 检查文件是否损坏
- 尝试重新上传文件
- 确认文件格式有效
- 检查 API 配额限制
"文件仍在处理中"（未使用 --wait 标志）
- 文件状态为 PROCESSING，而非 ACTIVE
- 使用
--wait标志或稍后检查状态 - 大文件（尤其是视频）需要时间
- 处理可能需要几分钟到几小时
最佳实践
上传策略
- 对将要立即使用的文件使用
--wait - 批量上传时跳过
--wait以节省时间 - 使用描述性
--name便于组织 - 记录文件名以备后续使用
文件组织
- 使用一致的命名约定
- 在名称中包含日期或版本号
- 将相关文件分组
- 在代码中记录文件名
性能提示
- 并行上传多个文件（单独进程）
- 预上传文件用于批量操作
- 在 API 调用前检查文件状态
- 删除旧文件以管理存储
错误处理
- 上传后检查返回状态
- 重试失败的上传
- 上传前验证文件完整性
- 记录文件名以供审计追溯
与其他技能集成
- gemini-text：多模态分析、文档处理
- gemini-image：基于上传的参考图片生成图像
- gemini-batch：在批处理作业中使用已上传的文件
- gemini-embeddings：从文件内容创建嵌入
文件生命周期
- 上传 → PROCESSING → ACTIVE → 在 API 中使用
- 删除旧文件以释放存储空间
- 文件可能在特定时间后过期
- 重要文件请下载备份
相关技能
- gemini-text：分析已上传的文件，进行文本生成
- gemini-image：基于上传的参考图片创建图像
- gemini-batch：在批处理中使用已上传的文件
- gemini-embeddings：从文件内容生成嵌入
快速参考
# 基本上传
python scripts/upload.py image.jpg
# 使用自定义名称
python scripts/upload.py document.pdf --name "我的文档"
# 等待处理
python scripts/upload.py video.mp4 --wait
# 多个文件
for file in *.jpg; do python scripts/upload.py "$file"; done
文件管理 API
脚本中虽未包含，但您也可以通过 Python SDK 管理文件：
from google import genai
client = genai.Client()
# 列出所有文件
for file in client.files.list():
print(f"{file.name}: {file.display_name} ({file.state})")
# 获取文件信息
file = client.files.get(name="files/abc123...")
print(f"State: {file.state}")
# 删除文件
client.files.delete(name="files/abc123...")
参考
- 获取 API 密钥：https://aistudio.google.com/apikey
- 文档：https://ai.google.dev/gemini-api/docs/file-upload
- 文件 API：https://ai.google.dev/gemini-api/docs/files
- 支持格式：图片、音频、视频、文档（见上表）