Step 4 — Background Images

Status: ✅ Live (Chapter XIV)

Unlocks when: Episode is audio_ready

Advances to: images_ready (on explicit episode approval, after all scenes approved)

Each scene gets one 1280×720 background image generated by Imagen 4 Fast via the Gemini API ($0.02/image). No local GPU required.

How It Works

1. Scene 1 is active — "Generate" button visible, rest locked
2. Click Generate → Imagen API call (~5–10 seconds) → image appears
3. Edit mood_brief (used for reuse embeddings) or image_prompt (full prompt sent to Imagen — can be the full scene prose) as needed
4. Click Approve → Gemini Vision auto-describes the approved image → description overwrites mood_brief → embedded into vec_chunks → next scene unlocks
5. All scenes approved → "Approve Backgrounds" button → episode advances to images_ready

Prompt System

Two separate fields per scene: - mood_brief — short visual description. Used for reuse lookup via vec_chunks embeddings. Updated by Gemini Vision on approval. - image_prompt — full prompt sent to Imagen. Defaults to mood_brief if empty. Can be the full scene prose for richer generation.

Image Reuse

Before generating, the pipeline queries vec_chunks for a semantically similar existing image (threshold: distance ≤ 0.4). If a match is found, the existing image is reused. Reuse is skipped when explicitly regenerating.

File Naming

Images stored globally at media/studio/images/ — agnostic to project, episode, or scene: - Generated: scene_NNN_bg_proposal01.png, proposal02, etc. - On approval: old canonical archived as scene_NNN_bg_old01.png, proposal promoted to scene_NNN_bg.png

Gemini Vision Description

On approval, the approved image is sent to Gemini 2.5-flash Vision which generates a concise visual description. This overwrites mood_brief with an accurate description of what's actually in the image — more precise than the pre-generation brief. The description is then embedded into vec_chunks for future reuse matching.

Visual Style

Each StudioProject has a visual_style field — a multi-sentence description of the series' visual aesthetic (color palette, lighting, atmosphere). Generated by Gemini at project creation and editable on the project detail page. Appended to every Imagen prompt. Should describe aesthetic only — interior/exterior is determined by each scene's image_prompt.

Service

studio/service.py: - run_scene_image(episode_id, scene_id, skip_reuse) — background thread, saves image_path - approve_scene_image(episode_id, scene_id) — Vision description, mood_brief update, embedding, rename proposal→canonical - regenerate_scene_image(episode_id, scene_id) — skips reuse, re-runs with next proposal number - approve_images(episode_id) — advances to images_ready - search_scene_images(mood, threshold, limit) — KNN reuse lookup - _describe_image(abs_path) — Gemini Vision call, returns description string

studio/image_gen.py — pure Python, zero Django imports. generate_image(prompt, output_path, api_key, model_name) calls Imagen 4 Fast.

Model: imagen-4.0-fast-generate-001 (IMAGE_MODEL_NAME env var)

Management command: python manage.py check_image_embeddings — inspect vec_chunks for scene image embeddings.