meitu-image-adapt

Overview

Intelligently adapt the user-provided image to the target width and height (in pixels), keeping the subject undistorted and the background naturally extended without seams. The core tool is meitu image-transform 's canvas expansion capability.

Dependencies

meitu-cli (>=2.0.6): npm install -g meitu-cli@latest
- Preferred environment variables:MEITU_OPENAPI_ACCESS_KEY / MEITU_OPENAPI_SECRET_KEY
- Or preset credential file:~/.meitu/credentials.json
- If manual initialization of local credentials is needed, you can explicitly run meitu config set-ak --value "..." + meitu config set-sk --value "..."(will write to a local file)
- Verify: meitu auth verify --json

Path alias: $VISUAL = {OPENCLAW_HOME}/workspace/visual/

Core Workflow

Preflight → Execute → Deliver

Preflight

meitu --version → if not installed, prompt npm install -g meitu-cli@latest
meitu auth verify --json → if credentials are invalid, prompt to configure AK/SK
Detect mode: cwd has openclaw.yaml → project mode; else → one-off
Resolve output_dir: openclaw.yaml → ./output/ | else → $VISUAL/output/meitu-image-adapt/ mkdir -p {output_dir}

Execute

1. Collect input

Input	Description	Required	Default value
image	The original image to be adapted	Yes	—
width	Target width (pixels)	Yes	1080
height	Target height (pixels)	Yes	1920

image accepts formats: URL or local path (.jpg/.jpeg/.png/.webp)

2. Target size resolution

The user may directly provide pixel values, or may mention a platform name or ratio. Resolve in the following priority order:

A. User provided explicit pixels → use directly.

B. User provided a platform name → check references/platform-presets.md for recommended sizes.

Common quick reference (full table in references):

Platform	Scenario	width × height
Xiaohongshu	Vertical note cover	1080 × 1440
Douyin	Vertical video cover	1080 × 1920
WeChat Official Account	Article header image	900 × 383
WeChat Moments	Square	1080 × 1080
Bilibili	Video cover	1920 × 1080
Taobao	Product main image	800 × 800

If the platform has multiple scenarios, list the options for the user to choose.

C. User provided a ratio (e.g., 16:9) → ensure the output covers all pixels of the original image (no cropping), and take the smallest target size that can contain the original image:

For the target ratio W:H, calculate two schemes respectively: ① calculate the height based on the original image width; ② calculate the width based on the original image height. Take the scheme with the larger output area of the two (that is, ensure both sides are ≥ the original image).
Example: original image 1080×1440, target 16:9 → Scheme ① width=1080, height=608 (height reduced, content lost); Scheme ② width=2560, height=1440 (width extended, content preserved) → take Scheme ② = 2560×1440
Example: original image 1080×1440, target 1:1 → width=1440, height=1440 (based on the long side, short side extended)

D. User did not specify → default 1080×1920 (vertical full screen), and inform the user that it can be adjusted.

3. Input pre-check

Check before calling to avoid wasting quota:

Original image accessible — URL can be opened / local path exists
Target size reasonable — both width and height are within the range 100-8192
Not a meaningless operation — The target size differs from the original image size by ≥5% (if nearly identical, remind the user to confirm)
Reasonable extension ratio — A single-direction extension must not exceed 4 times the original image (e.g., extending 500px to over 2000px); if exceeded, warn that quality may degrade

4. Call meitu-cli

meitu image-transform \
  --skill_name skill_meitu-image-adapt \
  --image_url "{image}" \
  --target_width {width} \
  --target_height {height} \
  [--prompt "{extend_prompt}"] \
  --json \
  --download-dir "{output_dir}"

Return handling:

ok: true → downloaded_files[0].saved_path Get the local path
ok: false → First check the CLI raw field code、hint、error_name、action_url, then classify according to the meitu-tools rules as error_type / user_hint / next_action

extend_prompt Provide only when the user explicitly describes the content of the extension area, for example:

"extend seaside sky and sand naturally"
"extend studio background with clean white walls"
"extend city street scene consistently"

If not provided, it can be omitted, and the default outpainting path will complete the natural extension.

5. Error degradation strategy

Level	Action	Description
L1	Adjust the target size to the nearest standard ratio	Non-standard sizes may cause exceptions; try the closest standard ratio (16:9, 9:16, 4:3, 3:4, 1:1)
L2	Reduce the target size	Keep the ratio unchanged, reduce the long side to within 2048px and retry
L3	Step-by-step adaptation	If a single extension is too large, split it into two steps: first adapt to an intermediate size, then adapt from the intermediate size to the target
L4	Stop and report an error	2 consecutive failures → report the error code and hint, and do not retry

Common error codes:

ORDER_REQUIRED → Insufficient balance; inform the user to top up and provide the action_url
CREDENTIALS_MISSING → AK/SK not configured; first suggest using environment variables or the preset ~/.meitu/credentials.json; only when the user explicitly requests writing local credentials, then suggest meitu config set-ak/set-sk
INVALID_IMAGE → The image cannot be read; check URL accessibility or file format

Deliver

mv {file} {output_dir}/{date}_{name}.{ext}

Naming convention: {date}_{描述性名称}.{ext}

{date} = YYYY-MM-DD(e.g., 2026-03-23）
{name} = a concise description of the adaptation operation (e.g., adapt-1080x1920、adapt-xiaohongshu）
{ext} taken from the actual extension of the downloaded file, not hardcoded

For path display, use the ~/ format.

Example: ~/…/output/meitu-image-adapt/2026-03-23_adapt-xiaohongshu-cover.png

Output

Attribute	Value
Format	Same as the original image (PNG/JPEG/WEBP)
Naming	`{date}_{effect-name}.{ext}`
Size	User-specified width × height
Path	Determined by the Deliver step
Features	The subject proportions are not distorted, the content is complete without loss, and the background extends naturally without seams