Gemini 文件 API
通过可执行脚本上传和管理文件，用于 Gemini 模型，支持图片、音频、视频、PDF 及其他文件类型。
何时使用此技能
在以下场景中使用此技能：
- 上传图片进行多模态分析
- 上传视频以处理内容
- 上传 PDF 进行文档分析
- 上传音频以进行转录或处理
- 预上传文件以进行批量操作
- 检查文件处理状态
- 列出和管理已上传的文件
- 将文件与其他 Gemini 技能（文本、图片等）结合使用
可用脚本
scripts/upload.py
用途：上传文件至 Gemini File 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 "product-shot"
# 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-Research-Paper" --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 "interview-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 "demo-video" --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 <uploaded-file-path>
常见问题
“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
- File API：https://ai.google.dev/gemini-api/docs/files
- 支持的格式：图片、音频、视频、文档（见上方表格）