Kaipai

Video file → videoscreenclear or hdvideoallinone + spawn-run-task and sessions_spawn (main session). Image → eraser_watermark or image_restoration + blocking run-task only (never spawn-run-task for image tasks). Process images or video with Kaipai AI — four tasks — image watermark removal (eraser_watermark), video watermark removal (videoscreenclear), image quality restoration (image_restoration), video quality restoration (hdvideoallinone). Use when the user asks for watermark removal or quality restoration on images or video. Paid API (consumes tenant quota); never claim the service is free or invent pricing. For videoscreenclear and hdvideoallinone, always use spawn-run-task plus OpenClaw sessions_spawn in the main session (never blocking run-task there); only bypass spawn if the host explicitly forbids sessions_spawn.

# Kaipai Skill

## When to Use This Skill

Activate when the user wants any of the following:

- **Watermark removal** on images or video (remove watermark, eraser watermark, etc.)
- **Image quality restoration** (restore, upscale, enhance, super-resolution)
- **Video quality restoration** (video restore, upscale, hdvideo-style enhancement)

## Billing and user-facing claims (MANDATORY)

- **Fact:** Each successful **`run-task`** (including inside a **`sessions_spawn`** worker) goes through server-side **quota / credit consumption** for the **MT_AK** tenant. This is a **paid, metered commercial API**, not free compute bundled with the skill or the host.
- **Forbidden:** Do **not** state or imply that the service is **free**, costs nothing, uses **no quota**, has **unlimited trial**, or similar. Do **not** invent **prices**, **plan names**, **promotions**, or **trial rules**.
- **Allowed:** Neutral wording — e.g. processing **uses the Kaipai account quota** tied to the configured keys; **billing and plans** are **per your console or administrator**. If the user asks about cost, point them to **admin / official billing docs / console**; do not guess. When the API returns quota or membership errors, follow **Step 3 — MANDATORY (quota / consume failures)** using server **`detail`** and **`pricing_url`** when present.
- **On success too:** Success summaries must stay factual (task completed, delivery). Do **not** add “free” or zero-cost implications.

## Supported Algorithms

| task_name | Capability | Input |
|---|---|---|
| `eraser_watermark` | Image watermark removal | Image path or URL |
| `videoscreenclear` | Video watermark removal | Video path or URL |
| `image_restoration` | Image quality restoration | Image path or URL |
| `hdvideoallinone` | Video quality restoration | Video path or URL |

### Video tasks — default execution

