Meitu CLI

Meitu CLI is a command-line interface to Meitu's AI image and video capabilities. Everything accessible through the Meitu AI Open Platform — cutout, beauty enhancement, image generation, virtual try-on, image-to-video, and more — is available directly from the terminal with the same models, parameters, and quality.

It is designed for:

• AI agents — structured JSON output (--json), deterministic exit codes, and automatic task polling make it a natural fit for agentic workflows that need to call Meitu's image and video AI as a tool step (e.g. Claude Code, Cursor, or custom LLM agents).
• E-commerce & content teams — batch-process product images at scale: cutout backgrounds, virtual try-on for fashion listings, beauty enhancement for portrait shots, or generate marketing visuals without a GUI.
• Developers building on Meitu OpenAPI — prototype and debug API calls interactively from the terminal before integrating them into an application.

Docs

• CLI auth + Maat docs — design, API appendix, backend handoff, and review summary for the account-service-to-Maat authentication flow.
• Skills package docs — skills package registry contract and install/update backend handoff.
• Guides — internal setup, env overrides, passthrough usage, and local split-AK/SK workflows.
• Release docs — publish flow, privacy checks, and dual-registry release notes.
• Reports — command-mode and historical effect-id validation records.
• MCP passthrough spec — detailed MCP-style passthrough behavior and implementation notes.

Install

Recommended for most users (npm package):

npm install -g meitu-cli

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-cli --help
npx -y meitu-cli auth verify --json

Tool commands work the same way through npx:

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

Notes:

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

Install meitu-skills (optional, for agent workflows)

Recommended one-stop bootstrap (uses the bundled skills package installer):

npm install -g meitu-cli
meitu skills install meituhub-skills
meitu skills doctor

This downloads the official meituhub-skills runtime package from the Meitu package registry, verifies its checksum, validates PACKAGE_MANIFEST.json, and atomically installs the package into $MEITU_SKILLS_HOME/skills/meituhub-skills (default: ~/.meitu/skills/meituhub-skills). No remote scripts are executed; install is always an explicit, user-triggered action.

You can also install from a local archive (useful for offline / preview / internal builds):

meitu skills install meituhub-skills \
  --archive ./meituhub-skills-2.0.6.tar.gz \
  --json

Other useful subcommands:

meitu skills update meituhub-skills  # update the installed skills package
meitu skills version                 # show installed skills + CLI version
meitu skills doctor --json           # diagnose CLI / credentials / registry / skills

Common flags for install and update:

• positional <packageName> — registry package name, for example meituhub-skills
• --target <dir> — override skills root (default: $MEITU_SKILLS_HOME/skills or ~/.meitu/skills)
• --version <ver> — pin a specific package version (default: registry latest)
• --registry <url> — override the package registry URL
• --archive <path> — install from a local .tar.gz instead of the registry
• --force — drop the auto-generated backup of any prior install
• --json — emit structured JSON output for agents

Environment variable overrides (optional):

• MEITU_SKILLS_HOME — base directory for local skills files, default ~/.meitu
• MEITU_SKILLS_PACKAGE_REGISTRY_URL — package registry URL override
• MEITU_OPENAPI_BASE_URL / MEITU_OPENAPI_IMAGE_BASE_URL — derive registry host

Legacy alternatives (still supported):

# ClawHub
npm install -g clawhub
clawhub install meitu-skills

# Generic skills installer via GitHub URL
npx -y skills add https://github.com/meitu/meitu-skills --yes

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 (unless overridden by environment variables below):

• OpenAPI gateway host and strategy (file-upload token) host are set inside the CLI; override them only if your documentation or environment requires a different host (see Advanced Overrides).
• verify path: /demo/authorization
• image generate path: /api/v1/sdk/push
• task status path: /api/v1/sdk/status
• tool registry URL: follows the execution gateway domain by default, e.g. https://openapi-global.meitu.com/api/v1/skills/tool_registry.json?consumer=meituhub

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:

