---
name: live2d-layer-decompose
version: 1.0.0
description: AI-powered 2D anime illustration layer decomposition into 22+ Live2D standard layers (PSD/PNG). Use when decomposing character illustrations into layered PSDs, monitoring async job status, exporting PSD assets, or integrating with automated Live2D rigging pipelines.
---

# Live2D Layer Decomposition Skill (English)

**Version**: 1.0.0 (API: v1, Spec: 2026-10-11)

> Available languages: [English (SKILL.md)](https://live2dlayer.com/skills/live2d-layer-decompose/SKILL.md) | [中文 (SKILL.zh.md)](https://live2dlayer.com/skills/live2d-layer-decompose/SKILL.zh.md) | [日本語 (SKILL.ja.md)](https://live2dlayer.com/skills/live2d-layer-decompose/SKILL.ja.md) | [한국어 (SKILL.ko.md)](https://live2dlayer.com/skills/live2d-layer-decompose/SKILL.ko.md) | [Français (SKILL.fr.md)](https://live2dlayer.com/skills/live2d-layer-decompose/SKILL.fr.md)

This skill enables AI agents and automated workflows to decompose flat 2D anime character illustrations into 22+ standard Live2D layers (hair, face, eyes, clothes, accessories, body) with SDXL-based occlusion inpainting, directly exporting layered Photoshop `.psd` files or complete PNG asset bundles.

---

## 1. Practical Usage Guidelines & Guardrails (Empirical Best Practices)

Based on extensive empirical evaluations across anime character benchmarks, complex costumes, and edge cases, follow these 5 core rules for optimal decomposition quality and credit efficiency:

### ① Art Style: Cel-Shading & Semi-Realistic Anime Preferred; Avoid Pixel Art
* **Recommended**: Standard Japanese anime cel-shading, commercial character art, flat illustrations with clean lineart. Diffusion cross-attention activates reliably, yielding natural inpainting behind occluded areas (e.g. ears behind hair, torso behind clothes).
* **Avoid**: **Retro Pixel Art (8-bit/16-bit), hyper-realistic photos, and rough sketches**. Under low-resolution pixel art, cross-attention often fails on specific accessories (e.g. wizard hats, wands), resulting in omitted layers or flat-cut silhouettes.

### ② Background: Transparent Alpha (RGBA PNG) is Essential
* **Recommended**: RGBA PNG with transparent alpha channel, or solid pure white/grey clean backgrounds.
* **Avoid**: Complex indoor/outdoor backgrounds, heavy particle effects, or text watermarks. Complex backgrounds cause Stage 1 segmentation to incorrectly assign background clutter into `objects` or `bottomwear` layers.

### ③ Pose & Occlusion: Frontal or 3/4 View; Minimize Severe Overlaps
* **Recommended**: Standing or upright seated poses, natural limb spacing, unobstructed face and eyes.
* **Avoid**: Extreme foreshortening (steep top-down or low-angle shots) and heavy self-occlusion (e.g. curling up with knees to chest, large guitars/shields covering the torso). Severe occlusion degrades inpainting accuracy on hidden inner layers.

### ④ Wide Accessories: Canvas Margin Buffer
* **Guideline**: When characters wear wide wizard hats, extended wings, or long staves, leave at least **5% to 10% empty canvas margin** around the boundaries.
* **Avoid**: Accessories touching the exact canvas border, which risks boundary-cropping artifacts.

### ⑤ Agent Guardrails: Local Uploads Only & No Runaway Retries
* **Payload Type**: **Local file Base64 uploads only**. Remote HTTP/HTTPS image URLs are strictly rejected to ensure backend privacy and security isolation.
* **Timing & Polling**: GPU inference takes **60 to 80 seconds**. Agents must use a **3 to 5 second polling interval** with a timeout of **180 seconds**.
* **Anti-Looping**: Never wrap failed API calls in unconditional `while` loops. Each successful job deducts account credits.

---

## 2. Automated Execution via Python Client

A complete client script is provided at `scripts/decompose_client.py`:

```bash
# 1. Set your API Key
export LIVE2D_API_KEY="sk-live2d-..."

# 2. Run decomposition and export layered PSD
python3 decompose_client.py \
  --image "/path/to/character.png" \
  --output "./character_decomposed.psd" \
  --resolution 1024
```

### Script Arguments
* `--image`: Path to local image file (PNG, JPG, or WEBP).
* `--api-key`: API key (`sk-live2d-...`). Can also be passed via `LIVE2D_API_KEY` environment variable.
* `--resolution`: Inference resolution (`1024` for standard, `1280` for Pro).
* `--output`: Output file path (defaults to `<image_name>_decomposed.psd`).
* `--zip`: Download complete asset ZIP (22 transparent PNGs + PSD) instead of standalone PSD.
* `--force`: Force re-decomposition (bypasses 7-day duplicate image hash protection).
* `--base-url`: Base endpoint URL (default: `https://live2dlayer.com`).

---

## 3. HTTP REST API Specification

### 1. Submit Decomposition Task
* **Endpoint**: `POST /api/decompose`
* **Headers**: `Authorization: Bearer sk-live2d-...`, `Content-Type: application/json`
* **Body**:
  ```json
  {
    "image": "data:image/png;base64,iVBORw0KGgo...",
    "resolution": 1024,
    "tblr_split": true,
    "force": false
  }
  ```
* **Response (HTTP 200)**:
  ```json
  {
    "status": "processing",
    "job_id": "job_1791550533941_abc12",
    "progress": 5,
    "stage": "Queued for GPU processing"
  }
  ```

### 2. Poll Task Status
* **Endpoint**: `GET /api/decompose/status?job_id=job_1791550533941_abc12`
* **Headers**: `Authorization: Bearer sk-live2d-...`
* **Response When Ready (HTTP 200)**:
  ```json
  {
    "status": "success",
    "job_id": "job_1791550533941_abc12",
    "progress": 100,
    "stage": "Completed",
    "layers": [
      {"name": "front_hair.png", "order": 15},
      {"name": "face.png", "order": 10}
    ]
  }
  ```

### 3. Download Layered PSD
* **Endpoint**: `POST /api/export-psd`
* **Headers**: `Authorization: Bearer sk-live2d-...`, `Content-Type: application/json`
* **Body**:
  ```json
  {
    "jobId": "job_1791550533941_abc12",
    "filename": "character_model"
  }
  ```
* **Response**: Binary stream (`Content-Type: application/x-photoshop`).