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
- 最適: 高速アップロード、シンプルなファイル
- 出力: API で使用するファイル名と URI
- 状態: PROCESSING または ACTIVE
ワークフロー 2: カスタム名でのアップロード
python scripts/upload.py document.pdf --name "2026年第4四半期レポート"
- 最適: ファイルの整理、アップロードの追跡
- 使用時: 元のファイル名が十分に説明的でない場合
- 表示名はファイル一覧に表示される
ワークフロー 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
- 最適: 画像分析、キャプション生成、視覚的な Q&A
- 組み合わせ: gemini-text でのマルチモーダル処理
ワークフロー 5: コンテンツ抽出用の PDF アップロード
# 1. PDF をアップロード
python scripts/upload.py research-paper.pdf --name "AI研究論文" --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 "Analyze" --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 "My Document"
# 処理完了を待機
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"State: {file.state}")
# ファイルを削除
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
- 対応形式: 画像、音声、動画、ドキュメント（上記の表を参照）