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 "四半期レポート Q4 2026"
- 最適: ファイルの整理、アップロードの追跡
- 使用するタイミング: 元のファイル名ではわかりにくい場合
- 表示名: ファイル一覧に表示されます
ワークフロー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
- サポートされている形式: 画像、音声、動画、ドキュメント（上の表を参照）