Skill: beautypluscom/beautyplus-ai (version 1.0.4)

--- name: beautyplus-ai description: "AI image editing and beautification suite for portrait retouching, body reshaping (breast/butt), AI hair styling, AI clothes / cosplay change, expression edits, photo restoration & upscaling, and artistic filters." version: 1.1.0 author: BeautyPlus metadata: {"openclaw":{"emoji":"🖼️","requires":{"bins":["python3"],"env":{"BP_AK":{"required":true},"BP_SK":{"required":true}}},"tags":["image-processing","portrait-retouching","body-reshape","virtual-try-on","ai-cosplay","photo-restoration","image-upscaling","makeover"]}} --- # BeautyPlus Skills & API > **`{baseDir}` placeholder.** Every CLI command in this file uses > `{baseDir}/scripts/...`. The host (skill loader) substitutes `{baseDir}` > with this skill's installation directory at load time. If your host does > not expand placeholders, replace `{baseDir}` with the absolute path to > this skill folder, or run from inside the skill folder using `scripts/...`. ## When to Use This Skill Activate whenever the user requests modifications, enhancements, or artistic changes to a **photo / image** (path, URL, or attachment). **Trigger keywords:** "make me look better", "change my clothes", "fix this blurry photo", "make me smile", "enhance my body", "change my hair color / style", "add a filter", "cosplay", "outfit change", "upscale", "virtual try-on". ## Effect KEY catalog (`--task` values) The CLI `--task` value is always one of the **effect KEYs** below. Per-key algorithm params are returned inline by `POST /skill/consume.json` (`invoke_spec`) — never hard-code AIGC paths. If the server returns `Unknown invoke preset`, the key is not in the tenant's invoke map; do not invent params, check config or admin. All KEYs operate on **still images** (`.jpg` / `.jpeg` / `.png` / `.webp`). The current catalog is image-only; the async / video flow is reserved — see [docs/video-reserved.md](docs/video-reserved.md). ### 1. 💪 Body reshape **When:** user explicitly asks to enhance, enlarge, or reshape breast or buttocks. **Tier rule:** append `_strong` / `_medium` / `_weak` to the base KEY. Default tier: `_medium` (e.g. `breast_natural_medium`). | KEY (base) | Description | |-------------------|-------------| | `breast_natural` | Natural fullness; subtle lift. | | `breast_teardrop` | Teardrop contour, fuller lower pole. | | `breast_round` | Rounded, lifted look with upward emphasis. | | `breast_outward` | Editorial spread with outward emphasis. | | `butt_peach` | Lift and side volume for a peach shape. | | `butt_o_shape` | Smooth, continuous curve, even side profile. | ### 2. 💇‍♀️ Hair editing **When:** new hair color or new hairstyle. | KEY | Description | |-------------------------|-------------| | `hair_black` | Deep black shine; natural look. | | `hair_blonde` | Classic golden blonde. | | `hair_brown_highlights` | Brown with highlights for dimension. | | `hair_platinum` | Soft creamy platinum. | | `hair_silver_platinum` | Cool metallic silver; edgy modern look. | | `hair_teddy_brown` | Warm soft brown; youthful vibe. | | `hair_glossy` | Extra shine and sleek fall. | | `hair_high_layer` | Light layers and airy volume. | | `hair_soft_waves` | Romantic large waves. | | `hair_latino_curls` | Tight curls, maximum volume. | ### 3. 👗 Outfit change (AI clothes) **When:** user asks to change clothes, try on different styles, or dress up for a specific occasion / cosplay. **Formal / Evening** | KEY | Description | |-------------------------|-------------| | `dress_yellow_gown` | Vivid yellow silk evening gown. | | `dress_arctic_allure` | Rhinestone mesh gown with galaxy sparkle. | | `dress_ostrich_feather` | Ethereal feather gown. | | `dress_muse_goddess` | Couture-heavy beaded goddess gown. | | `suit_tartan_eve` | Smart, polished British tartan suit. | | `suit_red_carpet` | Classic sharp black suit. | **Vacation / Casual** | KEY | Description | |--------------------------|-------------| | `accessory_bunny_ear` | Playful bunny ear accessory. | | `dress_butter_moonlight` | Pale yellow slip dress; fresh light look. | | `dress_pink_puffy` | Tiered pink puff dress; sweet portrait style. | | `dress_gold_hoodie` | Urban casual hoodie dress. | | `dress_lace_corset` | French-inspired lace corset set. | | `dress_chiffon_cake` | Tiered chiffon maxi; relaxed vacation mood. | | `dress_sheer_bikini` | Bikini under sheer cover; resort look. | **Cosplay / Fantasy** | KEY | Description | |-------------------------|-------------| | `cosplay_carnival` | Carnival samba outfit with feather headpiece. | | `cosplay_bunny_cop` | Navy bunny police uniform. | | `cosplay_fox_boyfriend` | Green fox print shirt; relaxed vibe. | | `cosplay_deer_girl` | Forest fawn-inspired mini skirt. | | `cosplay_grinch` | Green fuzzy Grinch party costume. | | `victoria_angel` | Lingerie set with wings (runway showstopper). | | `dallas_cowboy` | Iconic blue-and-white cheerleader uniform. | **Party / Futuristic** | KEY | Description | |--------------------|-------------| | `floral_camisole` | Botanical floral cami. | | `puff_skirt` | Strapless puff corset dress. | | `one_shoulder_lbd` | One-shoulder little black dress. | | `red_latex` | Bold red latex mini skirt. | | `moonlight_dress` | Full-rhinestone bodycon long gown. | | `y3k_set` | Futuristic metallic Y3K co-ord. | **Sports / Activewear** | KEY | Description | |--------------------|-------------| | `brazilian_bikini` | Brazilian-cut bikini. | | `tennis_set` | Sporty athletic-chic tennis skirt and top. | | `cozy_fit` | Relaxed hoodie and jogger; urban athleisure. | | `racing_suit` | Bold motorsport racing driver suit. | | `white_yoga` | Minimal white yoga set. | ### 4. 🎭 Facial retouch & expression **When:** retouch / apply a makeup style, or change the subject's expression. | KEY | Description | |-------------------|-------------| | `natural_beauty` | Soft natural enhancement; clear skin. | | `glamour_beauty` | Polished, charismatic look with full makeup. | | `sweet_beauty` | Youthful sweet-girl vibe. | | `luminous_beauty` | Radiant glow; bright complexion. | | `youthful_beauty` | Fresh, energetic style. | | `closed_smile` | Gentle closed-lip smile. | | `open_smile` | Wide toothy grin. | | `cool_expression` | Serious, composed, edgy. | | `wink` | Single-eye wink. | ### 5. 🖼️ Photo quality & art filters **When:** image is blurry / noisy / old / low-resolution, or the user wants a camera vibe / lighting filter. | KEY | Description | |------------------------|-------------| | `photo_restoration_v3` | Denoise, deblur, reduce artifacts; keeps a natural look. | | `ai_ultra_hd_v3` | Deep-learning upscale + detail recovery for old / small photos. | | `tanning_filter` | Warm bronzed tan skin filter. | | `ccd_flash` | Vintage CCD-camera flash effect. | | `film_flash` | Film grain with flash overlay. | | `fuji_flash` | Fujifilm-style flash; soft grain, warm tones. | ## Defaults & disambiguation (MANDATORY) Use this table when the user's intent is broad or under-specified. Do **not** guess a wrong KEY. | Situation | Action | |-----------|--------| | Vague intent ("make this photo look better") | Default to `natural_beauty` if a face is present, else `photo_restoration_v3`. | | User asks for retouch / makeup but did not pick a style | Offer 2–3 KEYs from §4 (e.g. `natural_beauty`, `glamour_beauty`, `sweet_beauty`). | | User says "change my hair / outfit / cosplay" without a style | Ask one question, or offer 2–3 KEYs from §2 / §3. | | Body reshape, no tier given | Default to `_medium`, or briefly confirm before submit. | | User mentions video / motion / "make a video" | No video keys exist today — see [docs/video-reserved.md](docs/video-reserved.md). Stay on still images. | | Ambiguous or missing attachment | Ask one clarifying question, or pull media from IM per [docs/im-attachments.md](docs/im-attachments.md). | ## API submission path (MANDATORY) - **New jobs** must go through **`python3 {baseDir}/scripts/beautyplus_ai.py run-task …`** (or the same `run-task` embedded inside `spawn-run-task` → `sessions_spawn` for the reserved video flow). - **Do not** hand-craft HTTP to the skill's `wapi` gateway or to AIGC / invoke endpoints — that skips `POST /skill/consume.json` (quota and permission) and breaks the supported pipeline. This skill does not emit debug curl for API calls. - **`query-task --task-id`** is for **resuming polling** on an existing full `task_id` only; it does **not** replace `run-task` for a new submission. ## Billing and user-facing claims (MANDATORY) - Each successful `run-task` (including inside a `sessions_spawn` worker) triggers server-side **quota / credit consumption** for the `BP_AK` tenant. This is a paid, metered commercial API. - **Do not** state or imply that the service is free, costs nothing, has an unlimited trial, or invent prices, plan names, promotions, or trial rules. - **Allowed wording:** processing uses the BeautyPlus account quota tied to the configured keys; billing and plans are per the user's console or administrator. - On quota / membership errors, surface the server `detail` and `pricing_url` (see Step 3 error table). Never add "free" or zero-cost wording, even on success. --- ## Step 0 — Pre-flight check (MANDATORY) Verify AK / SK are configured. **Only run this command** at this stage; do not read other Python sources first. ```bash python3 {baseDir}/scripts/beautyplus_ai.py preflight ``` - Output `ok` → continue to Step 1. - Output `missing` → **stop** and prompt the user. Use the channel-appropriate template in [docs/credentials-prompt.md](docs/credentials-prompt.md) (plain text by default; Feishu interactive card when the host exposes a Feishu account). ## Step 1 — Pick effect KEY and input 1. Map the user's intent to one **effect KEY** from the catalog above. Apply the **Defaults & disambiguation** table when the request is broad. 2. Confirm the input file location. If the user already gave a path or URL, continue to Step 2 without asking again. 3. **Reply immediately** to acknowledge, e.g. *"🖼️ Processing — please wait a moment…"* ### Getting media from IM messages Full detail: [docs/im-attachments.md](docs/im-attachments.md). | Platform | How to obtain | |----------|---------------| | Feishu | Message resource URL / `image_key` + `message_id` → optional `resolve-input` | | Telegram | `file_id` → `resolve-input --telegram-file-id` (needs `TELEGRAM_BOT_TOKEN`) | | Discord | `attachments[0].url` — often usable directly as `--input` | | Generic | URL or path | ```bash python3 {baseDir}/scripts/beautyplus_ai.py resolve-input --file /tmp/saved.jpg --output-dir /tmp # or: --url, --telegram-file-id, --feishu-image-key + --feishu-message-id ``` Use the JSON `path` field as `--input`. **`--input` as a URL:** quote the full URL in the shell to avoid `&` splitting. Defaults: 120 s read timeout, 100 MB max — override with `MT_AI_URL_READ_TIMEOUT`, `MT_AI_URL_CONNECT_TIMEOUT`, `MT_AI_URL_MAX_BYTES`. For flaky or large links, use `resolve-input --url` first and pass the local `path`. ## Step 2 — Install dependencies ```bash python3 {baseDir}/scripts/beautyplus_ai.py install-deps ``` If dependencies are already installed this step is quick; then continue to Step 3. ## Step 3 — Run the task All listed effect KEYs are image jobs — use the inline `run-task` flow (§3a). Video keys are reserved; see [docs/video-reserved.md](docs/video-reserved.md). ### 3a — Inline `run-task` (blocking, default) ```bash python3 {baseDir}/scripts/beautyplus_ai.py run-task \ --task "<effect_key>" \ --input "<image_url_or_path>" ``` Replace `<effect_key>` (e.g. `hair_soft_waves`) and `<image_url_or_path>` with real values. Default params include `rsp_media_type: url`. For custom JSON params: ```bash python3 {baseDir}/scripts/beautyplus_ai.py run-task \ --task "<effect_key>" \ --input "<url_or_path>" \ --params '{"parameter":{"rsp_media_type":"url"}}' ``` #### When `run-task` exits 0 Stdout is JSON containing: - `skill_status: "completed"` — job done. - `output_urls` — ordered `http(s)` links (extracted from `data.result.urls`, `images`, `media_info_list`, etc.). - `primary_result_url` — same as `output_urls[0]`; convenient for delivery. - `task_id` — full task id when the API returns one. Keep it for support / recovery; do not truncate. Some sync completions may omit it. - `agent_instruction` — short reminder for the model. - `meta` / `data` — full API payload for debugging. **You must:** 1. Send the user a short natural-language summary of what was done. 2. Complete Step 4 delivery using `primary_result_url` or `output_urls[0]`, unless the user explicitly asked for the URL only. Never end the turn with raw JSON alone. Never resubmit `run-task` for the same `task_id` — use `query-task` to resume polling. #### When `run-task` exits non-zero Stdout has `skill_status: "failed"` with an `error` field. Map it as: | `error` | `api_code` | Action | |-----------------------|------------|--------| | `credit_required` | 60002 | Show server `detail` to the user; include `pricing_url` as a link if present. Do **not** retry by tweaking params. | | `membership_required` | 60001 | Same — show `detail` / `pricing_url`. | | `consume_param_error` | — | Fix `--task` / `--input` / `--params`; do **not** tell the user to recharge. | | Other (`task_failed`, `poll_timeout`, `poll_aborted`, …) | — | See [docs/errors-and-polling.md](docs/errors-and-polling.md). | Never dump raw JSON to the user. Never retry `run-task` for credit / membership errors. ### 3b — Resume polling (`query-task`) When you already have a full `task_id` (from previous stdout JSON, polling checkpoint, or `task_id=...` lines in stderr) and the job may still be running, **do not run `run-task` again** — resume polling only: ```bash python3 {baseDir}/scripts/beautyplus_ai.py query-task \ --task-id "<full_task_id>" ``` Optional `--task` sets the `task_name` field in the success JSON for your logs (default labels as `query_task`). Uses the same `BP_AK` / `BP_SK` and remote config as the original submit. Stdout JSON and exit codes match `run-task`. ### 3c — Last task and history Local state lives under `~/.openclaw/workspace/beautyplus-ai/` (`last_task.json`, `history/task_*.json`, last 50 records). For async jobs, `last_task.json` may briefly show `skill_status: "polling"` with a `task_id` while the client is still polling — a checkpoint that lets `query-task` resume if the process is killed mid-poll. ```bash python3 {baseDir}/scripts/beautyplus_ai.py last-task python3 {baseDir}/scripts/beautyplus_ai.py history ``` Use when the user asks whether a recent job finished, or wants a short history summary. Do not expose raw secrets. ## Step 4 — Deliver result to the channel Required after `skill_status: "completed"`. The CLI does not post to IM by itself — send the processed image back on the user's platform, in the same turn as the success summary. ### Resolve `deliver-to` | Platform | Source | Format | |--------------|----------------------------------------------------------|--------| | Feishu group | `conversation_label` or `chat_id` without `chat:` prefix | `oc_xxx` | | Feishu DM | `sender_id` without `user:` prefix | `ou_xxx` | | Telegram | inbound message `chat_id` | e.g. `-1001234567890` | | Discord | `channel_id` | e.g. `123456789` | ### Feishu ```bash python3 {baseDir}/scripts/feishu_send_image.py \ --image "<result_url>" \ --to "<oc_xxx or ou_xxx>" ``` ### Telegram ```bash TELEGRAM_BOT_TOKEN="$TELEGRAM_BOT_TOKEN" python3 {baseDir}/scripts/telegram_send_image.py \ --image "<result_url>" \ --to "<chat_id>" \ --caption "✅ Done" ``` ### Discord Download the result, then send with the `message` tool: ```bash curl -L "<result_url>" -o /tmp/result_image.jpg ``` ``` message(action="send", channel="discord", target="<channel_id>", filePath="/tmp/result_image.jpg") ``` For files over ~25 MB, send the result URL as a link instead. ### WhatsApp / Signal / others Use the `message` tool with `media`, or send the result URL directly. **Video delivery (reserved):** see [docs/video-reserved.md](docs/video-reserved.md). ## Multi-stage pipelines (chaining tasks) When the user asks for more than one BeautyPlus step on the same media (e.g. `photo_restoration_v3` → `dress_yellow_gown`), treat each step as a **separate job** with its own `--task`: 1. After stage A completes, pass `primary_result_url` (or `output_urls[0]`) as `--input` for the next stage. That is a new job, not a retry. 2. *"Do not re-run `run-task`"* means: do not resubmit the **same** `task_id`. It does not forbid the next stage with a different effect KEY. 3. Deliver only after the **final** stage completes. Video chains are reserved — see [docs/video-reserved.md](docs/video-reserved.md). ## Notes - **Single business entrypoint:** all algorithm runs and config fetches go through `beautyplus_ai.py`; agents do not need to open `client.py` or `ai/api.py`. See **API submission path** above for the no-direct-HTTP rule. - **AK / SK loading:** environment variables `BP_AK` / `BP_SK` first; if unset, `scripts/.env` is read automatically. - **Client init** pulls the latest algorithm config from the server; no manual `INVOKE` setup is required. - **Bot token safety:** pass `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, etc. only via environment variables — never as CLI arguments. - **URL input errors** may report HTTP 403 (expired signed URL) or timeout — see `MT_AI_URL_*` env vars in Step 1. ## Further reading - [BeautyPlus Developers](https://www.beautyplus.com/developers/console) — API and skill key integration, use cases. - [BeautyPlus](https://www.beautyplus.com) — product overview. - [README.md](README.md) - [docs/video-reserved.md](docs/video-reserved.md) — async / video flow (reserved). - [docs/credentials-prompt.md](docs/credentials-prompt.md) — `preflight: missing` user prompt templates. - [docs/multi-platform.md](docs/multi-platform.md) — delivery details (Feishu, Telegram, Discord, …). - [docs/im-attachments.md](docs/im-attachments.md) — IM attachments and `resolve-input`. - [docs/errors-and-polling.md](docs/errors-and-polling.md) — polling, timeouts, failure codes.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)