• MEITU_OPENAPI_BASE_URL — overrides the built-in OpenAPI gateway host
• MEITU_OPENAPI_IMAGE_BASE_URL — optional; image/task calls use this if set, otherwise MEITU_OPENAPI_BASE_URL (or the built-in default when that is unset)
• MEITU_OPENAPI_STRATEGY_BASE_URL — overrides the built-in strategy host
• MEITU_OPENAPI_IMAGE_GENERATE_PATH — overrides the push endpoint path used for tool and low-level generate calls
• MEITU_OPENAPI_TASK_STATUS_PATH — overrides the task status endpoint path
• MEITU_OPENAPI_TASK_TIMEOUT_MS — maximum task polling wait time in milliseconds for tool commands, generate, and batch (default: 300000, i.e. 5 minutes); also used as the default for meitu task wait when --timeout-ms is omitted
• MEITU_SKILLS_REGISTRY_URL — overrides the default tool registry URL; when unset, the registry uses the same domain source as command execution (MEITU_OPENAPI_IMAGE_BASE_URL -> MEITU_OPENAPI_BASE_URL -> built-in default)
• MEITU_IAM_REFRESH_AHEAD_MS — when using IAM token auth, refresh the session proactively this many milliseconds before access-token expiry; defaults to 300000 (5 minutes), set to 0 to only refresh after expiry
• MEITU_OPENAPI_TOOL_TASK_MODE — optional compatibility guard; when set, it must stay command because tool commands now always send the CLI command name directly
• MEITU_CLI_OUTPUT_FORMAT — controls --json output shape; concise (default) uses the historical wrapped CLI payloads, full keeps the full backend-response passthrough format
• MEITU_RECHARGE_URL — overrides the recharge page returned in insufficient-balance / order-limit responses; defaults to https://meituhub.cn/zh-cn/pricing
• MEITU_CONSOLE_URL / OPENAPI_CONSOLE_URL — overrides the console/configuration page returned for authorization or configuration errors; defaults to MEITU_RECHARGE_URL when unset

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

• strategy path: /ai/token_policy (override: MEITU_OPENAPI_STRATEGY_PATH)
• strategy type: mtai (override: MEITU_OPENAPI_STRATEGY_TYPE)

Example:

export MEITU_OPENAPI_BASE_URL=https://api.example.com
export MEITU_OPENAPI_IMAGE_GENERATE_PATH=/api/v2/sdk/push
export MEITU_OPENAPI_STRATEGY_BASE_URL=https://strategy.example.com
export MEITU_OPENAPI_TOOL_TASK_MODE=command
export MEITU_CLI_OUTPUT_FORMAT="concise"

MCP-style passthrough

When you need meitu-cli to behave more like an MCP proxy calling AIGCP, the CLI can augment push requests with MCP-style passthrough headers and payload fields.

Supported push payload additions:

• request_id
• trace_id
• context

Supported passthrough request headers:

