Melies CLI

AI filmmaking from the command line. 148 AI actors, 98 visual styles, 50+ models. Generate images, videos, posters, and YouTube thumbnails without prompt engineering.

Install

npm install -g melies

Authentication

# Browser login (opens melies.co, authenticates automatically)
melies login

# Or use an API token directly (for CI/agents)
melies login --token YOUR_TOKEN

# Or set as environment variable
export MELIES_TOKEN=your_token

Generate an API token at melies.co > Settings > API.

Output Format

By default, browse commands (

credits

models

actors

assets

styles

--json

Generation commands (

image

video

poster

thumbnail

pipeline

upscale

remove-bg

Quick Start

# Generate an image with an AI actor, Ghibli style, and golden lighting
melies image "portrait in a café" --actor mei --art-style ghibli --lighting golden --sync

# Generate a movie poster with a preset style
melies poster "Neon Shadows" --style noir --actor james --sync

# Image → video pipeline in one command
melies pipeline "warrior on a cliff at sunset" --actor mei --best --sync

# Generate 4 YouTube thumbnails
melies thumbnail "shocked face reacting to AI news" --actor aria -n 4 --sync

# Preview cost before generating
melies image "sunset" --quality --actor hailey --dry-run

Smart Model Selection

No model names needed. Use quality presets:

--fast

--quality

--best

-m <id>

-m

melies models

Visual Style Flags

Add these flags to any

image

video

thumbnail

pipeline

--camera

--shot

--expression

--lighting

--time

--weather

--color-grade

--mood

--art-style

--era

Multiple flags combine. Example:

melies image "woman in a café" --lighting golden --mood romantic --art-style ghibli --sync

Commands

melies image <prompt>

Generate images from text.

melies image "sunset over mountains" --quality --sync
melies image "portrait" --actor mei --lighting golden --sync
melies image "cyberpunk city" --art-style neo-noir --mood gritty -n 4 --sync
melies image "product photo" -a 1:1 --best --sync --output photo.webp

Options:

• -m, --model

  Model override (use quality presets instead)

• -a, --aspectRatio

  1:1, 16:9, 9:16, 4:3, 3:4 (default: 1:1)

• -n, --numOutputs

  1-4 images (default: 1)

• -r, --resolution

  Output resolution (model-dependent)

• -i, --imageUrl

  Reference image for img2img

• --ref

  Reference ID for custom characters (see

  melies ref

  )

• --actor

  Built-in AI actor name (see

  melies actors

  )

• --sref

  Style reference code (see

  melies styles

  )

• --fast

  /

  --quality

  /

  --best

  Quality presets

• --camera

  ,

  --shot

  ,

  --expression

  ,

  --lighting

  ,

  --time

  ,

  --weather

  ,

  --color-grade

  ,

  --mood

  ,

  --art-style

  ,

  --era

  Visual style flags

• --seed

  Reproducible generation

• --dry-run

  Preview prompt, model, and cost without generating

• -o, --output

  Save file to path (use with --sync)

• -s, --sync

  Wait for completion

melies video <prompt>

Generate videos from text or images.

melies video "drone shot over forest" --quality --sync
melies video "walking down the street" --actor mei --camera low --sync
melies video "zoom into product" -i https://example.com/product.jpg --sync

Options: Same as

image

• -d, --duration

  Video duration in seconds
• Default aspect ratio is 16:9
• Sync timeout is 5 minutes

melies poster <title>

Generate movie posters with style presets.

melies poster "Neon Shadows" --style noir --sync
melies poster "The Last Garden" --style anime --genre drama --actor mei --sync
melies poster "Blood Moon" -l "A detective hunts a killer" -g horror --quality --sync

Options:

• -l, --logline

  Short synopsis

• -g, --genre

  Genre (horror, sci-fi, comedy, drama, etc.)

• --style

  Poster preset: cinematic, anime, retro, film-noir, minimalist, horror, sci-fi, watercolor, comic-book, art-deco, grindhouse, bollywood, western, pixel-art, surrealist, documentary, cartoon, epic-fantasy, indie-film, neon-noir

• --actor

  AI actor name

• --fast

  /

  --quality

  /

  --best

  Quality presets

• --seed

  ,

  --dry-run

  ,

  --output

  ,

  --sync

melies thumbnail <prompt>

Generate YouTube thumbnails (forced 16:9, optimized for click-through).

melies thumbnail "shocked face reacting to AI news" --actor aria -n 4 --sync
melies thumbnail "cooking tutorial intro" --actor sofia --expression smile --quality --sync

Options: Same as

image

melies pipeline <prompt>

Generate an image then animate it into a video. One command, both steps.

melies pipeline "warrior on a cliff at sunset" --actor mei --art-style concept --best --sync
melies pipeline "serene lake at dawn" --mood ethereal --lighting golden --sync

Options:

• --im

  Image model override

• --vm

  Video model override

• -a, --aspectRatio

  Ratio for both steps (default: 16:9)

• -d, --duration

  Video duration
• All style flags,

  --actor

  , quality presets,

  --dry-run

  ,

  --output

• Sync defaults to true

Returns

{ imageUrl, videoUrl }

melies upscale <imageUrl>

Upscale an image to higher resolution.

melies upscale "https://..." --model esrgan --scale 2 --sync
melies upscale "https://..." --model clarity --scale 4 --sync

Models: esrgan (3cr), clarity (8cr), seedvr2 (5cr). Scale 4x costs double.

melies remove-bg <imageUrl>

Remove background from an image. Returns transparent PNG.

melies remove-bg "https://..." --sync

Cost: 3 credits.

melies actors

Browse 148 built-in AI actors.

melies actors                              # List all actors
melies actors --type influencer            # Filter by type
melies actors --gender female --age 20s    # Filter by gender and age
melies actors search "asian"               # Search by name/tags
melies actors --json                       # JSON output for parsing

melies styles

Browse 220+ visual style flags (art styles, lighting, camera angles, expressions, moods, and more).

melies styles                              # Overview of all categories
melies styles --type lighting              # All values for a category
melies styles search "neon"                # Search across all categories
melies styles --json                       # JSON output for parsing

melies credits

Check credit balance and usage.

melies credits                             # Human-readable table
melies credits --json                      # JSON output for parsing
melies credits -g day

melies models

List available AI models.

melies models                    # All models
melies models -t image           # Image models only
melies models -t video           # Video models only
melies models --json             # JSON output for parsing

melies status <assetId>

Check generation job status.

melies status 6502a3b1f2e4a123456789ab

melies assets

List recent generated assets.

melies assets                              # Recent assets
melies assets -l 50 -t text_to_image       # Filter by type
melies assets --json                       # JSON output for parsing

melies ref

Manage custom AI actor/object references.

melies ref list
melies ref create "John" -i https://example.com/john.jpg
melies ref delete <id>

Common Patterns

YouTube Thumbnail Pipeline with AI Actors

melies thumbnail "shocked face reacting to AI news" \
  --actor aria --expression surprised -n 4 --sync

Consistent Character Across Media

# Same actor in different scenes
melies image "Mei in a coffee shop" --actor mei --lighting soft --sync
melies image "Mei on a mountain" --actor mei --mood epic --sync
melies video "Mei walks toward camera" --actor mei --camera low --sync

Image → Video Pipeline

melies pipeline "a warrior on a cliff at sunset" \
  --actor mei --art-style concept --lighting golden \
  --best --sync

Movie Poster Batch

melies poster "Neon Requiem" --style neon-noir --sync
melies poster "Whispers in the Dark" --style horror -l "A blind woman hears the dead" --sync
melies poster "Starbound" --style sci-fi -l "Humanity's last colony ship" --sync

Dry Run Before Expensive Generation

# Preview everything without spending credits
melies pipeline "epic battle scene" --actor james --best --dry-run

Budget-Aware Generation

CREDITS=$(melies credits --json | jq '.credits')
if [ "$CREDITS" -gt 100 ]; then
  melies video "Epic aerial shot" --best --sync
else
  melies image "Epic aerial shot" --fast --sync
fi

Credit Costs

Gotchas

1. Generation is async by default. Use

   --sync

   to wait for results.
2. Video generation takes time. 30s to 3min depending on model.

   --sync

   waits up to 5 min.
3. Credits are deducted upfront. Refunded automatically on failure.
4. Actor names are case-insensitive.

   --actor Mei

   and

   --actor mei

   both work.
5. Style flags combine.

   --lighting golden --mood romantic --art-style ghibli

   all apply to one generation.
6. Pipeline defaults to sync. It needs to wait for the image before generating the video.
7. --dry-run shows the full prompt. Useful for debugging what modifiers get applied.
8. Poster --style is separate from --art-style. Poster styles are preset poster designs. Art styles are visual rendering options.
9. Token expiry. If you get 401 errors, run

   melies login

   again.
10. Rate limits. Max 1000 requests per 15 minutes.

Environment Variables

MELIES_TOKEN

MELIES_API_URL

Quick Reference

melies image "prompt" --actor <name> --art-style <style> --quality --sync
melies video "prompt" --actor <name> --lighting <light> --best --sync
melies poster "title" --style <preset> -g <genre> --sync
melies thumbnail "prompt" --actor <name> -n 4 --sync
melies pipeline "prompt" --actor <name> --best --sync
melies upscale <url> --scale 2 --sync
melies remove-bg <url> --sync
melies actors search "query"
melies styles search "keyword"
melies credits
melies models

Links

• Melies Agent Page
• Documentation
• agentskill.sh
• ClawHub