Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

🎬 Gemini、Veo、Cloud Run を使用して AI モーションラボを構築してデプロイする

1. はじめに

作成する機能

Gemini Motion Lab は、AI を活用したライブキオスク体験です。ユーザーが短いダンスや動きのクリップを録画すると、システムは次の処理を行います。

Gemini を使用して動きを分析（体の部位、フェーズ、テンポ、エネルギー）
Nano Banana（Gemini Flash Image）を使用して、スタイライズされたアバター画像を生成します。
Veo を使用して、アバターでモーションを再現する AI 動画を作成します。
並べて表示する動画（オリジナル + AI 生成）を作成します
モバイルデバイス向けページの QR コードで結果を共有します。

この Codelab を終了すると、Google Cloud Run にデプロイされた完全なデモが完成し、そのデモを支える AI パイプラインを理解できるようになります。

アーキテクチャの概要

最終デモ:

核となるテクノロジー

コンポーネント	テクノロジー	目的
モーション分析	Gemini Flash	動画の体の動き、フェーズ、スタイルを分析する
アバター生成	Gemini Flash Image（Nano Banana）	キーフレームから 1024×1024 のスタイル設定されたアバターを生成する
動画生成	Veo 3.1	アバターとモーションプロンプトから AI 動画を作成する
バックエンド	FastAPI + Python 3.11	非同期パイプラインオーケストレーションを備えた API サーバー
フロントエンド	React + Vite + TypeScript	カメラの録画とライブステータスを表示するキオスク UI
ホスト方法	Cloud Run	サーバーレスコンテナ化デプロイ
ストレージ	Google Cloud Storage	動画のアップロード、フレーム、カットと合成された出力

2. 📦 リポジトリのクローンを作成する

1. Cloud Shell エディタを開く

👉 ブラウザで Cloud Shell エディタを開きます。

ターミナルが画面の下部に表示されない場合:

[表示] をクリックします。
[Terminal] をクリックします。

2. コードのクローンを作成する

👉💻 ターミナルで、リポジトリのクローンを作成します。

cd ~
git clone https://github.com/cuppibla/gemini-motion-lab-starter.git
cd gemini-motion-lab-starter

3. プロジェクトの構造を確認する

リポジトリのレイアウトを簡単に見てみましょう。

gemini-motion-lab-starter/
├── backend/                     # FastAPI backend (Python 3.11)
│   ├── app/
│   │   ├── main.py              # FastAPI app entry point
│   │   ├── config.py            # Environment-based settings
│   │   ├── routers/             # API endpoints (upload, analyze, generate, share...)
│   │   ├── services/            # Business logic (Gemini, Veo, storage, pipeline...)
│   │   └── prompts/             # AI prompt templates
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/                    # React + Vite + TypeScript
│   ├── src/                     # React components
│   ├── public/                  # Static assets
│   ├── Dockerfile
│   └── nginx.conf
├── init.sh                      # Create GCP project & link billing
├── billing-enablement.py        # Auto-link billing account
├── setup.sh                     # Create GCS bucket, service account, .env
└── scripts/                     # Utility scripts

3. 🛠️ クレジットを請求して GCP プロジェクトを作成する

パート 1: 請求先クレジットを利用する

Gmail アカウントを使用して、請求先アカウントのクレジットを請求します。

パート 2: 新しいプロジェクトを作成する

👉💻 ターミナルで、init スクリプトを実行可能にして実行します。

cd ~/gemini-motion-lab-starter
chmod +x init.sh
./init.sh

init.sh スクリプトは次の処理を行います。

接頭辞 gemini-motion-lab を使用して新しい GCP プロジェクトを作成する
プロジェクト ID を ~/project_id.txt に保存する
課金依存関係をインストールして、請求先アカウントを自動的にリンクする

パート 3: プロジェクトを構成して API を有効にする

👉💻 ターミナルでプロジェクト ID を設定します。

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 このプロジェクトに必要な Google Cloud APIs を有効にします（1 ～ 2 分かかります）。

gcloud services enable \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com

4. 🧠 [読み取り専用] アーキテクチャについて

このセクションでは、AI パイプラインがエンドツーエンドでどのように機能するかについて説明します。対応不要 - デプロイする前に、システムを理解するために読むだけです。

AI パイプライン

ユーザーがキオスクでモーションクリップを録画すると、次の 5 つのステージが順番に実行されます。

ステージ 1: 動画のアップロード

