Studio Lumiere CLI

Local SDK + CLI for AI-powered jewelry product photography. Generate editorial-quality images, videos, and compositions from reference jewelry photos.

npx studio-lumiere-cli <command> [options]

Setup

1. Install dependencies

npm install

2. Create .env

GEMINI_API_KEY=your_key_here
LUMIERE_OUTPUT_DIR=outputs

Commands

| Command | Description | |---------|-------------| | generate | Generate styled jewelry product images | | refine | Apply refinement instructions to an existing image | | upscale | Upscale an image to higher resolution | | muse | Create a consistent character reference ("Muse") | | video | Generate video from a text prompt | | tired-girl | Generate "before" / casual aesthetic images | | annotate | Overlay text on an image | | grid | Combine multiple images into a grid layout | | list | List available templates, backgrounds, vibes, etc. |

generate

Generate styled jewelry product images using AI.

lumiere generate --images <paths> --template <id> [options]

Required

| Flag | Description | |------|-------------| | --images <paths> | Comma-separated input image paths | | --template <id> | Template ID (see Templates) |

Customization

| Flag | Description | |------|-------------| | --detail <id> | Primary customization (template-specific) | | --secondary-detail <id> | Secondary customization | | --tertiary-detail <id> | Tertiary customization | | --ethnicity <id> | Model ethnicity | | --skin-tone <id> | Model skin tone | | --hair-color <id> | Model hair color | | --background <id> | Background color/texture | | --background-type <id> | Background type (studio, interior, exterior, texture) | | --vibe <id> | Photography mood/style | | --resolution <id> | Output aspect ratio (default: portrait) | | --occasion <id> | Special occasion theme |

Generation

| Flag | Description | |------|-------------| | --quantity <n> | Number of images to generate (default: 1) | | --muse-id <id> | Muse ID for consistent model appearance | | --muse-images <paths> | Comma-separated Muse reference image paths | | --no-enhance | Skip LLM prompt enhancement |

Example

lumiere generate \
  --images "ring.jpg" \
  --template hand_model \
  --detail nail_red \
  --background velvet_black \
  --vibe golden_hour \
  --quantity 4

refine

Apply refinement instructions to an existing generated image.

lumiere refine --image <path> --instruction <text> [options]

| Flag | Description | |------|-------------| | --image <path> | (required) Path to image to refine | | --instruction <text> | (required) Refinement instruction | | --size <percent> | Resize jewelry to given percentage (e.g. 80 = smaller, 120 = larger) |

lumiere refine --image "output.png" --instruction "make the background warmer"
lumiere refine --image "output.png" --instruction "adjust jewelry" --size 80

upscale

Upscale an image to higher resolution.

lumiere upscale --image <path> [--scale <n>]

| Flag | Description | |------|-------------| | --image <path> | (required) Path to image | | --scale <n> | Scale factor (default: 2) |

muse

Create a Muse (consistent character reference) from a source image. Used with the half_body_muse template for identity-consistent generations.

lumiere muse --name <name> --source <path> [--variations <n>]

| Flag | Description | |------|-------------| | --name <name> | (required) Name for the Muse | | --source <path> | (required) Path to source image | | --variations <n> | Number of variations to generate (default: 3) |

lumiere muse --name "Sarah" --source "reference.jpg"
lumiere generate --images "necklace.jpg" --template half_body_muse --muse-id sarah

video

Generate a short video from a text prompt.

lumiere video --prompt <text> [options]

| Flag | Description | |------|-------------| | --prompt <text> | (required) Video description | | --aspect <ratio> | Aspect ratio (1:1, 3:4, 9:16, 16:9) | | --duration <seconds> | Duration in seconds |

Video-enabled templates: hand_model, neck_model, ear_model, flatlay_creative, floating_minimal, half_body_muse.

tired-girl

Generate "tired girl" / "before" aesthetic images showing a model in casual, un-styled looks (no jewelry).

lumiere tired-girl [options]

| Flag | Description | |------|-------------| | --muse-id <id> | Muse ID for identity reference | | --image <path> | Single reference image (if no Muse) | | --styles <ids> | Comma-separated style IDs | | --quantity <n> | Number of images (default: 1) |

Available styles

| ID | Description | |----|-------------| | tired | Slightly tired, soft under-eye shadows, relaxed expression | | morning | Freshly awake, morning light, sleepy energy | | no_makeup | Completely bare faced | | crazy_hair | Messy, unstyled wild hair | | pyjama | Cozy pajamas or loungewear |

lumiere tired-girl --muse-id sarah --styles "tired,no_makeup" --quantity 2

annotate

Overlay text on an image with customizable styling.

lumiere annotate --input <path> --output <path> --text <text> [options]

Required

| Flag | Description | |------|-------------| | --input <path> | Input image path | | --output <path> | Output image path | | --text <text> | Text to overlay |

Text styling

| Flag | Default | Description | |------|---------|-------------| | --font <name> | Poppins | Font family | | --size <px> | auto | Font size in pixels | | --weight <n> | 700 | Font weight | | --color <hex> | #FFFFFF | Text color | | --stroke-color <value> | rgba(0,0,0,0.6) | Text outline color | | --stroke-width <px> | fontSize * 0.08 | Text outline width |

