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.

intent

melies is an AI filmmaking CLI that generates high-quality images, videos, posters, and thumbnails using 148 pre-built AI actors and 98 visual styles. instead of writing complex prompts, you use simple flags like --actor, --lighting, --mood, and --art-style to control output. use melies when you need production-ready visual content fast, from single images to full video pipelines, without spending credits on prompt iteration.

inputs

required

• MELIES_TOKEN: JWT auth token (get it from melies.co > Settings > API). set as environment variable or use melies login --token <TOKEN>.
• melies CLI: install via npm install -g melies.

optional but recommended

• MELIES_API_URL: API base endpoint (defaults to https://melies.co/api). override only if using self-hosted melies.
• ~/.melies/config.json: auto-created after first melies login. stores token and user settings.
• credit balance: check with melies credits before expensive operations. operations are charged upfront and auto-refunded on failure.

external data

• reference images for img2img: pass via -i, --imageUrl https://... for image or video generation.
• custom character references: upload via melies ref create to reuse custom actors across generations.
• style reference codes: browse with melies styles search <keyword> and use --sref <code> flag.

edge cases

• token expiry: melies tokens may expire after extended periods. if you get 401 errors, re-run melies login.
• rate limits: 1000 requests per 15 minutes per account. async generations count as 1 request each.
• network timeouts: sync operations (--sync) timeout after 5 minutes for video, 2 minutes for image. fall back to polling with melies status <assetId>.
• empty credit balance: operations fail with "insufficient credits" error. no charges incur if balance is too low.
• missing actor/style: invalid --actor or --sref values return 400 with suggestion list.

procedure

setup

1. install melies: run npm install -g melies to add cli to PATH.
2. authenticate: run melies login (opens browser) or melies login --token <TOKEN> (non-interactive).
   • input: none (browser login) or TOKEN string.
   • output: auth token stored in ~/.melies/config.json. shell prints "logged in as ".
3. verify installation: run melies credits to confirm token works.
   • input: none.
   • output: json with { credits: <number>, usage: {...} }.

generate a single image

4. compose command: build melies image <prompt> with optional flags.

   • input: prompt string (required), one or more of --actor <name>, --lighting <type>, --mood <mood>, --art-style <style>, -a <ratio>, --quality or --best or --fast (default), -n <count>, --seed <number>, -o <filepath>.
   • output: if using --sync, json with { imageUrl: "...", cost: <credits> }. if no sync, json with { assetId: "...", status: "pending" }.

5. example basic image:

   melies image "sunset over mountains" --quality --sync
   

   • input: prompt "sunset over mountains", quality preset.
   • output: { imageUrl: "https://...", cost: 8 } (waits up to 2 min).

6. example with actor and style flags:

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

   • input: prompt, actor name, three style modifiers, quality preset (default --fast).
   • output: 1x image url with applied styles, cost deducted.

7. dry-run before spending credits:

   melies image "cyberpunk city" --art-style neo-noir --mood gritty --best --dry-run
   

   • input: full command with --dry-run flag.
   • output: json with expanded prompt, chosen model, and estimated cost. no credits deducted.

generate multiple images in batch

8. batch generation: use -n <count> (1-4 images per call).

   melies image "cyberpunk city" --art-style neo-noir --mood gritty -n 4 --sync
   

   • input: prompt, -n 4 flag.
   • output: array of 4 image urls, total cost multiplied by 4.

generate video from text

9. text-to-video:

   melies video "drone shot over forest" --quality --sync
   

   • input: prompt, quality preset.
   • output: video url (if sync, waits up to 5 min). cost 30-400 credits depending on preset.

10. video with actor and camera angle:

    melies video "walking down the street" --actor mei --camera low --sync
    

    • input: prompt, actor, camera flag.
    • output: video url with specified framing.

image-to-video (img2img)

11. reference image for consistency:

    melies video "zoom into product" -i https://example.com/product.jpg --sync
    

    • input: video prompt, -i <imageUrl> (reference, not keyframe), quality preset.
    • output: video based on reference image aesthetic.

12. image-to-video pipeline (image + video in one call):

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

    • input: prompt, actor, style flags, quality preset.
    • output: { imageUrl: "...", videoUrl: "...", cost: <imageCredits + videoCredits> }. pipeline generates image first, then animates it. costs both image and video credits.

generate thumbnails

13. youtube thumbnails:

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

    • input: prompt, actor, expression flag, -n 4 count.
    • output: 4x 16:9 thumbnails optimized for click-through. aspect ratio forced to 16:9.

generate movie posters

14. poster with preset style:

    melies poster "Neon Shadows" --style noir --sync
    

    • input: title, --style <preset> (cinematic, anime, horror, sci-fi, etc.).
    • output: poster image url.

15. poster with logline and genre:

    melies poster "Blood Moon" -l "A detective hunts a killer" -g horror --quality --sync
    

    • input: title, -l <logline>, -g <genre>, optional actor, quality preset.
    • output: poster with genre-specific visual treatment.

upscale images

16. upscale 2x or 4x:

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

    • input: image url, model (esrgan, clarity, seedvr2), scale (2 or 4).
    • output: upscaled image url. costs 3-5 credits (doubled for 4x scale).

remove background

17. transparent background removal:

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

    • input: image url.
    • output: png with transparent background. costs 3 credits.

browse actors and styles

18. list all actors:

    melies actors
    

    • input: none.
    • output: table of 148 actors with names, types, and tags.

19. filter actors by type/gender/age:

    melies actors --type influencer --gender female --age 20s
    

    • input: one or more filter flags.
    • output: filtered actor list.

20. search actors:

    melies actors search "asian"
    

    • input: search term (name or tag).
    • output: matching actors.

21. browse style references:

    melies styles search "cyberpunk"
    melies styles top
    melies styles info 1234567
    

    • input: keyword or style code.
    • output: matching styles with sref codes and popularity.

check credit balance and job status

22. view credits:

    melies credits
    melies credits -g day
    

    • input: optional -g <granularity> (day, week, month).
    • output: { credits: <int>, usage: [...] }.

23. check job status by id:

    melies status 6502a3b1f2e4a123456789ab
    

    • input: asset id (returned from async generate).
    • output: { status: "completed" | "pending" | "failed", result: {...} }.

24. list recent assets:

    melies assets -l 50 -t text_to_image
    

    • input: optional -l <limit>, -t <type> (text_to_image, text_to_video, etc.).
    • output: array of recent generations with urls and timestamps.

manage custom actor references

25. create custom actor:

    melies ref create "John" -i https://example.com/john.jpg
    

    • input: name, reference image url.
    • output: ref id. use --ref <id> in future image/video commands.

26. list custom refs:

    melies ref list
    

    • input: none.
    • output: all custom refs with ids and upload dates.

27. delete custom ref:

    melies ref delete <id>
    

    • input: ref id.
    • output: success message.

save output to file

28. save generated image/video:

    melies image "sunset" --quality --sync -o photo.webp
    melies video "forest" --quality --sync -o movie.mp4
    

    • input: generation command + -o <filepath>.
    • output: file written to disk at filepath. url also returned in json.

decision points

quality preset selection

• if you have 2-8 credits available and speed matters: use --fast (default) or no flag. flux-schnell image (2cr), kling-v2 video (30cr).
• if you have 8-100 credits and want good quality: use --quality. flux-pro image (8cr), kling-v3-pro video (100cr).
• if you have 100+ credits and want best output: use --best. seedream-3 image (6cr), veo-3.1 video (400cr).
• if you need exact control over model: use -m <model_id> to override presets. query melies models for full list.

sync vs async

• if you need the url immediately: use --sync. blocks until generation completes (timeout: 2 min image, 5 min video).
• if you're in a batch workflow or running low on time: omit --sync. returns asset id, poll later with melies status <assetId>.
• if you're scripting and need the result: use --sync and pipe json output to jq.
• exception: pipeline defaults to sync (needs image before video). remove --sync only if you manually poll both steps.

actor consistency

• if you're generating multiple images/videos of the same character: use same --actor <name> across all commands. actor name is case-insensitive.
• if you need a custom character that's not in the 148 built-ins: use melies ref create once, then --ref <id> in future commands.
• if you want randomness: omit --actor flag. each generation picks a random actor.

poster vs art-style

• if you're generating a movie poster: use --style <preset> (noir, anime, horror, etc.). these are full poster design templates.
• if you're using art-style flag on poster: it applies to the artwork within the poster, separate from the poster template. combine both flags for full control.

dry-run before expensive ops

• if cost is unclear: run command with --dry-run flag. prints full expanded prompt, chosen model, and estimated cost. zero credits deducted.
• if you're about to spend 100+ credits: always dry-run first. catches unexpected prompt expansions or model mismatches.

handling auth expiry

• if you get 401 unauthorized errors: run melies login or melies login --token <NEW_TOKEN>. token may have expired after 30+ days.
• if you're in ci/automation and token expires: set MELIES_TOKEN env var to a fresh token. no interactive login needed.

rate limiting

• if you hit 1000 requests in 15 minutes: wait 15 minutes. subsequent requests fail with 429 too-many-requests.
• if you're bulk-generating: stagger requests with sleep 1 between async (non-sync) calls. async ops count as 1 request each regardless of output count.

no credits remaining

• if melies credits shows 0: any generation fails with "insufficient credits" error before charge. add credits at melies.co and retry.
• exception: credits are deducted upfront but auto-refunded if generation fails (e.g., invalid prompt, timeout). check credits again after failure.

reference images and img2img

• if you want the video to look like a reference image: use -i <imageUrl> in video command. melies uses reference for style/aesthetic, not as actual keyframe.
• if you want to upscale or modify an existing image: use upscale or remove-bg commands, or img2img with image command (-i <url>).

output contract

all melies commands return json (not pretty-printed by default). pipe to jq for readability or scripting.

single image generation

{
  "imageUrl": "https://melies.co/assets/abc123.webp",
  "cost": 2,
  "seed": 42,
  "model": "flux-schnell"
}

multiple images (n > 1)

{
  "images": [
    { "imageUrl": "...", "seed": 123 },
    { "imageUrl": "...", "seed": 124 }
  ],
  "cost": 4,
  "model": "flux-schnell"
}

video generation

{
  "videoUrl": "https://melies.co/assets/vid456.mp4",
  "cost": 30,
  "duration": 5,
  "model": "kling-v2"
}

pipeline (image + video)

{
  "imageUrl": "https://melies.co/assets/img789.webp",
  "videoUrl": "https://melies.co/assets/vid789.mp4",
  "cost": 32,
  "models": { "image": "flux-schnell", "video": "kling-v2" }
}

async response (no --sync)

{
  "assetId": "6502a3b1f2e4a123456789ab",
  "status": "pending",
  "type": "text_to_image"
}

status check

{
  "assetId": "6502a3b1f2e4a123456789ab",
  "status": "completed",
  "result": { "imageUrl": "..." }
}

upscale

{
  "upscaledUrl": "https://melies.co/assets/upscaled.webp",
  "scale": 2,
  "cost": 3,
  "model": "esrgan"
}

remove background

{
  "imageUrl": "https://melies.co/assets/transparent.png",
  "cost": 3
}

credit balance

{
  "credits": 247,
  "usage": [
    { "date": "2025-01-15", "spent": 10, "operations": 5 }
  ]
}

actors list

{
  "actors": [
    {
      "name": "mei",
      "type": "anime",
      "gender": "female",
      "age": "20s",
      "tags": ["asian", "friendly"]
    }
  ],
  "total": 148
}

styles list

{
  "styles": [
    {
      "sref": "1234567",
      "keyword": "cyberpunk",
      "popularity": 1200
    }
  ]
}

save to file with -o

output file is written to the path specified in -o <filepath>. file type is inferred from extension (.webp, .png, .mp4, etc.). json response still contains url and metadata.

outcome signal

you know melies worked when:

1. images/videos are accessible: the returned url loads in a browser. webp/mp4 files are valid and playable.
2. credits deducted correctly: melies credits shows lower balance after generation. estimate from --dry-run matches actual cost.
3. actor/style applied: generated image/video visibly matches the flags you passed. compare --dry-run prompt against result.
4. file saved locally: if using -o <filepath>, file exists on disk and is not empty. ls -lh <filepath> confirms size.
5. consistency across batch: if you generated 4 images with same actor, all 4 show the same character (within melies' rendering variance).
6. sync completed before timeout: sync command returned json with url, not timeout error. check command output, not just file existence.
7. pipeline two-step flow: pipeline returned both imageUrl and videoUrl. video is an animation of the image, not random.
8. thumbnail is 16:9: if using melies thumbnail, aspect ratio is forced 16:9. measure with imagemagick or check file dimensions.
9. poster preset applied: if using --style noir, poster has dark noir aesthetic. doesn't look like a generic image.
10. no 401 errors: if you see "unauthorized", your token expired. re-run melies login and retry.