フロントエンドは、ユーザーのカメラから 5 秒の WebM クリップを録画し、バックエンドの /api/upload エンドポイントを介して Google Cloud Storage にアップロードします。

POST /api/upload/{video_id}  →  gs://BUCKET/uploads/{video_id}.webm

ステージ 2: Gemini モーション分析

バックエンドは、アップロードされた動画を構造化分析のために Gemini Flash（gemini-3-flash-preview）に送信します。

仕組み（backend/app/services/gemini_service.py）:

このサービスは、Vertex AI SDK の client.models.generate_content() を使用し、動画を Part.from_uri 入力として、構造化されたプロンプトを使用します。response_mime_type="application/json" により、Gemini は解析可能な JSON を返します。このモデルでは、モーションフェーズの推論を改善するために ThinkingConfig(thinking_budget=1024) も使用しています。

# Simplified from gemini_service.py
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        types.Part.from_uri(file_uri=gcs_uri, mime_type="video/webm"),
        MOTION_ANALYSIS_PROMPT,  # detailed prompt template
    ],
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        thinking_config=types.ThinkingConfig(thinking_budget=1024),
    ),
)
analysis = json.loads(response.text)

ステージ 3: Nano Banana アバターの生成

動画から抽出されたベストフレームを使用して、Gemini Flash Image（gemini-3.1-flash-image-preview）が 1024×1024 のスタイル化されたアバターを生成します。

仕組み（backend/app/services/nano_banana_service.py）:

# Simplified from nano_banana_service.py
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[
        types.Content(role="user", parts=[
            types.Part.from_bytes(data=frame_bytes, mime_type="image/png"),
            types.Part.from_text(text=avatar_prompt),
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="1:1",
            output_mime_type="image/png",
        ),
    ),
)

生成されたアバター PNG が GCS にアップロードされ、次のステージに渡されます。

ステージ 4: Veo の動画生成

アバター画像は、Veo 3.1（veo-3.1-fast-generate-001）の参照アセットとして使用され、8 秒間の AI 動画が生成されます。

仕組み（backend/app/services/veo_service.py）:

# Simplified from veo_service.py
config = GenerateVideosConfig(
    reference_images=[
        VideoGenerationReferenceImage(
            image=Image(gcs_uri=avatar_gcs_uri, mime_type="image/png"),
            reference_type="ASSET",
        )
    ],
    aspect_ratio="16:9",
    duration_seconds=8,
    output_gcs_uri=f"gs://{BUCKET}/output/{video_id}/",
)
operation = client.models.generate_videos(
    model="veo-3.1-fast-generate-001",
    prompt=veo_prompt,
    config=config,
)

Veo の生成は非同期です。オペレーション ID がすぐに返されます。バックエンドは、完了するまで（最大 10 分）オペレーションをポーリングします。

ステージ 5: 後処理パイプライン

Veo が完了すると、バックグラウンドパイプライン（backend/app/services/pipeline.py）が自動的に実行されます。

8 秒の Veo 出力を 3 秒にトリミングする
構成: 並べて表示する動画（左側に元の録画、右側に AI 動画）
構成された動画を GCS にアップロードする
キュースロットを解放する

このパイプラインはバックグラウンド asyncio.Task として実行されるため、キオスクのフロントエンドは待機する必要がありません。

キューシステム

Veo の生成はリソースを大量に消費するため、システムでは最大 3 つの同時実行ジョブが適用されます。

# backend/app/routers/queue.py
MAX_CONCURRENT_JOBS = 3

@router.get("/queue/status")
async def queue_status():
    return {
        "active_jobs": len(_active_jobs),
        "max_jobs": MAX_CONCURRENT_JOBS,
        "available": len(_active_jobs) < MAX_CONCURRENT_JOBS,
    }

フロントエンドは、新規ユーザーがセッションを開始する前に GET /api/queue/status を確認します。パイプラインが完了して complete(video_id) を呼び出すと、次のユーザーのためにスロットが開きます。

Cloud Run - サーバーレスコンテナ

バックエンドとフロントエンドの両方が Cloud Run サービスとしてデプロイされます。

サービス	目的	キーの構成
バックエンド	FastAPI API サーバー	2 GiB のメモリ（ffmpeg による動画処理用）
フロントエンド	Nginx で提供される静的 React アプリ	デフォルトのメモリ

5. ⚙️ 設定スクリプトを実行

1. 自動設定を実行する

setup.sh スクリプトは、必要なクラウドリソースを作成し、.env ファイルを生成します。

