Meitu CLI

cli/ is the main Node.js implementation of the meitu CLI. It is the primary command-line runtime for this repository.

It supports:

• local or environment-based credential loading
• auth verify
• generate for low-level image effect calls
• automatic task polling
• result download with --download-dir
• local file upload through the strategy service
• metadata-driven tool commands such as image-cutout, image-generate, and image-to-video

Install

Recommended for external CLI users after the npm package is published:

npm install -g meitu-ai

Then run the CLI directly:

meitu --help
meitu auth verify --json

If you do not want a global install, you can run the published package with npx:

npx -y meitu-ai --help
npx -y meitu-ai auth verify --json

Tool commands work the same way through npx:

npx -y meitu-ai image-cutout --image ./test.png --json

Notes:

• npm install -g meitu-ai installs the package globally and exposes the meitu command on PATH.
• npx -y meitu-ai ... runs the published package without a separate global install.
• Both forms use the same CLI behavior, configuration file, and environment variables.

For local repository usage:

cd cli
npm install
npm link

Then verify:

meitu --help
meitu image-cutout --help

Configure

You can save credentials locally:

meitu config set-ak --value your_access_key
meitu config set-sk --value your_secret_key

Or provide them through environment variables:

export MEITU_OPENAPI_ACCESS_KEY=your_access_key
export MEITU_OPENAPI_SECRET_KEY=your_secret_key

Environment variables take priority over the local credentials file.

The local credentials file is stored at ~/.meitu/credentials.json.

Built-in defaults:

• verify endpoint: /demo/authorization
• image generate endpoint: /api/v1/sdk/push
• task status endpoint: /api/v1/sdk/status

Advanced Overrides

For normal external usage, you usually only need:

• MEITU_OPENAPI_ACCESS_KEY
• MEITU_OPENAPI_SECRET_KEY

The strategy service used for local file upload is built in and does not need to be configured in normal usage.

If you are testing against a private environment or a non-default deployment, the CLI also supports these advanced overrides:

• MEITU_OPENAPI_BASE_URL
• MEITU_OPENAPI_STRATEGY_BASE_URL

The strategy path and strategy type use built-in defaults and normally do not need to be configured:

• strategy path: /ai/token_policy
• strategy type: mtai

Example:

export MEITU_OPENAPI_BASE_URL=https://api.example.com
export MEITU_OPENAPI_STRATEGY_BASE_URL=https://strategy.example.com

Usage

Verify credentials:

meitu auth verify --json

Tool commands:

• video-motion-transfer
• image-edit
• image-generate
• image-upscale
• image-try-on
• image-to-video
• image-face-swap
• image-cutout
• image-beauty-enhance

These commands all use the same fixed internal defaults:

• task mapping is handled internally by the CLI
• task type is handled internally by the CLI
• media inputs are exposed from the MCP tool metadata
• local file paths and remote URLs are both supported for media inputs
• parameter definitions are exposed from MCP metadata and wrapped by the CLI automatically

The CLI loads media input and parameter definitions from the MCP tool metadata endpoint. Use per-tool help to inspect the exact arguments:

meitu image-cutout --help
meitu image-try-on --help

Parameter wrapping rules:

• values from parameter_input_alias are wrapped as {"parameter": {...}}
• values from params_input_alias stay at the top level of params
• when a tool has no extra params, the CLI sends an empty string for params

Run cutout with a local file:

meitu image-cutout \
  --image ./test.jpg \
  --model_type 2 \
  --download-dir ./outputs \
  --json

Run beauty enhancement with the default beauty mode:

meitu image-beauty-enhance \
  --image ./portrait.jpg \
  --json

Run beauty enhancement with stronger beauty mode:

meitu image-beauty-enhance \
  --image ./portrait.jpg \
  --beatify_type 1 \
  --json

Run image generation with a prompt only:

meitu image-generate \
  --prompt "make it cinematic" \
  --json

Run virtual try-on with the required media inputs:

meitu image-try-on \
  --clothes_image_url ./cloth.png \
  --person_image_url ./person.png \
  --replace upper \
  --need_sd 1 \
  --json

Advanced Generate Usage

The low-level generate command is still available when you need to call a custom task directly.

Run intelligent cutout with a local file through the low-level command:

meitu generate \
  --task /v1/photo_scissors/sod \
  --image-file ./test.jpg \
  --params-json '{"parameter":{"nMask":false,"model_type":0}}' \
  --download-dir ./outputs \
  --json

Run a task with an explicit init_images array:

meitu generate \
  --task /v1/photo_scissors/sod \
  --task-type mtlab \
  --init-images-json '[{"media_data":"./test.jpg","resource_type":"file","profile":{"media_profiles":{"media_data_type":"url"},"version":"v1"}}]' \
  --params-json '{"parameter":{"nMask":false,"model_type":0}}' \
  --download-dir ./outputs \
  --json

Run a task with a remote image URL:

meitu generate \
  --task /v1/photo_scissors/sod \
  --image-url https://example.com/test.jpg \
  --params-json '{"parameter":{"nMask":false,"model_type":0}}' \
  --json

Wait for an existing task manually:

meitu task wait t_xxx --download-dir ./outputs --json

Task Behavior

• meitu generate automatically polls /api/v1/sdk/status when the create call returns a task_id
• default polling interval: 1s
• status = 0, 1, or 9 means the task is still running
• status = 10 means the task succeeded
• status = 2 means the task failed
• any other non-success status is treated as a failure state

When --download-dir is used, the CLI downloads every result image URL it receives and returns downloaded_files in JSON output.

Development

cd cli
npm install
npm test

If you want to preview the npm package contents locally:

npm pack --dry-run --cache /tmp/meitu-node-npm-cache

Python Reference

The previous Python implementation is still kept in:

cli-python/