🎬 Membangun & Men-deploy Lab Gerakan AI dengan Gemini, Veo, & Cloud Run

1. Pengantar

Yang Akan Anda Buat

Gemini Motion Lab adalah pengalaman interaksi langsung dengan kios yang didukung AI. Pengguna merekam klip pendek gerakan atau tarian, dan sistem:

  1. Menganalisis gerakan menggunakan Gemini (bagian tubuh, fase, tempo, energi)
  2. Membuat gambar avatar bergaya menggunakan Nano Banana (Gemini Flash Image)
  3. Membuat video AI menggunakan Veo yang menciptakan kembali gerakan dengan avatar
  4. Menyusun video berdampingan (asli + buatan AI)
  5. Membagikan hasil melalui kode QR di halaman yang dioptimalkan untuk seluler

Di akhir codelab ini, Anda akan memiliki demo lengkap yang di-deploy ke Google Cloud Run dan memahami pipeline AI yang mendukungnya.

Ringkasan Arsitektur

Demo Akhir:

cover

Teknologi Inti

Komponen

Teknologi

Tujuan

Analisis Gerakan

Gemini Flash

Menganalisis video untuk gerakan tubuh, fase, dan gaya

Pembuatan Avatar

Gemini Flash Image (Nano Banana)

Membuat avatar bergaya 1024×1024 dari frame utama

Pembuatan Video

Veo 3.1

Membuat video AI dari avatar + perintah gerakan

Backend

FastAPI + Python 3.11

Server API dengan orkestrasi pipeline asinkron

Frontend

React + Vite + TypeScript

UI Kios dengan perekaman kamera dan status aktif

Hosting

Cloud Run

Deployment dalam container serverless

Penyimpanan

Google Cloud Storage

Upload video, frame, output yang dipangkas & disusun

2. 📦 Meng-clone Repositori

1. Buka Cloud Shell Editor

👉 Buka Cloud Shell Editor di browser Anda.

Jika terminal tidak muncul di bagian bawah layar:

  • Klik Lihat
  • Klik Terminal

2. Meng-clone Kode

👉💻 Di terminal, clone repositori:

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

3. Mempelajari Struktur Project

Lihat sekilas tata letak repositori:

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. 🛠️ Klaim Kredit & Buat Project GCP

Bagian 1: Mengklaim Kredit Penagihan Anda

👉 Klaim kredit akun penagihan Anda menggunakan akun Gmail Anda.

Bagian 2: Buat Project Baru

👉💻 Di terminal, jadikan skrip init dapat dieksekusi dan jalankan:

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

Skrip init.sh akan:

  1. Buat project GCP baru dengan awalan gemini-motion-lab
  2. Simpan project ID ke ~/project_id.txt
  3. Menginstal dependensi penagihan dan menautkan akun penagihan Anda secara otomatis

Bagian 3: Mengonfigurasi Project & Mengaktifkan API

👉💻 Tetapkan project ID Anda di terminal:

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

👉💻 Aktifkan Google Cloud API yang diperlukan untuk project ini (membutuhkan waktu ~1-2 menit):

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

4. 🧠 [HANYA BACA] Memahami Arsitektur

Bagian ini menjelaskan cara kerja pipeline AI secara menyeluruh. Tidak ada tindakan yang diperlukan — cukup baca untuk memahami sistem sebelum men-deploy.

Pipeline AI

Saat pengguna merekam klip gerakan di kios, lima tahap akan berjalan secara berurutan:

Tahap 1: Upload Video

Frontend merekam klip WebM 5 detik dari kamera pengguna dan menguploadnya ke Google Cloud Storage melalui endpoint /api/upload backend.

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

Tahap 2: Analisis Gerakan Gemini

Backend mengirimkan video yang diupload ke Gemini Flash (gemini-3-flash-preview) untuk analisis terstruktur.

Cara kerjanya (backend/app/services/gemini_service.py):

Layanan ini menggunakan client.models.generate_content() Vertex AI SDK dengan video sebagai input Part.from_uri dan perintah terstruktur. response_mime_type="application/json" memastikan Gemini menampilkan JSON yang dapat diuraikan. Model ini juga menggunakan ThinkingConfig(thinking_budget=1024) untuk penalaran yang lebih baik tentang fase gerakan.

