Gemini File API
通过可执行的脚本上传和管理文件,以便与 Gemini 模型配合使用,支持图片、音频、视频、PDF 和其他文件类型。
何时使用此技能
当你需要以下操作时使用此技能:
- 上传图片用于多模态分析
- 上传视频用于内容处理
- 上传 PDF 用于文档分析
- 上传音频用于转录或处理
- 为批处理操作预先上传文件
- 检查文件处理状态
- 列出和管理已上传的文件
- 与其他 Gemini 技能(文本、图片等)一起使用文件
可用脚本
scripts/upload.js
目的:将文件上传到 Gemini File API
使用时机:
- 上传任意文件用于 Gemini 处理
- 准备用于多模态生成的文件
- 上传文档进行分析
- 批量文件准备
关键参数:
| 参数 | 描述 | 示例 |
|---|---|---|
path | 文件路径(必填) | image.jpg |
--name, -n | 显示名称 | "my-document" |
--wait, -w | 等待处理完成 | 标志 |
输出:文件名、URI 和状态信息
工作流
工作流 1:基本文件上传
node scripts/upload.js image.jpg
- 最佳用途:快速上传,简单文件
- 输出:文件名和 URI,用于 API 调用
- 状态:PROCESSING 或 ACTIVE
工作流 2:使用自定义名称上传
node scripts/upload.js document.pdf --name "Quarterly Report Q4 2026"
- 最佳用途:组织文件,跟踪上传
- 使用时机:原始文件名不够描述性
- 显示名称会出现在文件列表中
工作流 3:上传并等待处理
node scripts/upload.js video.mp4 --wait
- 最佳用途:大文件、视频、音频
- 等待文件变为 ACTIVE 状态
- 使用时机:上传后需要立即使用文件
工作流 4:上传图片用于分析
# 1. 上传图片
node scripts/upload.js photo.png --name "product-shot"
# 2. 使用 gemini-text 进行分析
node skills/gemini-text/scripts/generate.js "描述这张图片" --image photo.png
- 最佳用途:图片分析、生成描述、视觉问答
- 与 gemini-text 结合用于多模态处理
工作流 5:上传 PDF 用于内容提取
# 1. 上传 PDF
node scripts/upload.js research-paper.pdf --name "AI-Research-Paper" --wait
# 2. 使用 gemini-text 提取内容
node skills/gemini-text/scripts/generate.js "提取这份文档的关键发现" --image research-paper.pdf
- 最佳用途:文档处理、内容提取
- 与 gemini-text 结合用于分析
工作流 6:批量上传多个文件
# 1. 上传多个文件
for file in *.jpg; do
node scripts/upload.js "$file"
done
# 2. 使用已上传的文件创建批处理任务(gemini-batch 技能)
- 最佳用途:为批处理准备文件
- 与 gemini-batch 结合用于批量操作
工作流 7:上传音频用于转录
# 1. 上传音频
node scripts/upload.js interview.mp3 --name "interview-001" --wait
# 2. 使用 gemini-text 处理(如果支持转录)
node skills/gemini-text/scripts/generate.js "转录并总结这段音频" --image interview.mp3
- 最佳用途:音频处理、转录、播客分析
- 与 gemini-text 结合用于音频分析
工作流 8:上传视频用于内容分析
# 1. 上传视频(可能需要时间)
node scripts/upload.js product-demo.mp4 --name "demo-video" --wait
# 2. 使用 gemini-text 分析
node skills/gemini-text/scripts/generate.js "分析这个产品演示视频" --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 一起使用
node skills/gemini-text/scripts/generate.js "分析" --image <uploaded-file-path>
常见问题
"google-genai 未安装"
npm install @google/genai@latest dotenv@latest
"文件未找到"
- 检查文件路径是否正确
- 如果相对路径失败,请使用绝对路径
- 检查文件扩展名是否属于支持的类型
"文件太大"
- 检查文件类型的最大大小限制
- 如果可能,压缩图片/视频
- 将大文件分割成更小的部分
"不支持的文件类型"
- 检查支持的扩展名
- 如果可能,转换为支持的格式
- 图片: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:从文件内容生成嵌入
快速参考
# 基本上传
node scripts/upload.js image.jpg
# 使用自定义名称
node scripts/upload.js document.pdf --name "My Document"
# 等待处理
node scripts/upload.js video.mp4 --wait
# 多个文件
for file in *.jpg; do node scripts/upload.js "$file"; done
文件管理 API
虽然不在脚本中,但你也可以通过 JavaScript 管理文件:
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// 列出所有文件
for await (const file of client.files.list()) {
console.log(`${file.name}: ${file.displayName} (${file.state})`);
}
// 获取文件信息
const file = await client.files.get({ name: "files/abc123..." });
console.log(`State: ${file.state}`);
// 删除文件
await 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
- 支持的格式:图片、音频、视频、文档(详见上方表格)