Banner

| Flag | Default | Description | |------|---------|-------------| | --banner | off | Enable semi-transparent banner behind text | | --banner-color <value> | rgba(0,0,0,0.45) | Banner color | | --banner-padding <px> | fontSize * 0.6 | Banner padding | | --banner-radius <px> | fontSize * 0.4 | Banner corner radius |

Position

| Flag | Default | Description | |------|---------|-------------| | --position <pos> | bottom-center | One of: top-center, top-left, top-right, bottom-center, bottom-center-high, bottom-left, bottom-right, center | | --padding <px> | auto | Padding from edges | | --max-width <ratio> | auto | Max text width as ratio of image width (0-1) |

lumiere annotate \
  --input "image.jpg" \
  --output "branded.jpg" \
  --text "New Collection" \
  --position bottom-center \
  --banner \
  --size 48

grid

Combine multiple images into a grid layout.

lumiere grid --inputs <paths> --output <path> [options]

| Flag | Default | Description | |------|---------|-------------| | --inputs <paths> | | (required) Comma-separated image paths | | --output <path> | | (required) Output image path | | --columns <n> | 2 | Number of columns | | --rows <n> | 2 | Number of rows | | --padding <px> | 20 | Padding between tiles | | --background <hex> | #000000 | Background color | | --tile-width <px> | auto | Fixed tile width | | --tile-height <px> | auto | Fixed tile height |

lumiere grid \
  --inputs "img1.jpg,img2.jpg,img3.jpg,img4.jpg" \
  --output "grid.jpg" \
  --columns 2 --rows 2 \
  --padding 10 --background "#FFFFFF"

list

List available options for any category. Output is JSON.

lumiere list <type>

| Type | Description | |------|-------------| | templates | All templates with their customization options | | ethnicities | Model ethnicity options | | skin-tones | Skin tone options | | hair-colors | Hair color options | | backgrounds | Background color/texture options | | background-types | Background type options | | vibes | Photography mood options | | resolutions | Aspect ratio options | | occasions | Special occasion themes |

Templates

hand_model -- Hand Model

Close-up of a model's hand, wrist, and forearm. Perfect for rings and bracelets.

| Customization | Options | |---------------|---------| | Nail Polish (--detail) | nail_nude Soft Nude, nail_red Classic Red, nail_french French Manicure, nail_natural Natural & Clean, nail_dark Noir / Dark |

neck_model -- Neckline Portrait

Waist-up portrait focusing on the neck and collarbone. Ideal for necklaces and pendants.

| Customization | Options | |---------------|---------| | Wardrobe (--detail) | wear_skin Bare Skin, wear_silk White Silk Shirt, wear_black Black Turtleneck, wear_gown Evening Gown, wear_kaftan Modern Kaftan | | Makeup (--tertiary-detail) | makeup_none Bare, makeup_minimal Minimal, makeup_soft Soft Glam, makeup_full Full Glam, makeup_editorial Editorial |

ear_model -- Ear Detail

Intimate side profile shot. Best for earrings.

| Customization | Options | |---------------|---------| | Hairstyle (--detail) | hair_tucked Tucked Behind Ear, hair_updo Elegant Updo, hair_waves Loose Waves, hair_sleek Sleek & Straight | | Makeup (--tertiary-detail) | makeup_none Bare, makeup_minimal Minimal, makeup_soft Soft Glam, makeup_full Full Glam, makeup_editorial Editorial |

flatlay_creative -- Creative Flatlay

Artistic still-life composition on a surface. No model. Great for any jewelry type.

| Customization | Options | |---------------|---------| | Surface (--detail) | surf_marble White Marble, surf_stone Dark Slate, surf_velvet Beige Velvet, surf_wood Aged Wood, surf_sand Fine Sand, surf_pedestal Geometric Pedestal, surf_riser Stone Riser |

floating_minimal -- Floating Minimalist

Jewelry suspended in mid-air with dramatic lighting. No model.

| Customization | Options | |---------------|---------| | Lighting (--detail) | light_soft Soft & Diffused, light_hard Hard Contrast, light_warm Golden Glow, light_cool Cool Steel |

half_body_muse -- The Editorial Muse

Dynamic waist-up fashion shot. The only template that supports Muse (consistent model identity).

| Customization | Options | |---------------|---------| | Outfit (--detail) | outfit_blazer Power Suit, outfit_evening Evening Glamour, outfit_linen Resort Linen, outfit_knit Cashmere Knit, outfit_silk Silk Shirt, outfit_turtleneck Turtleneck | | Nail Polish (--secondary-detail) | nail_nude Soft Nude, nail_red Classic Red, nail_french French Manicure, nail_natural Natural & Clean, nail_dark Noir / Dark | | Makeup (--tertiary-detail) | makeup_none Bare, makeup_minimal Minimal, makeup_soft Soft Glam, makeup_full Full Glam, makeup_editorial Editorial | | Pose (quaternary) | pose_winking, pose_grimace, pose_teasing, pose_kiss, pose_laughing, pose_pout, pose_peace |

