musa

CLI tool for generating, editing, and restoring images via OpenRouter API.

Install

npm install -g @dengxifeng/musa

Setup

Set your OpenRouter API key:

export OPENROUTER_API_KEY="your-key-here"

Get a key at https://openrouter.ai/keys.

Usage

Generate an image

musa generate "a watercolor painting of a fox in a snowy forest"

Options:

-m, --model <model>        Model name (default: google/gemini-2.5-flash-image)
-n, --count <n>            Number of images to generate (default: 1)
    --aspect-ratio <ratio>  Aspect ratio (e.g. 16:9, 1:1, 9:16)
    --size <size>           Image size (e.g. 1024x1024)
-o, --output <dir>         Output directory (default: ~/.musa/cache)
-f, --format <fmt>         Output format: png or jpeg (default: png)

Edit an image

musa edit photo.jpg "add sunglasses to the person"

The output image automatically preserves the aspect ratio of the input.

Options:

-m, --model <model>   Model name (default: google/gemini-2.5-flash-image)
-o, --output <dir>    Output directory (default: ~/.musa/cache)
-f, --format <fmt>    Output format: png or jpeg (default: png)

Restore / enhance an image

musa restore old-photo.jpg
musa restore old-photo.jpg "remove scratches and enhance colors"

Options:

-m, --model <model>   Model name (default: google/gemini-2.5-flash-image)
-o, --output <dir>    Output directory (default: ~/.musa/cache)
-f, --format <fmt>    Output format: png or jpeg (default: png)

Supported models

The model is auto-validated against OpenRouter's image generation models. Some examples:

| Model | Output | |-------|--------| | black-forest-labs/flux.2-flex | image | | black-forest-labs/flux.2-pro | image | | bytedance-seed/seedream-4.5 | image | | google/gemini-2.5-flash-image | text + image | | google/gemini-3-pro-image-preview | text + image | | openai/gpt-5-image | text + image |

Override the default model per-request or globally:

# Per-request
musa generate "a cat" -m google/gemini-2.5-flash-image

# Global default via environment variable
export MUSA_MODEL="google/gemini-2.5-flash-image"

Supported aspect ratios

1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

Extended (gemini-3.1-flash-image-preview only): 1:4, 4:1, 1:8, 8:1

License

Apache-2.0