Communitygithub.com

akrindev/google-studio-skills

スクリプトを使用してGemini File API経由でファイルをアップロードおよび管理します。画像、音声、動画、PDFなどのファイルをGeminiモデルで使用するためにアップロード、ステータス確認、ファイル管理を行います。

google-studio-skills とは？

このスキルは、Google Gemini File API を利用して、画像、音声、動画、PDFなどのファイルをアップロードし、管理するための機能を提供します。主にスクリプト（scripts/upload.js）を使用して、ファイルのアップロード、カスタム名の指定、処理完了の待機、ファイルリストの取得、削除といった操作をCLIから直接実行できます。アップロードされたファイルは、Gemini Text（文章生成）やGemini Image（画像生成）などの他のスキルと連携して、マルチモーダル解析やバッチ処理に活用できます。このスキルはClaude Codeなどの開発エージェントツール向けに設計されており、特に大規模なファイル処理や複数ファイルの事前アップロードが必要なワークフローで有用です。ファイルの状態（PROCESSING、ACTIVE、FAILED）を確認し、エラーハンドリングや再アップロードといったベストプラクティスに従うことで、効率的なファイル管理を実現します。

対応~Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/akrindev/google-studio-skills/tree/HEAD/skills/gemini-files
オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

Gemini File API

スクリプトを使用して、画像、音声、動画、PDFなどのファイルをGeminiモデル用にアップロードおよび管理します。

いつこのスキルを使うか

以下の状況でこのスキルを使用します：

  • 画像をアップロードしてマルチモーダル分析を行う
  • 動画をアップロードしてコンテンツ処理を行う
  • 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 "四半期レポート Q4 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
  • 最適な用途: 画像分析、キャプション作成、視覚的なQ&A
  • 連携: 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
  • 最適な用途: 音声処理、文字起こし、ポッドキャスト分析
  • 連携: 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処理が失敗いいえ

出力の解釈

アップロード応答

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 "Analyze" --image <uploaded-file-path>

よくある問題

"google-genai not installed"

npm install @google/genai@latest dotenv@latest

"File not found"

  • ファイルパスが正しいことを確認
  • 相対パスが失敗する場合は絶対パスを使用
  • ファイル拡張子がサポートされているタイプであることを確認

"File too large"

  • ファイルタイプのサイズ制限を確認
  • 画像や動画を可能な限り圧縮
  • 大きなファイルは小さな部分に分割

"Unsupported file type"

  • サポートされている拡張子を確認
  • 可能であればサポートされている形式に変換
  • 画像: jpg, png, gif, webp
  • 動画: mp4, mov, avi, webm

"Processing failed"

  • ファイルが破損していないか確認
  • ファイルを再アップロードしてみる
  • ファイル形式が有効であることを確認
  • APIクォータ制限を確認

"File still processing"（--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..." });

参考

関連スキル

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