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 "2026年第4四半期 四半期レポート"
- 最適な用途: ファイルの整理、アップロードの追跡
- 使用するタイミング: 元のファイル名が十分に説明的でない場合
- 表示名はファイル一覧に表示されます
ワークフロー 3: アップロードして処理完了を待機
python scripts/upload.py video.mp4 --wait
- 最適な用途: 大容量ファイル、動画、音声
- ファイルが ACTIVE 状態になるまで待機します
- 使用するタイミング: アップロード後すぐにファイルを使用する必要がある場合
ワークフロー 4: 分析用の画像をアップロード
# 1. 画像をアップロード
python scripts/upload.py photo.png --name "商品写真"
# 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 "インタビュー-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 "デモ動画" --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 "分析" --image <アップロードしたファイルのパス>
よくある問題
「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
- File API: https://ai.google.dev/gemini-api/docs/files
- サポートされている形式: 画像、音声、動画、ドキュメント（上記の表を参照）