romance_proposal -- Romance & Proposal

Emotional engagement ring moments with a couple.

| Customization | Options | |---------------|---------| | Moment (--detail) | moment_proposal The Proposal, moment_said_yes Just Said Yes, moment_hand_in_hand Hand in Hand, moment_dinner Intimate Dinner, moment_promise The Promise | | Setting (--secondary-detail) | setting_garden Garden, setting_restaurant Candlelit Restaurant, setting_beach Beach at Sunset, setting_home Cozy at Home, setting_rooftop Rooftop City Views, setting_winter Winter Snow | | Nail Polish (--tertiary-detail) | nail_nude Soft Nude, nail_red Classic Red, nail_french French Manicure, nail_natural Natural & Clean, nail_dark Noir / Dark |

museum_exhibit -- Museum Exhibit

Jewelry displayed as a priceless museum artifact. No model.

| Customization | Options | |---------------|---------| | Museum Style (--detail) | museum_classical Classical Gallery, museum_modern Modern Art Museum, museum_baroque Baroque Palace, museum_art_deco Art Deco Gallery | | Display Type (--secondary-detail) | display_vitrine Glass Vitrine, display_pedestal Velvet Pedestal, display_stand Open Display, display_wall Wall Mount, display_alcove Illuminated Alcove |

romantic_mood -- Romantic Mood

Jewelry styled as a romantic still life with props. No model.

| Customization | Options | |---------------|---------| | Props (--detail) | prop_rose_petals Rose Petals, prop_candles Candlelight, prop_love_letter Love Letter, prop_silk_lace Silk & Lace, prop_fresh_roses Fresh Roses, prop_gift_box The Gift | | Mood (--secondary-detail) | mood_candlelight Warm Candlelight, mood_morning Soft Morning Light, mood_moody Moody & Dark, mood_golden Golden Hour Glow, mood_blush Blush Pink Haze |

Global Options

Ethnicities (--ethnicity)

| ID | Name | |----|------| | european | European | | moroccan | Moroccan | | middle_east | Middle Eastern | | african | African | | asian | East Asian |

Skin Tones (--skin-tone)

| ID | Name | |----|------| | fair | Porcelain | | light | Light | | medium | Tan | | deep | Deep | | dark | Ebony |

Hair Colors (--hair-color)

| ID | Name | |----|------| | dark | Dark / Black | | brunette | Brunette | | blonde | Blonde | | red | Red / Auburn | | grey | Silver / Grey |

Backgrounds (--background)

| ID | Name | |----|------| | silk_cream | Cream Silk | | velvet_black | Midnight Velvet | | marble_white | Carrara Marble | | emerald_velvet | Emerald Velvet | | studio_grey | Studio Grey | | warm_beige | Warm Beige | | burgundy_velvet | Burgundy Velvet | | champagne_gold | Champagne Gold | | navy_sapphire | Navy Sapphire | | blush_rose | Blush Rose | | ivory_pearl | Ivory Pearl | | slate_charcoal | Slate Charcoal |

Background Types (--background-type)

| ID | Name | |----|------| | studio | Studio Flat | | interior | Luxury Interior | | exterior | Outdoors | | texture | Macro Texture |

Vibes (--vibe)

| ID | Name | |----|------| | golden_hour | Golden Hour -- warm natural sunlight | | moody_chic | Moody Chic -- dramatic shadows, high contrast | | clean_minimal | Clean Minimal -- bright, airy, minimalist | | romantic_soft | Romantic -- soft focus, pastel tones |

Resolutions (--resolution)

| ID | Aspect Ratio | Best for | |----|-------------|----------| | square | 1:1 | Instagram Feed | | portrait | 3:4 | Instagram Feed (vertical) | | story | 9:16 | Instagram Stories / Reels | | landscape | 16:9 | Website / Ads |

Occasions (--occasion)

Occasions auto-configure vibe, background, and background type, and inject thematic prompt details.

| ID | Name | |----|------| | moroccan_wedding | Moroccan Wedding | | eid_fitr | Eid al-Fitr | | eid_adha | Eid al-Adha | | henna_night | Henna Night | | ramadan | Ramadan | | valentines | Valentine's Day | | mothers_day | Mother's Day | | birthday | Birthday | | anniversary | Anniversary | | graduation | Graduation | | christmas | Christmas | | new_year | New Year |

SDK Usage

import { generateImages } from "studio-lumiere-cli";

const result = await generateImages(
  { apiKey: "your-key", outputDir: "outputs" },
  {
    inputImages: ["./ring.jpg"],
    quantity: 4,
    selections: {
      templateId: "hand_model",
      detailId: "nail_red",
      backgroundId: "velvet_black",
      vibeId: "golden_hour",
      resolutionId: "portrait",
    },
  }
);

Notes

• Templates, backgrounds, vibes, and all shared options are synced from the main Studio Lumiere web app at build time (npm run sync). The CLI always matches the web app.
• The Muse flow generates variations and stores a local muses.json index under your output directory.
• Video generation uses Veo via the Gemini SDK and returns an operation name plus the video file when available.