For **`videoscreenclear`** and **`hdvideoallinone`**: **`spawn-run-task`** → pass **`sessions_spawn_args`** to **`sessions_spawn`** (main session does not block on **`run-task`**). Command shape, **`runTimeoutSeconds`** (default **3600**), worker **`install-deps`** / **`run-task`** / Step 4, polling and recovery: **[§3b](#3b--async-worker-sessions_spawn-all-video-tasks)** and **[docs/errors-and-polling.md](docs/errors-and-polling.md)**.

---

## Multi-stage pipelines (chaining tasks) / 多阶段管线

When the user asks for **more than one** Kaipai step on the **same** media (e.g. remove watermark **then** restore quality), treat each step as a **separate job**:

| Typical chain | Stages |
|---|---|
| Image | `eraser_watermark` → `image_restoration` |
| Video | `videoscreenclear` → `hdvideoallinone` |

**Rules:**

1. After stage A completes with `skill_status: "completed"`, use **`primary_result_url`** or **`output_urls[0]`** as **`--input`** for stage B with a **new** `--task`. That is a **new** job, not a retry of stage A. For **video**, stage B means a **new** **`spawn-run-task`** + **`sessions_spawn`** (each spawn embeds a **single** `run-task`), not a second `run-task` inside the same embed.
2. **“Do not re-run `run-task`”** in this skill means: **do not submit `run-task` again for the same `task_id` / the same submitted job** (use `query-task` to resume polling instead). It does **not** forbid the **next pipeline stage** with a different `task_name` and the previous result URL as input.
3. **Step 4 (delivery):** Prefer **final-stage** native delivery when the user wanted the full pipeline; intermediate stages may still run embedded Step 4 per worker (one spawn per video stage) — tune the user-facing copy if they only care about the last asset.
4. **Video chains (medeo-style):** **One `sessions_spawn` = one embedded `run-task`.** Do **not** put two `run-task` calls in one spawn. Chain = **multiple spawns**: after stage A, read **`primary_result_url`** from stdout or **`last-task`** / **`history`**, then **`spawn-run-task`** for stage B with that URL as **`--input`**. No video **`run-task`** in the main session. Optional one-line user update before the second spawn.

See also Step 3 success bullets and **`agent_instruction`** in the JSON.

---

## API submission path (MANDATORY)

- **New jobs:** Submit **only** via **`python3 {baseDir}/scripts/kaipai_ai.py run-task …`** (§3a / §3b), or the **same** `run-task` command embedded in **`spawn-run-task`** → `sessions_spawn`. **Do not** hand-craft HTTP to **wapi.kaipai.ai** or **AIGC / invoke** endpoints to replace that flow — that skips **`POST /skill/consume.json`** (quota and permission) and breaks the supported pipeline.
- **Exception:** **`query-task --task-id`** is **only** for resuming status polling on an **existing** full `task_id` (no upload, no second consume). **Do not** use it instead of **`run-task`** for a **new** submission.
- **No curl replay:** This skill does not emit debug curl for API calls. **Do not** hand-craft HTTP to **wapi / AIGC** to mimic requests — always use the **CLI** above so **`/skill/consume.json`** runs before algorithm submit.

---

## 0. Pre-Flight Check (MANDATORY — run before anything else)

Verify AK/SK are configured (**only run this command**; do not read other Python sources first):

```bash
python3 {baseDir}/scripts/kaipai_ai.py preflight
```

- Output `ok` → continue to Step 1
- Output `missing` → **stop** and send the user the configuration message below

**Feishu** — send an interactive card via the Feishu API (do not use the `message` tool for this):

```python
import json, urllib.request
cfg = json.loads(open("~/.openclaw/openclaw.json").read())
feishu = cfg["channels"]["feishu"]["accounts"]["default"]
token = json.loads(urllib.request.urlopen(urllib.request.Request(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    data=json.dumps({"app_id": feishu["appId"], "app_secret": feishu["appSecret"]}).encode(),
    headers={"Content-Type": "application/json"}
)).read())["tenant_access_token"]
card = {
    "config": {"wide_screen_mode": True},
    "header": {"title": {"tag": "plain_text", "content": "🖼️ Kaipai — credentials required"}, "template": "blue"},
    "elements": [{"tag": "div", "text": {"tag": "lark_md", "content": "Set **MT_AK** and **MT_SK** in `scripts/.env`, then run:\n```
source scripts/.env
```\nIf you do not have keys, contact your administrator."}}],
}
urllib.request.urlopen(urllib.request.Request(
    "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
    data=json.dumps({"receive_id": "<USER_OPEN_ID>", "msg_type": "interactive", "content": json.dumps(card)}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
))
```

**Telegram / Discord / other channels** — use the `message` tool with plain text:

```
🖼️ Kaipai — credentials required

Set MT_AK and MT_SK in scripts/.env, then run:
  source scripts/.env

If you do not have keys, contact your administrator.
```

---

## Step 1 — Pick task and input

Choose `task_name` from the table above and confirm the input file location.

**Media type → `task_name` (MANDATORY checklist):**

1. **Video** — Path or URL ends with common video extensions (e.g. `.mp4`, `.mov`, `.webm`, `.mkv`, `.m4v`) **or** the user / attachment clearly indicates **video / clip / footage** → choose only **`videoscreenclear`** (watermark) or **`hdvideoallinone`** (quality). Then use **§3b** (`spawn-run-task` + `sessions_spawn`), not blocking `run-task` in the main session.
2. **Image** — Extensions like `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp` **or** the user says **photo / picture / screenshot / 图** (static image) → choose only **`eraser_watermark`** or **`image_restoration`**. Use **§3a** (`run-task` in the main session). **Do not** use **`spawn-run-task`** for these tasks (the CLI rejects it).
3. **Watermark vs quality** — “Remove watermark / 去水印” → `eraser_watermark` (image) or `videoscreenclear` (video). “Restore / upscale / enhance / 画质修复 / 清晰化” → `image_restoration` (image) or `hdvideoallinone`