👉💻 スクリプトを実行可能にして実行します。

cd ~/gemini-motion-lab-starter
chmod +x setup.sh
./setup.sh

2. IAM ロールを付与する

次に、サービスアカウントに必要な権限を付与します。

👉💻 次のコマンドを実行して、プロジェクト ID を設定し、3 つのロールすべてを付与します。

export PROJECT_ID=$(cat ~/project_id.txt)

# 1. Storage Admin — upload/download videos and frames
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:gemini-motion-lab-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/storage.admin"

# 2. Vertex AI User — call Gemini and Veo models
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:gemini-motion-lab-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# 3. Service Account Token Creator — generate signed URLs for GCS
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
COMPUTE_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

gcloud iam service-accounts add-iam-policy-binding \
  gemini-motion-lab-sa@${PROJECT_ID}.iam.gserviceaccount.com \
  --project=$PROJECT_ID \
  --member="serviceAccount:${COMPUTE_SA}" \
  --role="roles/iam.serviceAccountTokenCreator"

3. `.env` ファイルを確認する

👉💻 生成された .env ファイルを確認します。

cat .env

以下のように表示されます。

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GCS_BUCKET=gemini-motion-lab-your-project-id
GCS_SIGNING_SA=gemini-motion-lab-sa@your-project-id.iam.gserviceaccount.com
GOOGLE_GENAI_USE_VERTEXAI=true
MOCK_AI=false

6. 🚀 バックエンドをデプロイする

1. バックエンドの Dockerfile について

デプロイする前に、コンテナの構造を確認しましょう。

# backend/Dockerfile
FROM python:3.11-slim                           # Python base image
RUN apt-get update && apt-get install -y \
    ffmpeg libgl1 libglib2.0-0 \                # ffmpeg for video processing
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY pyproject.toml .
RUN pip install --no-cache-dir .                # Install Python dependencies
COPY app/ ./app/                                # Copy application code
EXPOSE 8080
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

2. Cloud Run へのデプロイ

👉💻 環境変数を読み込んでデプロイします。

source .env

cd ~/gemini-motion-lab-starter/backend

gcloud run deploy gemini-motion-lab-backend \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --min-instances 1 \
  --max-instances 3 \
  --memory 2Gi \
  --port 8080 \
  --project $GOOGLE_CLOUD_PROJECT \
  --set-env-vars "GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GCS_BUCKET=$GCS_BUCKET,GCS_SIGNING_SA=$GCS_SIGNING_SA,GOOGLE_GENAI_USE_VERTEXAI=$GOOGLE_GENAI_USE_VERTEXAI,MOCK_AI=$MOCK_AI"

これには 3 ～ 5 分ほどかかります。Cloud Build は次の処理を行います。

ソースコードをアップロードする
Docker イメージをビルドする
Artifact Registry に push する
Cloud Run にデプロイする

3. バックエンド URL を保存する

👉💻 デプロイしたら、バックエンド URL を保存します。

BACKEND_URL=$(gcloud run services describe gemini-motion-lab-backend \
  --region us-central1 \
  --format="value(status.url)" \
  --project $GOOGLE_CLOUD_PROJECT)

echo "Backend URL: $BACKEND_URL"

バックエンドで QR コードが生成され、ユーザーが動画をダウンロードできるようになります。そのためには、独自の公開 URL を知る必要があります。

👉💻 独自の URL を使用してバックエンド構成を更新します。

gcloud run services update gemini-motion-lab-backend \
  --region us-central1 \
  --update-env-vars PUBLIC_BASE_URL=$BACKEND_URL \
  --project $GOOGLE_CLOUD_PROJECT

5. バックエンドを確認する

👉💻 ヘルスエンドポイントをテストします。

curl $BACKEND_URL/api/health

想定される出力:

{"status":"ok"}

👉💻 キューのステータスを確認します。

curl $BACKEND_URL/api/queue/status

想定される出力:

{"active_jobs":0,"max_jobs":3,"available":true}

7. 🎨 フロントエンドをデプロイする

1. フロントエンドの Dockerfile について

フロントエンドはマルチステージビルドを使用します。まず React アプリをビルドし、次に Nginx で提供します。

# frontend/Dockerfile
FROM node:20-alpine AS builder               # Stage 1: Build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ARG VITE_API_BASE=https://...                # Backend URL baked at build time
ENV VITE_API_BASE=$VITE_API_BASE
RUN npm run build                            # Produces static files in /app/dist

