Gemini File 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 "Quarterly Report Q4 2026"
- 最適: ファイルの整理、アップロードの追跡
- 使用時: 元のファイル名だけでは不十分な場合
- 表示名はファイル一覧に表示されます
ワークフロー 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 "Describe this image" --image photo.png
- 最適: 画像分析、キャプション生成、ビジュアル Q&A
- 連携: マルチモーダル処理のために gemini-text と併用
ワークフロー 5: コンテンツ抽出用に PDF をアップロード
# 1. PDF をアップロード
python scripts/upload.py research-paper.pdf --name "AI-Research-Paper" --wait
# 2. gemini-text でコンテンツを抽出
python skills/gemini-text/scripts/generate.py "Extract key findings from this document" --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 "Transcribe and summarize this audio" --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 "Analyze this product demo video" --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 not installed"
pip install google-genai
"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: ファイルコンテンツから埋め込みを生成
クイックリファレンス
# 基本的なアップロード
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
- File API: https://ai.google.dev/gemini-api/docs/files
- サポートされる形式: 画像、音声、動画、ドキュメント（上の表を参照）