Metadata-Version: 2.1
Name: meitu-ai
Version: 0.1.2
Summary: Meitu OpenAPI command-line tool.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: boto3<2,>=1.35

# Meitu CLI

`meitu` is now a Python CLI for Meitu OpenAPI image tasks. It is the main runtime used by the skills in this repository.

It supports:

- local or environment-based credential loading
- `auth verify`
- `generate` for image effect calls
- automatic task polling
- result download with `--download-dir`
- local file upload through the strategy service

## Install

Recommended for external CLI users:

```bash
pipx install meitu-ai
```

For local repository usage before the package is published:

```bash
cd /Users/lichao/openapi-cli/cli
pipx install .
```

Alternative for virtual environments or advanced users:

```bash
cd /Users/lichao/openapi-cli/cli
pip install .
```

For local development:

```bash
cd /Users/lichao/openapi-cli/cli
make develop
```

That installs the package in editable mode and makes the `meitu` command available in the current Python environment.

## Configure

You can save credentials locally:

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

Or provide them through environment variables:

```bash
export OPENAPI_ACCESS_KEY=your_access_key
export OPENAPI_SECRET_KEY=your_secret_key
export OPENAPI_BASE_URL=openapi.meitu.com
```

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`

`OPENAPI_BASE_URL` can be written as `openapi.meitu.com`; the CLI normalizes it to `https://openapi.meitu.com`.

## Advanced Overrides

For normal external usage, you usually only need:

- `OPENAPI_ACCESS_KEY`
- `OPENAPI_SECRET_KEY`
- `OPENAPI_BASE_URL` if you want to override the default API domain

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:

- `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:

```bash
export OPENAPI_STRATEGY_BASE_URL=https://strategy.example.com
```

## Usage

Verify credentials:

```bash
OPENAPI_BASE_URL=openapi.meitu.com meitu auth verify --json
```

Tool commands:

- `video-motion-transfer` -> task `/v1/openclaw/default/488175`
- `image-edit` -> task `/v1/openclaw/default/488176`
- `image-generate` -> task `/v1/openclaw/default/488177`
- `image-upscale` -> task `/v1/openclaw/default/488178`
- `image-virtual-tryon` -> task `/v1/openclaw/default/488184`
- `image-to-video` -> task `/v1/openclaw/default/488185`
- `image-face-swap` -> task `/v1/openclaw/default/488186`
- `image-cutout` -> task `/v1/openclaw/default/488187`

These commands all use the same fixed internal defaults:

- `task_type = formula`
- task mapping 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:

```bash
meitu image-cutout --help
meitu image-virtual-tryon --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:

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

Run image generation with a remote image URL:

```bash
meitu image-generate \
  --image https://example.com/test.jpg \
  --prompt "make it cinematic" \
  --json
```

Run virtual try-on with the required media inputs:

```bash
meitu image-virtual-tryon \
  --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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
cd /Users/lichao/openapi-cli/cli
make test
make package
```

`make test` runs a syntax smoke test and a basic CLI help check.

`make package` builds a Python source distribution and wheel. If `python -m build` is not installed yet, install it first with `python3 -m pip install build`.