FROM nginx:alpine                            # Stage 2: Serve
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 8080

2. Cloud Run へのデプロイ

👉💻 まず、バックエンド URL を .env ファイルに書き込み、Vite がビルド時にそれを組み込めるようにします。

cd ~/gemini-motion-lab-starter/frontend
echo "VITE_API_BASE=$BACKEND_URL" > .env

👉💻 フロントエンドをデプロイします。

gcloud run deploy gemini-motion-lab-frontend \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --min-instances 1 \
  --max-instances 3 \
  --port 8080 \
  --project $GOOGLE_CLOUD_PROJECT

これには 2 ～ 3 分ほどかかります。

3. フロントエンドの URL を取得する

👉💻 フロントエンド URL を取得して開きます。

FRONTEND_URL=$(gcloud run services describe gemini-motion-lab-frontend \
  --region us-central1 \
  --format="value(status.url)" \
  --project $GOOGLE_CLOUD_PROJECT)

echo "🎬 Your Gemini Motion Lab is live at: $FRONTEND_URL"

👉 ブラウザで URL を開きます。Gemini Motion Lab キオスクインターフェースが表示されます。

8. 🎮 [省略可] デモを試す

1. モーションを記録する

ブラウザ（カメラのサポートが最適な Chrome を推奨）でフロントエンド URL を開きます。
[開始] をクリックして録画を開始します
約 5 秒間踊るか動く - 腕を大きく動かしたり、ダイナミックなポーズをとったりすると効果的です。
録画は自動的に停止してアップロードされます

2. AI パイプラインを監視する

アップロードすると、パイプラインの実行がリアルタイムで表示されます。

フェーズ	変更の内容	所要時間
分析中...	Gemini Flash が動画の動きのパターンを分析する	～ 5 ～ 10 秒
アバターを生成しています...	Nano Banana がベストフレームからスタイライズされたアバターを作成	～ 8 ～ 12 秒
動画を作成しています...	Veo 3.1 は、アバターとモーションプロンプトから AI 動画を生成します	約 60 ～ 120 秒
作成中...	ffmpeg がトリミングして並べて比較を作成する	～ 5 ～ 10 秒

パイプラインが完了したら、次の操作を行います。

キオスクの画面に QR コードが表示されます
スマートフォンで QR コードをスキャンします
作成した動画を含むモバイルデバイス向け共有ページが表示されます。

4. バックエンドログを確認する

👉💻 舞台裏で何が起きたかを確認する:

gcloud logging read \
  "resource.type=cloud_run_revision AND resource.labels.service_name=gemini-motion-lab-backend" \
  --limit=30 \
  --project $GOOGLE_CLOUD_PROJECT \
  --format="value(timestamp,textPayload)" \
  --freshness=10m

パイプラインをトレースするログ行が表示されます。

Pipeline started for video_id=abc123
Gemini model used: gemini-3-flash-preview
Avatar generated: style=pixel-hero size=450KB time=8.2s
Veo model used: veo-3.1-fast-generate-001
Pipeline: Veo complete for video_id=abc123
Pipeline: trimmed video uploaded
Pipeline: composed video uploaded
Pipeline complete for video_id=abc123

5. キューをモニタリングする

👉💻 実行中のジョブ数を確認します。

curl $BACKEND_URL/api/queue/status

3 つのセッションが同時にアクティブになっている場合、レスポンスは次のようになります。

{"active_jobs":3,"max_jobs":3,"available":false}

新規ユーザーは、スロットが空くまで待つよう求められます。

9. 🎉 まとめ

作成した内容

✅ AI モーション分析 - Gemini Flash が動画の動き、テンポ、スタイルを分析

✅ アバターの生成 - Nano Banana が動画フレームからスタイリッシュなアバターを作成

✅ AI 動画制作ツール - Veo 3.1 がユーザーの動きに合わせて新しい動画を生成

✅ 非同期パイプライン - キュー管理によるバックグラウンド処理（最大 3 つの同時処理）

✅ 並べて合成 - ffmpeg を利用した動画合成

✅ Cloud Run Deployment - サーバーレス、自動スケーリング、サーバー管理不要

学習した主なコンセプト

Gemini Multimodal - 動画を入力として送信し、構造化された JSON 分析を受信する
Nano Banana（Gemini 画像生成） - リファレンス画像とスタイルプロンプトを使用してアバターを生成
Veo 3.1 - 参照アセットとテキストプロンプトを使用した非同期動画生成
Cloud Run - 環境変数と自動スケーリングを使用してコンテナをデプロイする
非同期パイプラインパターン - 長時間実行の AI オペレーションに asyncio.Task を使用した Fire-and-forget バックグラウンドタスク
キュー管理 - 同時実行 AI ジョブのレート制限により、費用と API 割り当てを制御します。

