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 | 处理失败 | 否 |
输出解读
上传响应
正在上传 photo.png...
已上传：files/abc123...
URI：gs://generation-tmp/abc123...
状态：PROCESSING
- 文件名：用于 API 调用
- URI：内部 Google Cloud Storage 引用
- 状态：PROCESSING = 等待，ACTIVE = 就绪
使用 --wait 标志
正在上传 video.mp4...
已上传：files/xyz789...
URI：gs://generation-tmp/xyz789...
状态：PROCESSING
等待处理中...
仍在处理...
文件已就绪！
- 脚本持续轮询直到状态变为 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 管理文件：
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"状态: {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
- 支持格式：图片、音频、视频、文档（见上方表格）