Communitygithub.com

akrindev/google-studio-skills

通过脚本使用 Google Gemini File API 上传和管理文件。支持上传图片、音频、视频、PDF 等文件,以便与 Gemini 模型协同使用。

google-studio-skills 是什么?

该技能提供了一个完整的文件管理解决方案,用于通过 Google Gemini File API 上传、检查状态和管理文件。它支持多种文件类型,包括图片、音频、视频、PDF 和文本文件,并提供了可直接执行的脚本以便易于集成。技能的主要用途是预先上传文件,以便在 Gemini 模型(如用于多模态分析、文档处理或转录)中使用。它支持通过 `--wait` 标志等待文件处理完成,并通过详细的输出(如文件名、URI 和状态)反馈操作结果。该技能与 `gemini-text`、`gemini-image` 和 `gemini-batch` 等其他技能无缝协作,支持从简单上传到多文件批处理等各种工作流。

兼容平台~Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/akrindev/google-studio-skills/tree/HEAD/skills/gemini-files

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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, webp20MB几秒
音频mp3, wav, aac, flac25MB几秒到几分钟
视频mp4, mov, avi, webm2GB几分钟到几小时
文档pdf, txt50MB几秒到几分钟

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..." });

参考

相关技能