Communitygithub.com

akrindev/google-studio-skills

透過 Google Gemini File API 上傳和管理檔案。支援上傳圖片、音訊、影片、PDF 等，以供 Gemini 模型使用。觸發關鍵字：上傳檔案、File API、上傳圖片、上傳 PDF、上傳影片、檔案管理。

google-studio-skills 是什麼？

此技能提供了一個完整的檔案上傳與管理方案，專門用於 Google Gemini File API。開發者可以透過簡單的指令稿（scripts/）上傳各種檔案類型，包括圖片、音訊、影片與文件。技能支援多種工作流程，例如基本上傳、自訂檔名、等待處理完成等，並可與其他 Gemini 技能（如 gemini-text）無縫整合進行多模態分析。該技能會自動偵測 MIME 類型、處理檔案狀態（PROCESSING、ACTIVE、FAILED），並提供詳細的錯誤處理與最佳實踐建議。無論是單一檔案還是批次上傳，此技能都能幫助開發者高效管理 Gemini 模型所需的資料。

相容平台~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 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

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
  • 適用於：快速上傳、簡單檔案
  • 輸出：檔案名稱及供 API 使用的 URI
  • 狀態：PROCESSING 或 ACTIVE

工作流程 2：使用自訂名稱上傳

node scripts/upload.js document.pdf --name "2026 年第四季季報"
  • 適用於：組織檔案、追蹤上傳記錄
  • 使用時機：原始檔名不夠具描述性時
  • 顯示名稱會出現在檔案清單中

工作流程 3：上傳並等待處理完成

node scripts/upload.js video.mp4 --wait
  • 適用於：大型檔案、影片、音訊
  • 會等待檔案狀態變為 ACTIVE
  • 使用時機：上傳後需要立即使用檔案

工作流程 4：上傳圖片進行分析

# 1. 上傳圖片
node scripts/upload.js photo.png --name "產品照"

# 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-研究論文" --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 "訪談-001" --wait

# 2. 使用 gemini-text 處理（若支援轉錄）
node skills/gemini-text/scripts/generate.js "轉錄並摘要這段音訊" --image interview.mp3
  • 適用於：音訊處理、轉錄、Podcast 分析
  • 與 gemini-text 搭配進行音訊分析

工作流程 8：上傳影片進行內容分析

# 1. 上傳影片（可能需要較長時間）
node scripts/upload.js product-demo.mp4 --name "示範影片" --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處理失敗否

輸出解讀

上傳回應

正在上傳 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
node skills/gemini-text/scripts/generate.js "分析" --image <上傳的檔案路徑>

常見問題

"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 "我的文件"

# 等待處理完成
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(`狀態: ${file.state}`);

// 刪除檔案
await client.files.delete({ name: "files/abc123..." });

參考資料

相關技能

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community