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
- 最佳场景：快速上传，简单文件
- 输出：文件名和 URI，用于 API 调用
- 状态：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
- 支持的格式：图片、音频、视频、文档（见上表）