# 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)

Tahap 3: Pembuatan Avatar Nano Banana

Dengan menggunakan frame terbaik yang diekstrak dari video, Gemini Flash Image (gemini-3.1-flash-image-preview) membuat avatar bergaya 1024×1024.

Cara kerjanya (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 avatar yang dibuat diupload ke GCS dan diteruskan ke tahap berikutnya.

Tahap 4: Pembuatan Video Veo

Gambar avatar digunakan sebagai aset referensi untuk Veo 3.1 (veo-3.1-fast-generate-001) guna membuat video AI berdurasi 8 detik.

Cara kerjanya (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,
)

Pembuatan video Veo bersifat asinkron — ID operasi akan segera ditampilkan. Backend melakukan polling operasi hingga selesai (hingga 10 menit).

Tahap 5: Pipeline Pasca-Pemrosesan

Setelah Veo selesai, pipeline latar belakang (backend/app/services/pipeline.py) akan berjalan secara otomatis:

  1. Pangkas output Veo 8 detik menjadi 3 detik
  2. Susun video berdampingan (rekaman asli di sebelah kiri, video AI di sebelah kanan)
  3. Upload video gabungan ke GCS
  4. Lepaskan slot antrean

Pipeline ini berjalan sebagai latar belakang asyncio.Task — frontend kios tidak perlu menunggu.

Sistem Antrean

Karena pembuatan video Veo memerlukan banyak resource, sistem menerapkan maksimum 3 tugas serentak:

# 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,
    }

Frontend memeriksa GET /api/queue/status sebelum mengizinkan pengguna baru memulai sesi. Saat pipeline selesai dan memanggil complete(video_id), slot akan terbuka untuk pengguna berikutnya.

Cloud Run — Container Serverless

Backend dan frontend di-deploy sebagai layanan Cloud Run:

Layanan

Tujuan

Konfigurasi Kunci

Backend

Server API FastAPI

Memori 2 GiB (untuk pemrosesan video melalui ffmpeg)

Frontend

Aplikasi React statis yang ditayangkan oleh Nginx

Memori default

5. ⚙️ Jalankan Skrip Penyiapan

1. Menjalankan Penyiapan Otomatis

Skrip setup.sh akan membuat resource cloud yang diperlukan dan menghasilkan file .env Anda.

👉💻 Jadikan skrip sebagai file yang dapat dieksekusi dan jalankan:

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

2. Memberikan Peran IAM

Sekarang, berikan izin yang diperlukan ke akun layanan.

👉💻 Jalankan perintah berikut untuk menetapkan project ID Anda dan memberikan ketiga peran:

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. Memverifikasi File .env Anda

👉💻 Periksa file .env yang dihasilkan:

cat .env

Anda akan melihat:

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. 🚀 Deploy Backend

1. Memahami Backend Dockerfile

Sebelum men-deploy, mari kita pahami tampilan container:

# 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. Men-deploy ke Cloud Run

👉💻 Muat variabel lingkungan dan deploy:

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"

Proses ini memerlukan waktu sekitar 3-5 menit. Cloud Build akan:

  1. Upload kode sumber Anda
  2. Membangun gambar Docker
  3. Kirim ke Artifact Registry
  4. Deploy ke Cloud Run

3. Simpan URL Backend

👉💻 Setelah di-deploy, simpan URL backend:

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"

4. Memperbarui URL Berbagi Backend

Backend membuat kode QR sehingga pengguna dapat mendownload video mereka. Aplikasi ini perlu mengetahui URL publiknya sendiri untuk melakukannya.

👉💻 Perbarui konfigurasi backend dengan URL-nya sendiri:

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

5. Memverifikasi Backend

👉💻 Uji endpoint health:

curl $BACKEND_URL/api/health

Output yang diharapkan:

{"status":"ok"}

👉💻 Periksa status antrean:

curl $BACKEND_URL/api/queue/status

Output yang diharapkan:

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

7. 🎨 Men-deploy Frontend

1. Memahami Dockerfile Frontend

Frontend menggunakan multi-stage build — pertama-tama membangun aplikasi React, lalu menayangkannya dengan 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. Men-deploy ke Cloud Run