• x-mtcc-client
• isStressTest
• Authorization (note: the standard Authorization header is still replaced by the CLI's SDK signature)

Recommended environment variables:

• MEITU_OPENAPI_HEADER_X_MTCC_CLIENT
• MEITU_OPENAPI_HEADER_ISSTRESSTEST
• MEITU_OPENAPI_HEADER_MT_MCP_CONTEXT
• MEITU_OPENAPI_HEADER_MT_MCP_UID
• MEITU_OPENAPI_HEADER_MT_MCP_GID
• MEITU_OPENAPI_HEADER_MT_MCP_TASK_ID
• MEITU_OPENAPI_HEADER_X_REQUEST_ID
• MEITU_OPENAPI_MCP_FROM
• MEITU_OPENAPI_MCP_BIZ_LINE

meitu-cli will also auto-populate x-mtcc-client.gnum when it is not explicitly provided. The value is persisted under ~/.meitu/device.json and generated once with crypto.randomUUID(), so the same CLI environment reuses a stable device-level gnum across AK/SK and IAM login flows.

Optional advanced passthrough variables:

• MEITU_OPENAPI_PASSTHROUGH_HEADERS — override passthrough header allowlist
• MEITU_OPENAPI_CONTEXT_EXTRA_JSON — merge custom JSON fields into context
• MEITU_OPENAPI_MCP_SERVER_PROJECT — override context.mcp_server_project
• MEITU_OPENAPI_MCP_SERVER_ADDR — override context.mcp_server_addr
• MEITU_OPENAPI_AUTO_GENERATE_IDS — auto-generate request_id / trace_id when missing
• MEITU_OPENAPI_FORWARD_ORIGINAL_AUTH_AS — preserve the upstream auth value in a secondary header such as X-Original-Authorization

Example:

export MEITU_OPENAPI_HEADER_X_MTCC_CLIENT='eyJhcHBfaWQiOiIxMjMiLCJiaXpfaWQiOiI0NTYiLCJ1aWQiOiJ1c2VyLTEiLCJnbnVtIjoiZGV2aWNlLWdudW0tMDAxIn0='
export MEITU_OPENAPI_HEADER_ISSTRESSTEST=true
export MEITU_OPENAPI_HEADER_X_REQUEST_ID=req-demo-001
export MEITU_OPENAPI_HEADER_MT_MCP_TASK_ID=trace-demo-001
export MEITU_OPENAPI_MCP_FROM=app
export MEITU_OPENAPI_MCP_BIZ_LINE=default

For the detailed implementation spec used by this repository, see docs/mcp/cli-mcp-passthrough-spec.md.

Usage

Verify credentials:

meitu auth verify --json

Manage IAM session explicitly:

meitu auth login --json
meitu auth refresh --json
meitu auth status --json

Tool commands:

• video-motion-transfer
• image-to-video
• text-to-video
• video-to-gif
• image-generate
• image-poster-generate
• image-edit
• image-upscale
• image-beauty-enhance
• image-face-swap
• image-try-on
• image-cutout
• image-grid-split

Behavior in short:

• task routing and task types are handled inside the CLI
• local file paths and remote URLs are supported for media inputs
• each subcommand exposes flags derived from the same tool metadata the CLI ships with; run meitu <command> --help for the exact options

Parameter wrapping rules (for JSON payloads sent to the API):

• 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 \
  --output ./outputs/cutout.png \
  --json

Run beauty enhancement with the default beauty mode:

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

Run beauty enhancement with stronger beauty mode (flag name matches the OpenAPI field spelling):

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 --output ./outputs/result.png --json

Download behavior:

• --output <paths...> saves files to the exact paths you provide
• --download-dir <dir> saves files into a directory and lets the CLI generate filenames
• if neither option is provided, the CLI only returns the backend response and does not download files
• --output maps files by the order of data.result.urls
• --output and --download-dir cannot be used together

Examples:

meitu image-face-swap \
  --head_image_url https://example.com/head.png \
  --sence_image_url https://example.com/scene.jpg \
  --prompt "swap face" \
  --output /tmp/face-swap.png \
  --json

meitu some-command \
  ...other args... \
  --output /tmp/result-1.png /tmp/result-2.png /tmp/result-3.png \
  --json

When downloads happen, JSON output includes:

{
  "code": 0,
  "message": "success",
  "data": {
    "result": {
      "urls": [
        "https://example.com/result.png"
      ]
    }
  },
  "downloaded_files": [
    {
      "url": "https://example.com/result.png",
      "saved_path": "/tmp/result.png"
    }
  ]
}

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 --output or --download-dir is used, the CLI downloads result URLs locally and returns downloaded_files in JSON output.

Skills Package Installer

meitu skills install meituhub-skills is a bootstrapper for the official meituhub-skills package. It is intentionally conservative:

• Explicit only — install/update only run when invoked by the user. Tool commands such as meitu image-edit never auto-install or auto-upgrade skills.
• No remote script execution — the CLI never executes scripts shipped inside the package. It only writes files into the local skills directory.
• Path-traversal protection — the bundled tar.gz extractor rejects absolute paths, parent traversal (..), Windows-rooted paths, NUL bytes, symlinks, hardlinks, and device entries. Only regular files and directories are extracted.
• Checksum verification — when the registry entry includes sha256, the download is verified before extraction. Local archives report the computed digest in their result payload for auditing.
• Manifest validation — the package must contain SKILL.md and a parseable PACKAGE_MANIFEST.json after extraction; otherwise the install is aborted.
• Compatibility check — when the manifest declares compatibility.meitu_cli, the CLI rejects installs that don't satisfy the version range.
• Atomic replace with backup — existing installs are renamed to <install-dir>.bak.<timestamp> before the new directory is moved into place. Use --force to drop the backup.
• Bounded download size — packages over 256 MB are rejected.

The corresponding diagnostics command, meitu skills doctor, validates:

• meitu-cli version
• presence of credentials (env or ~/.meitu/credentials.json)
• live meitu auth verify round-trip against the configured OpenAPI host
• presence and freshness of the local tool registry cache (~/.meitu/tool-registry.json)
• presence and structure of ~/.meitu/skills/meituhub-skills
• compatibility of the installed skill pack with the current meitu-cli

Related design documents (in this repository):

• docs/api/skills-package-registry-api-handoff.md — server-side API spec for the Skills Package Registry endpoint that meitu skills install/update consumes. Hand this to backend engineers for registry-side implementation.

Development

From the repository root:

npm install
npm test

If you want to preview the npm package contents locally:

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