アーキテクチャの要約

次のステップ

アバターのスタイルを追加 - backend/app/prompts/avatar_generation.py を編集
Veo のプロンプトをカスタマイズする - 編集アイコン backend/app/prompts/video_generation.py
モックモードでローカルで実行する - API 呼び出しなしで開発を行うために、.env で MOCK_AI=true を設定します。
イベントに合わせてスケーリングする - --max-instances と MAX_CONCURRENT_JOBS を増やす

API	目的
`run.googleapis.com`	Cloud Run - バックエンドとフロントエンドをサーバーレスコンテナとしてホストします。
`cloudbuild.googleapis.com`	Cloud Build - ソースコードから Docker イメージをビルドします。
`aiplatform.googleapis.com`	Vertex AI - Gemini モデルと Veo モデルへのアクセス
`storage.googleapis.com`	Cloud Storage - アップロードされた動画、フレーム、生成されたアセットを保存します。
`artifactregistry.googleapis.com`	Artifact Registry - ビルドされた Docker イメージを保存します。

ロール	目的
`roles/storage.admin`	Cloud Storage 内のオブジェクトの読み取り、書き込み、管理に対する完全なアクセス権 - 動画のアップロード、フレーム、合成された出力に必要
`roles/aiplatform.user`	Vertex AI モデルを使用して予測を行う - Gemini 分析、Nano Banana アバターの生成、Veo 動画の作成に必要
`roles/iam.serviceAccountTokenCreator`	共有ページが期間限定のリンクを介してモバイルに動画を配信できるように、署名付き URL を生成します

フラグ	目的
`--source .`	ソースから直接 Docker イメージをビルドする（Cloud Build が処理します）
`--allow-unauthenticated`	API を一般公開する（フロントエンドに必要）
`--min-instances 1`	コールドスタートを回避するために、少なくとも 1 つのインスタンスをウォーム状態にする
`--max-instances 3`	スケーリングを制限する（同時実行 Veo ジョブの数も 3 つに制限するため）
`--memory 2Gi`	ffmpeg を使用した動画処理に必要
`--set-env-vars`	すべての構成を環境変数として渡す

🎬 Gemini、Veo、Cloud Run を使用して AI モーション ラボを構築してデプロイする

1. はじめに

作成する機能

アーキテクチャの概要

核となるテクノロジー

2. 📦 リポジトリのクローンを作成する

1. Cloud Shell エディタを開く

2. コードのクローンを作成する

3. プロジェクトの構造を確認する

3. 🛠️ クレジットを請求して GCP プロジェクトを作成する

パート 1: 請求先クレジットを利用する

パート 2: 新しいプロジェクトを作成する

パート 3: プロジェクトを構成して API を有効にする

4. 🧠 [読み取り専用] アーキテクチャについて

AI パイプライン

ステージ 1: 動画のアップロード

ステージ 2: Gemini モーション分析

ステージ 3: Nano Banana アバターの生成

ステージ 4: Veo の動画生成

ステージ 5: 後処理パイプライン

キューシステム

Cloud Run - サーバーレス コンテナ

5. ⚙️ 設定スクリプトを実行

1. 自動設定を実行する

2. IAM ロールを付与する

3. .env ファイルを確認する

6. 🚀 バックエンドをデプロイする

1. バックエンドの Dockerfile について

2. Cloud Run へのデプロイ

3. バックエンド URL を保存する

4. バックエンドの共有 URL を更新する

5. バックエンドを確認する

7. 🎨 フロントエンドをデプロイする

1. フロントエンドの Dockerfile について

2. Cloud Run へのデプロイ

3. フロントエンドの URL を取得する

8. 🎮 [省略可] デモを試す

1. モーションを記録する

2. AI パイプラインを監視する

3. 作品を共有する

4. バックエンド ログを確認する

5. キューをモニタリングする

9. 🎉 まとめ

作成した内容

学習した主なコンセプト

アーキテクチャの要約

次のステップ

リソース

🎬 Gemini、Veo、Cloud Run を使用して AI モーションラボを構築してデプロイする

Cloud Run - サーバーレスコンテナ

3. `.env` ファイルを確認する

4. バックエンドログを確認する