👉💻 Pertama, tulis URL backend ke dalam file .env agar Vite dapat menyajikannya pada waktu build:

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

👉💻 Sekarang deploy frontend:

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

Proses ini memerlukan waktu sekitar 2-3 menit.

3. Mendapatkan URL Frontend

👉💻 Ambil dan buka URL frontend:

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"

👉 Buka URL di browser Anda — Anda akan melihat antarmuka kios Gemini Motion Lab.

8. 🎮 [OPSIONAL] Bermain dengan Demo

1. Merekam Gerakan

  1. Buka URL Frontend di browser Anda (sebaiknya Chrome untuk dukungan kamera terbaik)
  2. Klik Mulai untuk mulai merekam
  3. Menari atau bergerak selama sekitar 5 detik — gerakan lengan yang besar dan pose dinamis akan lebih efektif
  4. Perekaman akan otomatis berhenti dan diupload

2. Tonton Pipeline AI

Setelah mengupload, Anda akan melihat pipeline berjalan secara real time:

Fase

Yang Terjadi

Durasi

Menganalisis...

Gemini Flash menganalisis video Anda untuk mengetahui pola gerakan

~5-10 d

Membuat Avatar...

Nano Banana membuat avatar bergaya dari frame terbaik Anda

~8-12 d

Membuat Video...

Veo 3.1 membuat video AI dari avatar + perintah gerakan

~60-120 dtk

Menyusun...

ffmpeg memangkas dan membuat perbandingan berdampingan

~5-10 d

3. Membagikan Kreasi Anda

Setelah pipeline selesai:

  1. Kode QR akan muncul di layar kios
  2. Pindai kode QR dengan ponsel Anda
  3. Anda akan melihat halaman berbagi yang dioptimalkan untuk seluler dengan video yang Anda buat

4. Memeriksa Log Backend

👉💻 Lihat apa yang terjadi di balik layar:

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

Anda akan melihat baris log yang melacak pipeline:

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. Memantau Antrean

👉💻 Periksa jumlah tugas yang sedang berjalan:

curl $BACKEND_URL/api/queue/status

Jika 3 sesi aktif secara bersamaan, responsnya akan menampilkan:

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

Pengguna baru akan diminta untuk menunggu hingga slot tersedia.

9. 🎉 Kesimpulan

Yang Telah Anda Buat

✅ Analisis Gerakan AI — Gemini Flash menganalisis video untuk mengetahui gerakan, tempo, dan gaya

✅ Pembuatan Avatar — Nano Banana membuat avatar bergaya dari frame video

✅ Pembuatan Video AI — Veo 3.1 membuat video baru yang sesuai dengan gerakan pengguna

✅ Pipeline Asinkron — Pemrosesan latar belakang dengan pengelolaan antrean (maks. 3 serentak)

✅ Komposisi Berdampingan — penggabungan video yang didukung ffmpeg

✅ Deployment Cloud Run — Serverless, penskalaan otomatis, tanpa pengelolaan server

Konsep Utama yang Anda Pelajari

  1. Multimodal Gemini — Mengirim video sebagai input dan menerima analisis JSON terstruktur
  2. Nano Banana (Pembuatan Gambar Gemini) — Menggunakan gambar referensi + perintah gaya untuk membuat avatar
  3. Veo 3.1 — Pembuatan video asinkron dengan aset referensi dan perintah teks
  4. Cloud Run — Men-deploy container dengan variabel lingkungan dan penskalaan otomatis
  5. Pola Pipeline Asinkron — Tugas latar belakang fire-and-forget dengan asyncio.Task untuk operasi AI yang berjalan lama
  6. Pengelolaan Antrean — Membatasi kecepatan tugas AI serentak untuk mengontrol biaya dan kuota API

Ringkasan Arsitektur

Apa Langkah Selanjutnya?

  • Menambahkan gaya avatar lainnya — Mengedit backend/app/prompts/avatar_generation.py
  • Menyesuaikan perintah Veo — Edit backend/app/prompts/video_generation.py
  • Jalankan secara lokal dalam mode tiruan — Tetapkan MOCK_AI=true di .env untuk pengembangan tanpa panggilan API
  • Skala untuk acara — Meningkatkan --max-instances dan MAX_CONCURRENT_JOBS

Resource