{"id":"c30a0c50-fa7e-463b-a494-4dbcd7de0eab","entityType":"agent","slug":"clawhub-chancipher-motu-color-engine","name":"MotuArt Color Engine","canonicalUrl":"https://www.xpersona.co/agent/clawhub-chancipher-motu-color-engine","canonicalPath":"/agent/clawhub-chancipher-motu-color-engine","generatedAt":"2026-10-10T10:43:37.173Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":null},"description":"AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, expor","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17795ep8yhs009f8px48emmp98a2mxc:motu-color-engine","sourceUrl":"https://clawhub.ai/chancipher/motu-color-engine","homepage":"https://clawhub.ai/chancipher/skills/motu-color-engine","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/chancipher/motu-color-engine","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/chancipher/skills/motu-color-engine","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"MotuArt Color Engine technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":null},"stars":null,"forks":null,"downloads":1664,"packageName":null,"latestVersion":"1.0.9","tractionLabel":"1.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:09:30.595Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T05:09:30.627Z","lastCrawledAt":"2026-10-10T05:09:30.595Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T05:09:30.595Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.9","createdAt":"2026-08-12T07:15:16.479Z","changelog":"**Summary:** Adds dedicated support for portrait lighting enhancement and updates workflow guidance. - Added `scripts/portrait-lighting.sh` for independent sculpting of portrait lighting with selectable styles and strengths. - Updated SKILL.md to document the new lighting script and its usage. - Extended crop, grading, and workflow documentation to include new lighting-style options. - Removed the `skill-card.md` file.","fileCount":25,"zipByteSize":61266},{"version":"1.0.7","createdAt":"2026-08-02T13:43:38.288Z","changelog":"- Added support for AI Headshots generation, including reference preparation, confirmation, professional headshot workflows, and staged export. - Introduced new scripts (`scripts/headshots.sh`) and documentation (`references/headshots-api.md`) for the headshots feature. - Updated required API scopes to include `headshot:process` for AI Headshots. - Expanded trigger keywords and description to cover professional AI Headshots and business/corporate portrait use cases. - Added a logo asset (`assets/motu-color-engine-logo.png`). - Removed legacy documentation file (`skill-card.md`).","fileCount":24,"zipByteSize":56566},{"version":"1.0.6","createdAt":"2026-07-14T16:10:32.798Z","changelog":"motu-color-engine 1.0.6 - Improved API key handling: now direct users to create and export keys from the account page instead of asking for pasted keys. - Updated security guidance: clarified never to hard-code, print, or expose keys and outlined supported API scopes. - Noted that account credits are required for processing calls; catalog discovery does not consume credits. - Service health and error handling (i.e., insufficient credits) instructions are now more explicit. - Added project logo (assets/motu-color-engine-logo.png); removed redundant documentation file (skill-card.md).","fileCount":21,"zipByteSize":26664},{"version":"1.0.5","createdAt":"2026-07-14T03:35:47.802Z","changelog":"- Added Motu Color Engine logo image: assets/motu-color-engine-logo.png. - Removed skill-card.md file. - Updated documentation for the id-pack.sh script to include two new optional arguments: outfit-id and outfit-long-edge, enabling control over clothing replacement and result size in ID photo package generation.","fileCount":21,"zipByteSize":26103},{"version":"1.0.4","createdAt":"2026-07-12T09:31:18.547Z","changelog":"motu-color-engine 1.0.4 - Added support for approved clothing replacement using catalog-based outfit IDs (new scripts: outfit.sh, outfits.sh). - Updated documentation to cover outfit replacement workflows and emphasize only using known catalog outfits. - Included new asset: `motu-color-engine-logo.png`. - Removed old documentation file: `skill-card.md`.","fileCount":21,"zipByteSize":26154},{"version":"1.0.3","createdAt":"2026-07-10T04:15:31.809Z","changelog":"- Added new scripts for ID/passport/visa/photo delivery, validation, optimization, and print-out preparation. - New workflows: `id-pack.sh` (ID photo package), `id-check.sh` (compliance check), `optimize.sh` (upload-ready conversion), `print-sheet.sh` (layout for printing). - Expanded documentation with usage examples and workflow explanations for each new script. - ID package workflow now supports multi-spec cropping, consistent color/smooth processing, compliance reporting, and optional print sheet generation.","fileCount":19,"zipByteSize":23037},{"version":"1.0.2","createdAt":"2026-07-09T02:28:09.646Z","changelog":"- Added logo images in PNG and SVG format to the assets directory. - No changes to functionality or documentation beyond logo asset addition.","fileCount":15,"zipByteSize":16765},{"version":"1.0.1","createdAt":"2026-07-08T10:39:56.483Z","changelog":"- Reference files renamed and reorganized from /reference/ to /references/ for clarity and consistency. - Documentation now clarifies the preferred use of bundled scripts for common workflows, referencing new /references/*.md files for style and crop spec details. - Instructions and API key handling guidance improved for setup clarity and security (never hard-code keys, always prompt user if missing). - All usage examples and script purposes updated for precision; workflow guidance and constraints are now clearer and more concise. - API and feature language further emphasize identity preservation; warnings added against describing the system as slimming, reshaping, or face-altering.","fileCount":14,"zipByteSize":15831}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17795ep8yhs009f8px48emmp98a2mxc:motu-color-engine","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17795ep8yhs009f8px48emmp98a2mxc:motu-color-engine` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/chancipher/motu-color-engine before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:43:37.168Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-chancipher-motu-color-engine/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":null},"readme":"Skill: MotuArt Color Engine\n\nOwner: chancipher\n\nSummary: AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, expor\n\nTags: latest:1.0.9\n\nVersion history:\n\nv1.0.9 | 2026-08-12T07:15:16.479Z | user\n\n**Summary:**  \nAdds dedicated support for portrait lighting enhancement and updates workflow guidance.\n\n- Added `scripts/portrait-lighting.sh` for independent sculpting of portrait lighting with selectable styles and strengths.\n- Updated SKILL.md to document the new lighting script and its usage.\n- Extended crop, grading, and workflow documentation to include new lighting-style options.\n- Removed the `skill-card.md` file.\n\nv1.0.7 | 2026-08-02T13:43:38.288Z | user\n\n- Added support for AI Headshots generation, including reference preparation, confirmation, professional headshot workflows, and staged export.\n- Introduced new scripts (`scripts/headshots.sh`) and documentation (`references/headshots-api.md`) for the headshots feature.\n- Updated required API scopes to include `headshot:process` for AI Headshots.\n- Expanded trigger keywords and description to cover professional AI Headshots and business/corporate portrait use cases.\n- Added a logo asset (`assets/motu-color-engine-logo.png`).\n- Removed legacy documentation file (`skill-card.md`).\n\nv1.0.6 | 2026-07-14T16:10:32.798Z | user\n\nmotu-color-engine 1.0.6\n\n- Improved API key handling: now direct users to create and export keys from the account page instead of asking for pasted keys.\n- Updated security guidance: clarified never to hard-code, print, or expose keys and outlined supported API scopes.\n- Noted that account credits are required for processing calls; catalog discovery does not consume credits.\n- Service health and error handling (i.e., insufficient credits) instructions are now more explicit.\n- Added project logo (assets/motu-color-engine-logo.png); removed redundant documentation file (skill-card.md).\n\nv1.0.5 | 2026-07-14T03:35:47.802Z | user\n\n- Added Motu Color Engine logo image: assets/motu-color-engine-logo.png.\n- Removed skill-card.md file.\n- Updated documentation for the id-pack.sh script to include two new optional arguments: outfit-id and outfit-long-edge, enabling control over clothing replacement and result size in ID photo package generation.\n\nv1.0.4 | 2026-07-12T09:31:18.547Z | user\n\nmotu-color-engine 1.0.4\n\n- Added support for approved clothing replacement using catalog-based outfit IDs (new scripts: outfit.sh, outfits.sh).\n- Updated documentation to cover outfit replacement workflows and emphasize only using known catalog outfits.\n- Included new asset: `motu-color-engine-logo.png`.\n- Removed old documentation file: `skill-card.md`.\n\nv1.0.3 | 2026-07-10T04:15:31.809Z | user\n\n- Added new scripts for ID/passport/visa/photo delivery, validation, optimization, and print-out preparation.\n- New workflows: `id-pack.sh` (ID photo package), `id-check.sh` (compliance check), `optimize.sh` (upload-ready conversion), `print-sheet.sh` (layout for printing).\n- Expanded documentation with usage examples and workflow explanations for each new script.\n- ID package workflow now supports multi-spec cropping, consistent color/smooth processing, compliance reporting, and optional print sheet generation.\n\nv1.0.2 | 2026-07-09T02:28:09.646Z | user\n\n- Added logo images in PNG and SVG format to the assets directory.\n- No changes to functionality or documentation beyond logo asset addition.\n\nv1.0.1 | 2026-07-08T10:39:56.483Z | user\n\n- Reference files renamed and reorganized from /reference/ to /references/ for clarity and consistency.\n- Documentation now clarifies the preferred use of bundled scripts for common workflows, referencing new /references/*.md files for style and crop spec details.\n- Instructions and API key handling guidance improved for setup clarity and security (never hard-code keys, always prompt user if missing).\n- All usage examples and script purposes updated for precision; workflow guidance and constraints are now clearer and more concise.\n- API and feature language further emphasize identity preservation; warnings added against describing the system as slimming, reshaping, or face-altering.\n\nv1.0.0 | 2026-07-07T23:35:52.510Z | auto\n\nInitial release of motu-color-engine — an AI-based portrait processing toolset.\n\n- Offers portrait skin-color grading, pro skin smoothing, skin segmentation/mask export, and automated ID/headshot photo cropping with optional background swap via HTTP API.\n- Provides shell scripts for grading, smoothing, mask export, cropping, and listing available styles and crop specs.\n- Designed to never reshape faces or alter identities; smoothing is opt-in, precise, and non-destructive to natural texture.\n- Accepts common photo formats (JPG, PNG, WebP) up to ~15 MB each.\n- Includes support for batch operations and background color replacement for appropriate crop specs.\n- All API settings, usage, and constraints are clearly documented for easy integration.\n\nArchive index:\n\nArchive v1.0.9: 25 files, 61266 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (462b), assets/motu-color-engine-logo.png (20946b), assets/motu-color-engine-logo.svg (2208b), references/api.md (12598b), references/crop-specs.md (6469b), references/headshots-api.md (9829b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3728b), scripts/headshots.sh (22392b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3981b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/outfit.sh (1361b), scripts/outfits.sh (1149b), scripts/portrait-lighting.sh (1187b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2934b), SKILL.md (17388b), _meta.json (136b)\n\nFile v1.0.9:SKILL.md\n\n---\nname: motu-color-engine\ndescription: AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, exporting mattes, replacing clothing, preparing identity references and generating professional headshot candidates, cropping to ID/passport/visa specs, replacing ID-photo backgrounds, checking compliance, optimizing uploads, or creating print sheets. Triggers include portrait grading, skin tone, retouch, skin mask, outfit replacement, AI headshots, professional headshot, business portrait, corporate portrait, LinkedIn photo, ID photo, passport photo, visa photo, background swap, print sheet, 调色, 肤色, 磨皮, 蒙版, 人像调色, AI形象照, 职业形象照, 商务形象照, 企业头像, 换装, 证件照, 裁剪, 换底, 合规检查, 排版, 一寸, 二寸.\n---\n\n# Motu Color Engine\n\nUse Motu Color Engine to process portrait images through the hosted HTTP API. Prefer the bundled scripts in `scripts/` over hand-written `curl` calls unless the user explicitly needs raw API details.\n\nThe engine preserves identity. Do not describe it as slimming, reshaping, face swapping, or changing facial structure. Skin smoothing only softens pores and blemishes inside detected skin regions. Cropping repositions and pads to a spec; it never stretches or compresses the face.\n\n## Setup\n\n- Require `curl` and `python3`.\n- Read `MCE_API_BASE` from the environment; default is `https://mce.motu.art`.\n- Read `MCE_API_KEY` from the environment; send it only as `X-API-Key`.\n- If the key is missing, direct the user to `https://mce.motu.art/account` (English: `/en/account`) to sign in by email and create one. Ask them to export it securely in their own environment; do not ask them to paste the full key into chat.\n- Never hard-code, print, log, commit, or expose API keys in browser/client code. The full key is shown once and can be rotated or revoked from the account page.\n- Request only the scopes needed: `catalog:read` for portrait/ID discovery, `portrait:process` for grading/smoothing/masks, `id-photo:process` for ID-photo workflows, `outfit:process` for outfit replacement, and `headshot:process` for private AI Headshots projects and generation. An ID package with an outfit needs both `id-photo:process` and `outfit:process`.\n- Processing calls consume account credits; catalog discovery does not. Surface `402 insufficient_credits` instead of retrying.\n- Check service health with `curl -sS \"${MCE_API_BASE:-https://mce.motu.art}/v1/health\"` when diagnosing connectivity.\n\n## Choose The Workflow\n\n- Use `scripts/grade.sh` when the user wants color grading, skin-tone correction, a film/commercial look, or grading plus optional crop.\n- Use `scripts/smooth.sh` when the user wants smoothing only with no color or white-balance change.\n- Use `scripts/portrait-lighting.sh` when the user wants visibly more dimensional portrait lighting, a brighter facial plane, readable dark clothing, or a focused background without changing identity or geometry.\n- Use `scripts/mask.sh` when the user wants a skin, valid-skin, face, or person mask/matte.\n- Use `scripts/crop.sh` when the user wants crop-only ID/passport/visa/headshot/avatar output, optionally with a solid background color.\n- Use `scripts/outfit.sh` when the user wants clothing replacement only. The outfit id must come from the approved catalog; never accept or invent a custom prompt or outfit id.\n- Use `scripts/outfits.sh` before clothing replacement to discover currently enabled outfit ids. Do not infer an id from a garment name.\n- Use `scripts/id-pack.sh` when the user wants a complete ID/passport photo delivery package: one graded/smoothed master, multiple specs, upload-ready files, compliance report, and optional print sheets.\n- Use `scripts/id-check.sh` when the user wants to validate an ID photo against a spec or understand compliance warnings.\n- Use `scripts/optimize.sh` when the user needs a website/upload-ready file with format, pixel size, DPI, or maximum KB constraints.\n- Use `scripts/print-sheet.sh` when the user wants cropped ID photos laid out on photo paper for printing.\n- Use `scripts/headshots.sh` when the user wants AI-generated professional, business, corporate, LinkedIn, or studio headshots. Keep reference preparation, confirmation, generation, candidate download, post-processing, and export as explicit stages; do not turn them into one automatic operation.\n- Use the Headshots person-reference library when the user wants to reuse a previously confirmed person. Distinguish starting a new project from applying that person to an existing project, and never delete existing projects when removing a library entry.\n- Use `scripts/styles.sh` to discover live style ids. Read `references/styles.md` only when the user needs style-selection guidance or offline context.\n- Use `scripts/crop-specs.sh` to discover live crop specs. Read `references/crop-specs.md` only when choosing specs or background palettes without live discovery.\n- Read `references/api.md` for endpoint parameters, response fields, headers, limits, and error codes.\n- Read `references/headshots-api.md` before operating the AI Headshots workflow or when the user needs its raw API details.\n\n## Grade Portraits\n\n```bash\nscripts/grade.sh <input-image> <output-image> [style-id] [strength] [smooth-strength] [smooth-texture-retain] [crop-spec] [bg-color] [pad-color] [lighting-style] [lighting-strength]\n```\n\n- Omit `style-id` for the default skin base, or choose a style from `scripts/styles.sh`.\n- Use `strength` for look intensity; default is `1.0`, `0` disables the look, and values up to about `1.5` are stronger.\n- Pass `smooth-strength` from `0` to `1` only when the user asks for softened pores or blemishes. Omit it, or pass `0`, to preserve natural texture.\n- Use `smooth-texture-retain` from `0` to `1` to keep natural texture over smoothing; default is `0.35`.\n- Pass `crop-spec` when the same output should be graded and cropped in one API call.\n- Pass `bg-color` only with `crop-spec`; use an allowed palette name such as `white`, `blue`, or `red`, `default`, or explicit `#RRGGBB`.\n- Pass `pad-color` only with `crop-spec` when a specific padding color is needed; otherwise let the API edge-replicate.\n- Pass `lighting-style` only when the same output should also receive portrait light sculpting; choose `natural_dimension`, `soft_luminous`, or `studio_definition`. Omit it to preserve the existing grading result.\n- Use `lighting-strength` from `0` to `1` to override that preset's calibrated strength.\n- Report `skin_dE` from script output when summarizing quality; lower means closer skin color to the target.\n\nFor a folder, run the script once per image. Keep batch loops serial unless the user asks for parallelism and accepts API/load implications.\n\n## Smooth Skin Only\n\n```bash\nscripts/smooth.sh <input-image> <output.png> [strength] [texture-retain]\n```\n\n- Use this for pore/blemish softening without style, color, or white-balance changes.\n- Default `strength` is `0.6`.\n- Default `texture-retain` is `0.35`; raise it to preserve more natural texture.\n\n## Sculpt Portrait Lighting\n\n```bash\nscripts/portrait-lighting.sh <input-image> <output.png> [style] [strength]\n```\n\n- Styles are `natural_dimension` (default), `soft_luminous`, and `studio_definition`.\n- Omit `strength` to use the calibrated default for the selected style; otherwise use `0`–`1`.\n- `soft_luminous` prioritizes a luminous face and open dark midtones; `natural_dimension` balances face, wardrobe and background; `studio_definition` adds the strongest background focus and local definition.\n- The operation reshapes luminance relationships only. It never moves facial features, changes face/body geometry, or regenerates image content.\n- Use it independently after another editor, or as an explicit post-process after the user selects a Headshots candidate once that integration is available.\n\n## Export Masks\n\n```bash\nscripts/mask.sh <input-image> <output.png> [mask-kind]\n```\n\n- Use `skin` by default.\n- Other mask kinds are `valid_skin`, `face`, and `person`.\n- Output is an 8-bit grayscale PNG aligned to the input.\n\n## Crop ID Or Portrait Photos\n\n```bash\nscripts/crop.sh <input-image> <output-image> [spec-id] [bg-color] [pad-color]\n```\n\n- Default `spec-id` is `one_inch`.\n- Use `scripts/crop-specs.sh` to list supported specs and allowed background colors.\n- Use `bg-color` only when the spec declares a background palette, mostly ID-photo specs.\n- Use `pad-color` only when a source image lacks required margins and the user wants a specific fill.\n- Surface crop warnings from script output, especially warnings about margins, resolution, or background limitations.\n- Use `grade.sh` with crop arguments when the user wants grading and crop in one output.\n\n## Make ID Photo Packages\n\n```bash\nscripts/id-pack.sh <input-image> <output-dir> [specs] [style-id] [smooth-strength] [bg-color] [upload] [print-sheet] [outfit-id] [outfit-long-edge]\n```\n\n- Use this for passport/visa/ID-photo deliverables rather than calling `grade.sh` once per spec. The API generates one graded/smoothed master first, then crops multiple specs from that master so colour and retouching stay consistent.\n- `specs` is comma-separated, e.g. `passport_cn,one_inch,us_visa`; default is `passport_cn`. School/enrollment specs include `shanghai_compulsory_education_cn`, `college_graduation_image_cn`, and `national_k12_student_status_cn`.\n- Default style is `motu_business_neutral`; pass `smooth-strength` from `0` to `1` only when the user asks for smoothing.\n- `bg-color` defaults to `default`, which applies each spec's standard background palette. Use `white`, `blue`, `light_blue`, `red`, or `#RRGGBB` when the user asks and the spec allows it.\n- `upload` defaults to `true`, writing upload-optimized JPG files using the spec's `upload` rules from `crop_specs.json`.\n- `print-sheet` is optional, e.g. `6x4` or `a4`; when specs have different sizes, separate sheets may be generated.\n- `outfit-id` is optional. When present, it must be an id returned by `scripts/outfits.sh`; omitted keeps the original clothing.\n- `outfit-long-edge` controls the upstream outfit result size, defaults to 1536, and is bounded by the service to 512–2048px.\n- Output folder contains `master.png`, `single/`, `upload/`, `print/`, and `report.json`. Surface compliance status and warnings from the report.\n- When the user requests a supported outfit, pass its approved catalog id. Outfit replacement runs before the corrected master is generated, so all crop specs share the same clothing result.\n\n## Replace Clothing Only\n\nDiscover the approved catalog first:\n\n```bash\nscripts/outfits.sh\n```\n\nSelect only an id returned by that command, then replace clothing:\n\n```bash\nscripts/outfit.sh <input-image> <output.png> <approved-outfit-id> [long-edge]\n```\n\n- Only use ids returned by `GET /v1/outfits`; the API maps each approved id to its controlled generation prompt and rejects custom prompts or arbitrary ids.\n- The catalog groups styles as `male`, `female`, `kids`, or `unisex`; use the category and localized name/description to help select a suitable style.\n- If the requested clothing is absent, explain that only catalog styles are available; do not substitute a custom prompt, URL, or upload.\n- The service protects the detected facial oval with the face mask and calls the configured Motu asynchronous workflow.\n- Default output long edge is 1536px; the service bounds requests to 512–2048px.\n- Clothing generation must preserve the face and identity. Report upstream failures or timeouts instead of silently returning the original image.\n\n## Create AI Headshots\n\nUse one work directory for the whole staged workflow. The script stores non-secret ids,\nresponses, and configuration in `headshots.json`; it never stores `MCE_API_KEY`.\n\nDiscover current options:\n\n```bash\nscripts/headshots.sh catalog [locale]\n```\n\nList reusable confirmed people:\n\n```bash\nscripts/headshots.sh people [limit]\n```\n\nPrepare a graded, optionally smoothed, purpose-cropped identity reference:\n\n```bash\nscripts/headshots.sh prepare <input-image> <work-dir> \\\n  [--scene ID] [--garment male|female] [--skin-base ID] [--smoothing 0..1] \\\n  [--crop-spec ID] [--crop-anchor auto|center|manual] \\\n  [--crop-rect X,Y,W,H] [--rotation DEG]\n```\n\n- Inspect `source-check.json` and `reference-preview.png` before continuing.\n- Surface ineligible reasons and warnings. Do not submit generation for an ineligible source.\n- `skin-base` performs colour/skin-tone preparation; `smoothing=0` preserves natural texture.\n- Use an automatic crop unless the user provides a complete normalized manual rectangle.\n- Never confirm the reference without the user approving the preview.\n\nAfter approval, freeze that preview as the identity reference:\n\n```bash\nscripts/headshots.sh confirm <work-dir>\n```\n\nConfirmation automatically adds the approved person to the account library, deduplicated\nby the confirmed reference image. To start a separate project from a saved person, or switch\nthe active person inside an existing project while preserving its history:\n\n```bash\nscripts/headshots.sh start-person <person-reference-id> <new-work-dir> [--scene ID]\nscripts/headshots.sh use-person <existing-work-dir> <person-reference-id>\n```\n\n`use-person` appends a new immutable reference to the same project. Existing jobs, candidates,\nfavorites, and prior references remain available. Removing a person is a library-only soft delete:\n\n```bash\nscripts/headshots.sh remove-person <person-reference-id>\n```\n\nSubmit a compatible generation plan without waiting for the asynchronous worker:\n\n```bash\nscripts/headshots.sh generate <work-dir> [--scene ID] [--batch-size 1|2|4] \\\n  [--style ID] [--pose ID] [--outfit ID] [--background ID] \\\n  [--ratio 1:1|4:5|3:4] [--framing auto|close_up|half_body|three_quarter]\n```\n\n- Let the recommendation endpoint fill omitted options and correct incompatible defaults.\n- Use only ids returned by the live Headshots catalog. Never send custom generation prompts.\n- Generation consumes credits per requested image. Surface `402` and do not retry unchanged.\n- The command submits one job and returns; it does not hide asynchronous work behind a long synchronous call.\n\nCheck and download results explicitly:\n\n```bash\nscripts/headshots.sh status <work-dir>\nscripts/headshots.sh download <work-dir>\n```\n\nDownload after the job is `completed` or `partially_completed`. For a partial result, surface the\nfailure reason and download every ready candidate rather than discarding successful outputs.\n\nPost-process a user-selected candidate and optionally export that render:\n\n```bash\nscripts/headshots.sh render <work-dir> --candidate ID-or-ordinal --style ID [--locale LOCALE]\nscripts/headshots.sh light <work-dir> --candidate ID-or-ordinal [--style ID] [--strength 0..1] [--render]\nscripts/headshots.sh export <work-dir> --candidate ID-or-ordinal [--render] \\\n  [--crop SPEC] [--format jpeg|png|webp] [--quality 70..100]\n```\n\n- Require an explicit candidate id or ordinal.\n- `light` without `--render` creates an immutable lighting Render from the Candidate master. With `--render`, it uses the latest saved Render as its source, allowing an explicit grade → light chain without overwriting either version.\n- Without `--render`, export the generated master candidate. With `--render`, use the latest explicit render saved in the work directory.\n- Keep `project_id`, `reference_id`, `job_id`, and derivative ids so an interrupted workflow can resume.\n\n## Check ID Photo Compliance\n\n```bash\nscripts/id-check.sh <input-image> [spec-id] [report-json]\n```\n\n- Without `report-json`, the input is treated as a source portrait: the API crop-checks it against the spec and reports practical compliance.\n- With `report-json`, the input is treated as the already-cropped ID photo and the supplied crop metrics are checked.\n- Report failures and warnings plainly; this is a practical QA check, not a government guarantee.\n\n## Optimize Upload Files\n\n```bash\nscripts/optimize.sh <input-image> <output-image> [format] [max-kb] [quality] [resize] [dpi]\n```\n\n- Use for official website upload limits such as JPG under a maximum KB, exact pixel dimensions, or DPI metadata.\n- `format` is `jpg`, `png`, or `webp`; `resize` is `WIDTHxHEIGHT`; lossy formats search quality down to the server default floor when `max-kb` is set.\n\n## Make Print Sheets\n\n```bash\nscripts/print-sheet.sh <output-image> <paper> <input1> [input2 ...]\n```\n\n- Use after generating cropped ID photos when the user wants a printable sheet.\n- `paper` supports common values such as `6x4`, `4x6`, `5x7`, and `a4`. Inputs on a single sheet must have the same pixel size; use `id-pack.sh` for automatic grouping by size.\n\n## Constraints To Surface\n\n- Upload limit is about 15 MB per image.\n- Supported upload formats are JPG, PNG, and WebP.\n- Portrait, crop, and ID-photo processing calls are synchronous. Headshots generation is asynchronous and must be polled by job id.\n- Background replacement is limited to specs that declare `bg_colors`.\n- If a script fails, read its HTTP status and error detail before deciding whether to retry, change arguments, or ask the user for configuration.\n\nFile v1.0.9:_meta.json\n\n{\n  \"ownerId\": \"kn7b98pvjtsm6a4bw8gd87ttbs8a3ycc\",\n  \"slug\": \"motu-color-engine\",\n  \"version\": \"1.0.9\",\n  \"publishedAt\": 1786518916479\n}\n\nFile v1.0.9:references/api.md\n\n# MotuArt Color Engine — API reference\n\nBase URL: `$MCE_API_BASE` (default `https://mce.motu.art`).\nAuth: create a key at `https://mce.motu.art/account` (English: `/en/account`), then send\n`X-API-Key: $MCE_API_KEY` (or `Authorization: Bearer $MCE_API_KEY`) on private and\nprocessing endpoints. `/v1/health` and public Headshots discovery endpoints do not need\na key. The full key is displayed once; store it securely and rotate or revoke it from\nthe account page if exposed.\n\nScopes:\n- `catalog:read` — styles, crop specs and approved outfits.\n- `portrait:process` — process, smooth and mask.\n- `id-photo:process` — crop, id-pack, id-check, optimize and print-sheet.\n- `outfit:process` — standalone outfit replacement. Also required in addition to\n  `id-photo:process` or `portrait:process` when those requests include `outfit_id`.\n- `headshot:process` — private AI Headshots projects, reference preparation,\n  generation, candidates, post-processing, and exports. See `headshots-api.md`.\n\nSuccessful processing calls consume account credits; catalog requests do not. A `402`\nresponse uses `detail.code=\"insufficient_credits\"` and includes `required`, `available`,\nand whether the request included outfit replacement.\n\n## GET /v1/health\nLiveness/version. No key required.\n\n## GET /v1/styles\nReturns `{ styles: [{id, name, kind, name_zh, ...}], composite_separator, bases, flavours }`.\n`kind` is `base` or `flavour`. Combine as `<flavour><composite_separator><base>`\n(default separator `@`), e.g. `kodak_gold@motu_korean_id`.\n\n## POST /v1/process  (multipart/form-data)\nGrade an image. Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `style` — style id (default `motu_korean_id`).\n- `strength` — look intensity, default `1.0` (0–~1.5).\n- `smooth_strength` — optional M15 pro skin smoothing, `0`–`1`. Omitted/`0` leaves skin\n  texture untouched (default). Softens pores/blemishes only; never reshapes the face.\n- `smooth_texture_retain` — optional, `0`–`1` (default `0.35`), how much natural\n  texture to keep on top of the smoothing. Only used when `smooth_strength` > 0.\n- `portrait_lighting_style` — optional M17 light-sculpting preset:\n  `natural_dimension`, `soft_luminous`, or `studio_definition`. Omit it and all\n  `portrait_lighting_*` fields to keep the existing grading output unchanged.\n- `portrait_lighting_strength` — optional `0`–`1`; omitted uses the selected preset's\n  calibrated strength. Supplying this without a style uses `natural_dimension`.\n- `portrait_lighting_face_light_balance`, `portrait_lighting_subject_separation`,\n  `portrait_lighting_local_contrast`, `portrait_lighting_skin_protection`, and\n  `portrait_lighting_highlight_protection` — optional advanced overrides, each `0`–`1`.\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n- `max_long_edge` — cap working long edge (default 1024; server ceiling applies).\n- `mask` — `true` to also return a mask inline (base64).\n- `mask_kind` — mask type when `mask=true` (see below).\n- `crop_spec` — optional M16 purpose crop spec id (see `GET /v1/crop/specs`). When set,\n  the graded output is additionally cropped to that spec (grade + crop in one call).\n  Omitted — full graded frame, uncropped.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin; only used with `crop_spec`. Omitted — edge-replicate padding (the default).\n- `bg_color` — optional background replacement (换底), only used with `crop_spec`: a\n  palette name the spec allows (e.g. `white`/`blue`/`red`), `default` for the spec's\n  standard color, or an explicit `#RRGGBB`. Omitted — original background kept.\n\nResponse JSON:\n```\n{ \"trace_id\", \"style_id\", \"image_base64\", \"content_type\",\n  \"processing_time_ms\", \"quality\": { \"skin_delta_e_to_target\", \"warnings\" },\n  \"report_url\", \"compare_base64\",\n  \"mask_base64\", \"mask_kind\", \"mask_content_type\" }   // mask_* only when mask=true\n```\nDecode `image_base64` to bytes to get the graded image. `skin_delta_e_to_target`\nis the skin ΔE to the target skin (lower = closer).\nWhen portrait lighting is enabled, `GET report_url` includes a `portrait_lighting`\nmetrics object describing the applied preset, strength, EV guard, and before/after\nsubject-separation measurements.\n\n## POST /v1/mask  (multipart/form-data)\nSegmentation only (decode + parse; **skips grading/render/score** — faster). Fields:\n- `file` (required).\n- `mask_kind` — `skin` (default) | `valid_skin` | `face` | `person`.\n- `max_long_edge` — optional.\n\nReturns the mask as a raw **grayscale PNG** (`Content-Type: image/png`), with header\n`X-MCE-Mask-Kind`. Save the response body directly.\n\n## POST /v1/smooth  (multipart/form-data)\nStandalone M15 pro skin smoothing — runs decode + parse + smoothing + render only,\n**skipping the entire color-grading stack**. Softens pores/blemishes on the detected\nskin region; never reshapes the face or changes color. Fields:\n- `file` (required).\n- `strength` — smoothing amount, default `0.6`.\n- `texture_retain` — how much natural texture to keep, default `0.35`.\n- `radius_frac` — optional blur radius override (fraction of face size).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the smoothed image as a raw payload (default `image/png`), like `/v1/mask`.\n\n## POST /v1/portrait-lighting  (multipart/form-data)\nStandalone deterministic portrait light sculpting. Runs decode + human parse + M17 +\nrender only, preserving identity, geometry, image content, and the existing light\ndirection. Fields:\n\n- `file` (required).\n- `style` — `natural_dimension` (default), `soft_luminous`, or `studio_definition`.\n- `strength` — optional `0`–`1`; omitted uses the selected style's calibrated default.\n- `face_light_balance`, `subject_separation`, `local_contrast`, `skin_protection`,\n  `highlight_protection` — optional advanced overrides, each `0`–`1`.\n- `max_long_edge` — optional working-resolution cap.\n- `output_format` — `png` (default), `jpeg`, or `webp`.\n- `quality` — 1–100 for lossy formats.\n\nReturns the processed image as a raw payload. `X-MCE-Trace-Id` identifies the request;\n`X-MCE-Lighting-Info` contains the applied style, strength, maximum EV adjustment,\nsubject-separation measurements, and warnings.\n\nLocal CLI equivalent:\n\n```bash\nmce run --input portrait.jpg --output lit.png --portrait-lighting-only \\\n  --lighting-style natural_dimension --lighting-strength 0.70\n```\n\n## GET /v1/crop/specs\nList the available purpose-crop specs (证件照/形象照/头像 standards). Returns\n`{ specs: [{id, name, name_zh, category, width_px, height_px, width_mm, height_mm,\ndpi, head_ratio, bg_colors, default_bg, description_zh}] }`.\n- `category` — `id_photo` | `portrait` | `avatar`.\n- `width_mm`/`height_mm`/`dpi` — physical print size; `null` for portrait/avatar specs\n  (pixel-only, no print standard).\n- `bg_colors` — `{name: \"#RRGGBB\"}` palette the spec allows for background\n  replacement; `{}` when the spec does not standardize a background (most\n  portrait/avatar specs). `default_bg` is the palette name applied when a caller\n  requests `bg_color=\"default\"`.\n- See `references/crop-specs.md` for a curated overview of the shipped specs.\n\n## POST /v1/crop  (multipart/form-data)\nStandalone M16 purpose-crop. Runs decode + face/head geometry + crop **only** — no\nhuman parsing, no color grading (use `/v1/process` with `crop_spec` to grade and crop\ntogether). Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `spec` — crop spec id (default `one_inch`); see `GET /v1/crop/specs`.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin. Omitted — edge-replicate padding.\n- `bg_color` — optional background replacement (换底): a palette name the spec\n  allows, `default` for the spec's standard color, or an explicit `#RRGGBB`. Omitted —\n  original background kept.\n- `max_long_edge` — optional working-resolution cap; `0`/omitted means **full source\n  resolution** (crop quality is bounded by source resolution, not a latency budget —\n  unlike `/v1/process`, which defaults to 1024).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the cropped image as a raw payload (default `image/png`, with the spec's DPI\nembedded), like `/v1/mask`/`/v1/smooth`. The achieved geometry and any warnings are in\nthe `X-MCE-Crop-Info` response header (JSON), alongside `X-MCE-Trace-Id`.\n\n## POST /v1/id-pack  (multipart/form-data)\nGenerate a complete ID-photo delivery package. The service creates one graded/smoothed\nmaster, detects face/head geometry once, then crops multiple specs from that master.\nFields:\n- `file` (required) — image upload.\n- `specs` (required) — comma-separated crop spec ids, e.g. `passport_cn,one_inch`.\n- `style` — style id (default `motu_korean_id`).\n- `smooth_strength`, `smooth_texture_retain` — optional skin smoothing.\n- `strength`, `output_space`, `max_long_edge` — same meaning as `/v1/process`.\n- `bg_color` — `default` (recommended for ID photos), palette name, or `#RRGGBB`.\n- `pad_color` — optional padding colour.\n- `output_format` — `png` (default) | `jpeg` | `webp` for single-spec files.\n- `quality` — output quality for lossy formats.\n- `upload` — `true` to include upload-optimized files using spec `upload` rules.\n- `print_sheet` — optional paper id such as `6x4`/`a4`; groups same-size photos.\n\nResponse JSON includes `trace_id`, `style_id`, `master_base64`, `items[]` with\n`image_base64`, `crop_info`, `compliance`, optional `upload.image_base64`, optional\n`print_sheets[].image_base64`, and the master quality report.\n\nOptional outfit fields:\n- `outfit_id` — approved id returned by `GET /v1/outfits`; omitted keeps the original clothing.\n- `outfit_long_edge` — upstream generation long edge, bounded to 512–2048; default 1536.\n\n## GET /v1/outfits\nReturns the approved outfit catalog. Each item includes `id`, localized names and\ndescriptions, `category` (`male`/`female`/`kids`/`unisex`), `order`, `available`, and\noptional `preview_url`. `available` mirrors the catalog's `enabled` switch. The\ncontrolled `generation_prompt` used by the workflow is never exposed.\n\n## POST /v1/outfit  (multipart/form-data)\nControlled standalone clothing replacement. Fields:\n- `file` (required) — source JPG, PNG, or WebP.\n- `outfit_id` (required) — approved catalog id. Custom prompts and arbitrary ids are rejected.\n- `long_edge` — requested generation long edge, bounded to 512–2048; default 1536.\n\nResponse JSON contains `task_id`, `outfit_id`, `image_base64`, `content_type`,\n`long_edge`, and `processing_time_ms`. MCE resolves the id to its controlled\n`generation_prompt`, then submits the source, prompt, face mask, and long edge to the\nconfigured asynchronous Motu workflow and polls it.\n\n## POST /v1/id-check  (multipart/form-data)\nCheck an ID photo against a crop spec. Fields:\n- `file` (required) — source portrait, or already-cropped ID photo when `report_json` is supplied.\n- `spec` (required) — crop spec id.\n- `report_json` — optional crop report containing `metrics.crop`; use this when checking an already-cropped output.\n- `bg_color` — optional background for the temporary crop-check path (default `default`).\n\nResponse JSON: `{ ok, status, checks, warnings, errors }`. This is practical QA, not\na government acceptance guarantee.\n\n## POST /v1/optimize  (multipart/form-data)\nExport an upload-ready file. Fields:\n- `file` (required).\n- `output_format` — `jpg`/`jpeg` (default), `png`, or `webp`.\n- `max_kb` — optional maximum file size in KB.\n- `quality`, `min_quality` — lossy encoder quality range.\n- `resize` — optional `WIDTHxHEIGHT`.\n- `dpi` — optional DPI metadata.\n\nReturns the optimized image as a raw payload. Metadata is in `X-MCE-Export-Info`.\n\n## POST /v1/print-sheet  (multipart/form-data)\nLayout one or more same-size ID photos on paper. Fields:\n- `files` — one or more image uploads.\n- `paper` — `6x4` (default), `4x6`, `5x7`, `7x5`, `a4`, or `WIDTHxHEIGHTin`.\n- `dpi`, `margin_mm`, `gap_mm`, `cut_lines`, `output_format`.\n\nReturns the print sheet as a raw image payload. Metadata is in `X-MCE-Print-Sheet-Info`.\n\n## Errors\n- `400` bad params / empty upload · `401` missing/invalid key ·\n  `413` too large · `415` unsupported content-type · `422` processing/segmentation failed.\nError bodies are JSON `{ \"detail\": \"...\" }`.\n\nFile v1.0.9:references/crop-specs.md\n\n# MotuArt Color Engine — crop specs overview (M16 purpose crop)\n\nThe live catalog is authoritative — run `scripts/crop-specs.sh` (or `GET\n/v1/crop/specs`) to list current ids/sizes. This is a quick orientation to the\nthree categories and the shipping specs.\n\n## Three categories\n\n- **id_photo** — official ID/passport/visa/license photo standards. Fixed pixel size\n  + physical `width_mm`/`height_mm` + `dpi` (embedded on save, so exports print at the\n  right physical size). Most declare a `bg_colors` palette for background replacement\n  (换底) since these documents require a specific solid background. ID-photo specs may\n  also include `compliance`, `upload`, and `print` metadata used by `id-pack`,\n  `id-check`, upload optimization, and print-sheet layout.\n- **portrait** — professional/editorial portrait framings (headshot to full body).\n  Pixel-only, no print standard, no background palette (original background kept).\n- **avatar** — square social-avatar framing. Pixel-only, no background palette.\n\nPass only a `spec` id — the engine auto-detects the face/head and positions it to\nthat spec's `head_ratio` (crown-to-chin as a fraction of output height) and margins;\nyou never draw a crop box by hand.\n\n## id_photo specs (fixed background palette, mostly white/blue/red)\n\n| id | Use | Size | Print |\n| --- | --- | --- | --- |\n| `one_inch` | 简历/证件 general 1-inch | 295×413px | 25×35mm@300dpi |\n| `two_inch` | Standard 2-inch | 413×579px | 35×49mm@300dpi |\n| `small_two_inch` | Small 2-inch (passport/visa common) | 413×531px | 35×45mm@300dpi |\n| `small_one_inch` | Driver's license / some certificates | 260×378px | 22×32mm@300dpi |\n| `big_two_inch` | Diploma (blue background common) | 413×626px | 35×53mm@300dpi |\n| `id_card_cn` | CN ID card / social security card (GA 461) | 358×441px | 26×32mm@350dpi |\n| `shanghai_compulsory_education_cn` | 上海义务教育入学免冠证件照 | 272×354px | 20×26mm@350dpi |\n| `college_graduation_image_cn` | 大学生毕业图像信息采集免冠证件照 | 480×640px | 41×54mm@300dpi |\n| `national_k12_student_status_cn` | 全国中小学生学籍电子版照片 | 358×441px | 26×32mm@350dpi |\n| `passport_cn` | CN passport / HK-Macau-Taiwan permit / CN visa | 390×567px | 33×48mm@300dpi |\n| `us_visa` | US visa 2×2 | 600×600px | 51×51mm@300dpi |\n| `schengen_visa` | Schengen/UK visa | 413×531px | 35×45mm@300dpi |\n| `japan_visa` | Japan visa | 531×531px | 45×45mm@300dpi |\n| `canada_visa` | Canada visa/immigration | 590×826px | 50×70mm@300dpi |\n| `china_visa` | China visa printed photo | 390×567px | 33×48mm@300dpi; digital upload uses a separate crop |\n| `us_passport_printed` | US passport (paper application) | 600×600px | 51×51mm@300dpi |\n| `japan_passport` | Japan passport | 413×531px | 35×45mm@300dpi |\n| `canada_passport_printed` | Canada passport (paper application) | 590×826px | 50×70mm@300dpi |\n| `uk_passport_printed` | UK printed passport photo | 413×531px | 35×45mm@300dpi |\n| `uk_visa` | UK visa or permission digital photo | 600×750px minimum | JPG/JPEG, 50KB–6MB |\n| `malaysia_passport_photo` / `malaysia_evisa` | Malaysia passport supplied-photo cases / eVISA | 413×591px | 35×50mm@300dpi |\n| `thailand_passport_photo` | Thailand passport capture preparation | 413×531px illustrative crop | live capture; not a submission file |\n| `thailand_visa` | Thailand visa | 413×531px | 35×45mm@300dpi |\n| `vietnam_passport_photo` / `vietnam_evisa` | Vietnam passport / e-visa | 472×709px | 40×60mm@300dpi |\n| `philippines_passport_photo` | Philippines passport live-capture readiness reference | 413×531px | 35×45mm@300dpi |\n| `philippines_visa_online` | Philippines online visa | 600×600px | digital only |\n| `australia_passport_printed` | Australia passport (paper application) | 413×531px | 35×45mm@300dpi |\n| `australia_visa_photo` | Australia visa supplied photo when explicitly requested | 35×45mm @300dpi | channel-specific |\n| `korea_passport` / `korea_visa` | Korea passport / visa | 413×531px | 35×45mm@300dpi |\n| `singapore_passport_online` / `singapore_visa_online` | Singapore passport / visa online | 400×514px | digital only |\n\nSome passport and visa channels capture the applicant live instead of accepting a\nprepared file. Specs marked `capture_channel_limited` or `live_capture_only` must\nsurface that limitation; they are not a substitute for an in-person or in-app capture.\nSpecs marked `editing_restricted` should be used without grading, smoothing, outfit\nreplacement, background synthesis, or other appearance-changing processing.\n\n## portrait specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `headshot_3x4` | Close face headshot (actor/streamer/résumé) | 900×1200px | 0.55 |\n| `profile_4x5` | Professional headshot (LinkedIn/website/business card) | 1200×1500px | 0.42 |\n| `bust_3x4` | Chest-up bust portrait (team page/instructor bio) | 1200×1600px | 0.33 |\n| `half_body_2x3` | Waist-up half body (magazine-style, needs waist+ in source) | 1200×1800px | 0.26 |\n| `three_quarter_2x3` | Knee-up three-quarter body (needs knee+ in source) | 1200×1800px | 0.19 |\n| `full_body_9x16` | Full body, vertical poster/social (needs full body in source) | 1080×1920px | 0.13 |\n| `banner_16x9` | Wide head-and-shoulders banner (website/video cover) | 1920×1080px | 0.45 |\n\n## avatar specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `avatar_1x1` | Square social avatar (WeChat/DingTalk/general) | 800×800px | 0.45 |\n\n## Background replacement (换底)\n\nOnly `id_photo` specs declare a `bg_colors` palette (e.g. `{\"white\": \"#FFFFFF\",\n\"blue\": \"#438EDB\", \"light_blue\": \"#D6EAF8\", \"red\": \"#FF0000\"}` for the CN sizes). Pass a palette name, `default`\n(the spec's standard choice), or an explicit `#RRGGBB` as `bg_color` — an\nunrecognized name is rejected (the palette *is* the compliance rule for these\ndocuments). Background swap runs a portrait-matting pass on the crop window at source\nresolution, so hair/ear edges stay clean (no crude-cutout fringe).\n\n## Framing guarantee\n\nCropping only repositions the frame (head ratio + margins) — it never stretches or\ncompresses facial proportions. Wide framings (`half_body_2x3`, `three_quarter_2x3`,\n`full_body_9x16`) require the source photo to actually contain that much of the body;\nthe engine pads (edge-replicate or `pad_color`) rather than invent missing content.\n\nFile v1.0.9:references/headshots-api.md\n\n# AI Headshots API\n\nUse this reference for the staged professional-headshot workflow. Use\n`scripts/headshots.sh` for normal operation instead of assembling requests manually.\n\n## Authentication and ownership\n\nSend an account API key with the `headshot:process` scope:\n\n```http\nX-API-Key: $MCE_API_KEY\n```\n\n`Authorization: Bearer $MCE_API_KEY` is also accepted. The account user becomes the\nowner of every project and private asset. Another account receives a not-found response\ninstead of access to that data. Server environment keys are not sufficient without a\nuser identity.\n\nThese discovery endpoints are public:\n\n- `GET /v1/headshots/catalog?locale=en`\n- `GET /v1/headshots/showcases?locale=en`\n- `GET /v1/headshots/showcases/{showcase_id}?locale=en`\n- `GET /v1/headshots/scenes/{scene_id}?locale=en`\n\nSupported published locales are `en`, `zh-CN`, `ja-JP`, `ko-KR`, `th-TH`, `vi-VN`,\n`ms-MY`, `id-ID`, and `fil-PH`. Short content-language aliases are accepted where documented.\n\n## Workflow\n\nKeep the identifiers returned by each stage:\n\n```text\nproject_id -> preview_id -> reference_id -> job_id -> candidate_id\n                                                   -> render_id -> export_id\n```\n\nDo not submit generation before the user has reviewed and confirmed the reference\npreview. Generation consumes credits; preparation and discovery do not.\n\n## Prepare a reference\n\n### Create or restore a project\n\n`POST /v1/headshots/projects` is multipart form data:\n\n- `image` — required JPG, PNG, or WebP, subject to the service upload limit.\n- `scene_id` — optional live scene id.\n- `entry_source` — normally `direct_upload`, or `scene_gallery` when a scene led to the upload.\n\nDo not combine `entry_source=direct_upload` with `scene_id`. Use `scene_gallery` when sending\na scene id; `scene_gallery` requires one.\n\nUse `POST /v1/headshots/projects/{project_id}/source` with an `image` part to replace\nthe source while preserving the project history. Use `GET /v1/headshots/projects/{id}`\nto restore a project, `GET /v1/headshots/projects` to list projects, and `DELETE` on the\nproject resource to remove it and its private derivatives.\n\n### Inspect the source\n\n`POST /v1/headshots/projects/{project_id}/inspect` returns practical eligibility:\n\n```json\n{\"eligible\": true, \"status\": \"ready\", \"reasons\": [], \"warnings\": []}\n```\n\nStop when `eligible` is false. Surface warnings before creating a preview.\n\nSet the garment catalog preference with\n`POST /v1/headshots/projects/{project_id}/garment-preference`:\n\n```json\n{\"garment_preference\": \"female\"}\n```\n\nThe value is `male`, `female`, or `null` to clear it. This selects catalog variants; it\ndoes not infer or alter gender identity.\n\n### Grade, smooth, and crop the reference preview\n\n`POST /v1/headshots/projects/{project_id}/previews` accepts JSON:\n\n```json\n{\n  \"skin_base_id\": \"motu_business_neutral\",\n  \"smoothing_strength\": 0.2,\n  \"crop_spec_id\": \"profile_4x5\",\n  \"crop_anchor\": \"auto\",\n  \"crop_rotation\": 0\n}\n```\n\n- `skin_base_id` — allowed portrait base style; corrects skin colour and white balance.\n- `smoothing_strength` — `0`–`1`; `0` preserves texture and applies no smoothing.\n- `crop_spec_id` — normally `avatar_1x1`, `profile_4x5`, or `headshot_3x4`.\n- `crop_anchor` — `auto`, `center`, or `manual`.\n- `crop_zoom` — `1`–`2`; used by non-manual crop modes.\n- `crop_offset_x`, `crop_offset_y` — `-1`–`1`.\n- `crop_x`, `crop_y`, `crop_width`, `crop_height` — normalized complete rectangle for a manual crop.\n- `crop_rotation` — `-15`–`15` degrees.\n\nThe response contains `preview_id`, the applied `parameters`, and a private image URL.\nDownload it with `GET /v1/headshots/projects/{project_id}/previews/{preview_id}/image`.\n\nAfter the user approves the downloaded preview, confirm an immutable reference with\n`POST /v1/headshots/projects/{project_id}/references`:\n\n```json\n{\"preview_id\": \"hprev_...\"}\n```\n\nDownload it with\n`GET /v1/headshots/projects/{project_id}/references/{reference_id}/image`.\n\nConfirmation also makes the person available in the owner's reusable person-reference library.\nLibrary deduplication uses the confirmed image content, not crop or skin-preparation parameters.\n\n### Reuse or remove a saved person\n\n- `GET /v1/headshots/person-references?limit=20` lists active library entries.\n- `GET /v1/headshots/person-references/{person_reference_id}/image` downloads a private preview.\n- `POST /v1/headshots/projects/from-person-reference` with\n  `{\"person_reference_id\":\"hperson_...\",\"scene_id\":\"professional_profile\"}` starts a new project.\n- `POST /v1/headshots/projects/{project_id}/person-reference` with\n  `{\"person_reference_id\":\"hperson_...\"}` switches the active person inside the same project.\n- `DELETE /v1/headshots/person-references/{person_reference_id}` soft-deletes only the library entry.\n\nApplying a person to an existing project replaces its future preparation source and appends a new\nimmutable reference version. Historical jobs, candidates, favorites, and references remain intact.\nSoft deletion does not remove library assets or any project data, and history import must not\nrecreate a deleted entry.\n\n## Configure and generate\n\nUse the public catalog or scene endpoint to discover ids. Never invent ids or generation\nprompts. The public API exposes controlled ids and compatibility, not internal prompts.\n\n`POST /v1/headshots/recommendation` validates a partial selection and returns a complete\ncompatible configuration:\n\n```json\n{\n  \"project_id\": \"hproj_...\",\n  \"reference_id\": \"href_...\",\n  \"scene_id\": \"professional_profile\",\n  \"generation_style_id\": null,\n  \"pose_id\": null,\n  \"outfit_id\": null,\n  \"background_id\": null,\n  \"output_ratio\": \"4:5\",\n  \"framing\": \"auto\"\n}\n```\n\nOptional booleans are `hair_grooming_enabled` and `face_refinement_enabled`. Set\n`allow_incompatible=true` only when the user explicitly chooses catalog options outside\nthe scene recommendation.\n\nSubmit the complete returned selection to `POST /v1/headshots/jobs` with an\n`Idempotency-Key` header. `batch_size` is `1`, `2`, or `4`; `output_ratio` is `1:1`,\n`4:5`, or `3:4`. A successful request returns HTTP 202 and a `job_id`.\n\nGeneration is asynchronous. Query `GET /v1/headshots/jobs/{job_id}`. Terminal states include\n`completed`, `partially_completed`, `failed`, and `cancelled`; do not repeatedly submit a\nreplacement job while one is queued or running. A partially completed job may still contain\nbillable ready candidates, so surface `failure_reason` and retain every successful result.\nCandidate entries contain `candidate_id`, `ordinal`, `status`, and an\n`image_url` when ready. Download each private URL with the same API key.\n\nSelect a candidate with `POST /v1/headshots/jobs/{job_id}/selection` and\n`{\"candidate_id\":\"hcand_...\"}`. Favorites are available under\n`/v1/headshots/projects/{project_id}/favorites`.\n\n## Post-process\n\nList styles with:\n\n```http\nGET /v1/headshots/postprocess/styles?reference_id={reference_id}&locale=en\n```\n\nEach style maps a public style id to `base_id` and an optional `flavour_id`. Create a\nrender with `POST /v1/headshots/candidates/{candidate_id}/renders`:\n\n```json\n{\"base_id\": \"motu_business_neutral\", \"flavour_id\": null}\n```\n\nDownload `GET /v1/headshots/renders/{render_id}/image`.\n\nCreate an immutable portrait-lighting Render directly from the Candidate master:\n\n```json\n{\n  \"render_kind\": \"portrait_lighting\",\n  \"lighting_style\": \"natural_dimension\",\n  \"lighting_strength\": 0.70\n}\n```\n\nTo apply lighting after an existing grade, include that grade's explicit\n`\"source_render_id\": \"hrender_...\"`. The response identifies `render_kind`,\n`source_render_id`, `lighting_style`, and the resolved `lighting_strength`. The Candidate\nmaster and every earlier Render remain unchanged; repeated identical requests reuse the\nsame cached Render.\n\nFor the preferred single-pass Headshots workflow, send the approved grade selection\nin the same request instead of `source_render_id`:\n\n```json\n{\n  \"render_kind\": \"portrait_lighting\",\n  \"base_id\": \"motu_business_neutral\",\n  \"flavour_id\": null,\n  \"lighting_style\": \"natural_dimension\",\n  \"lighting_strength\": 0.70\n}\n```\n\nThis runs grading and portrait lighting in one pipeline decode/parse/render pass and\ncreates one immutable output Render from the Candidate master.\n\n## Export\n\nCreate a controlled crop with `POST /v1/headshots/candidates/{candidate_id}/exports`:\n\n```json\n{\n  \"source_type\": \"master\",\n  \"crop_spec_id\": \"profile_4x5\",\n  \"format\": \"jpeg\",\n  \"quality\": 92\n}\n```\n\nUse `source_type=\"render\"` plus the explicit `render_id` to export a post-processed\nversion. Supported crop specs include `avatar_1x1`, `profile_4x5`, `headshot_3x4`,\n`bust_3x4`, `half_body_2x3`, `three_quarter_2x3`, `full_body_9x16`, and `banner_16x9`.\nFormats are `jpeg`, `png`, and `webp`; quality is `70`–`100`.\n\nOptional automatic adjustments are `offset_x` and `offset_y` from `-0.15` to `0.15`.\nA manual crop requires the complete normalized rectangle and may include\n`crop_rotation` from `-15` to `15`.\n\nDownload the returned `download_url`. Exports are immutable and tied to their explicit\ncandidate or render source.\n\n## Errors and credits\n\n- `400` — invalid transition, ids, compatibility, or parameters.\n- `401` — missing or invalid session/API key.\n- `402` — insufficient credits; do not retry unchanged.\n- `403` — missing `headshot:process` or a non-user-bound service key.\n- `404` — missing resource or owner mismatch.\n- `409` — conflicting or duplicate state transition when applicable.\n- `413` / `415` — invalid upload size or type.\n- `503` — Headshots storage, worker, catalog, or post-processing is unavailable.\n\nPreserve `Idempotency-Key` for a generation retry after an uncertain network response.\nSurface provider or moderation failure details from the job instead of returning an old\ncandidate as if it were new.\n\nFile v1.0.9:references/styles.md\n\n# MotuArt Color Engine — styles overview\n\nThe live catalog is authoritative — run `scripts/styles.sh` to list current ids.\nThis is a quick orientation to the two style tiers and the shipping looks.\n\n## Two tiers\n\n- **base** — a skin-tone target (the anchor the engine grades skin toward).\n  Pick one as the foundation. Default: `motu_korean_id`.\n- **flavour** — a look/grade layered on top (film, clean, teal, etc.).\n  Optional. Combine with a base using the composite separator (default `@`):\n  `<flavour>@<base>`, e.g. `kodak_gold@motu_korean_id`.\n\nPassing only a base gives clean skin-tone correction with no stylization.\n\n## Shipping looks (flavours)\n\n| Look | When to use |\n| --- | --- |\n| Leica Classic | Neutral, true-to-life editorial; restrained contrast. |\n| Kodak Gold | Warm nostalgic film; golden skin, cozy mood. |\n| Clean Cool | Crisp, cool, commercial/e-commerce clarity. |\n| Cine Teal | Cinematic teal shadows; moody outdoor/urban. |\n| Milk Tea | Soft warm beige; lifestyle, gentle portraits. |\n| JP Airy | Bright, airy, low-contrast Japanese style. |\n\nStyle ids differ from display names — always resolve the exact id via\n`scripts/styles.sh` before calling `grade.sh`.\n\n## Strength\n\n`strength` scales the look (default `1.0`). Use `0` to disable stylization (base\ncorrection only), and up to ~`1.5` for a stronger grade. Report `skin_dE` from the\nresult so the user can judge accuracy.\n\nFile v1.0.9:skill-card.md\n\n## Description:\n\nMotuArt Color Engine helps agents call the hosted MotuArt Color Engine API for identity-preserving portrait grading, skin smoothing, segmentation masks, approved outfit replacement, AI headshots, ID/passport crops, compliance checks, upload optimization, and print sheets.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[chancipher](https://clawhub.ai/user/chancipher)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to prepare portrait and identity-photo deliverables through the MotuArt Color Engine API, including graded portraits, masks, approved outfit changes, AI headshot candidates, ID/passport crops, compliance reports, upload-ready images, and print sheets.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Sensitive portrait, passport, ID, and reusable headshot reference images may be sent to an environment-selected API server along with an API key.\n\nMitigation: Use a least-privilege MCE_API_KEY, keep MCE_API_BASE unset or restricted to the official HTTPS service unless intentionally using a separate trusted deployment, and avoid pasting full keys into chat or client code.\n\nRisk: Some API-controlled filenames are not safely contained according to the server security evidence.\n\nMitigation: Run outputs in a dedicated directory and review generated files before reusing or publishing them, especially for headshot candidate downloads and ID-photo packages.\n\nRisk: Processing calls consume account credits and failed credit checks should not be retried unchanged.\n\nMitigation: Use catalog discovery before processing where possible, surface 402 insufficient_credits responses to the user, and do not retry the same paid request without a user decision.\n\n## Reference(s):\n\n- [MotuArt Color Engine Skill Page](https://clawhub.ai/chancipher/skills/motu-color-engine)\n- [MotuArt Developer Homepage](https://mce.motu.art/developers)\n- [MotuArt Color Engine API Reference](references/api.md)\n- [Headshots API Reference](references/headshots-api.md)\n- [Crop Specs Reference](references/crop-specs.md)\n- [Styles Reference](references/styles.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files]\n\n**Output Format:** [Markdown guidance with bash commands and references to generated image or report files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May create PNG, JPEG, WebP, and JSON report files through API-backed scripts; processing requires scoped API credentials and may consume credits.]\n\n## Skill Version(s):\n\n1.0.9 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.9:.claude-plugin/plugin.json\n\n{\n  \"name\": \"motu-color-engine\",\n  \"description\": \"AI portrait color grading, pro skin smoothing, segmentation masks, ID/passport crop generation, compliance checks, upload optimization, and print-sheet packaging via the MotuArt Color Engine API.\",\n  \"version\": \"1.1.0\",\n  \"author\": {\n    \"name\": \"MotuArt\",\n    \"email\": \"hi@motu.art\"\n  },\n  \"homepage\": \"https://mce.motu.art/developers\",\n  \"license\": \"MIT\"\n}\n\nFile v1.0.9:agents/openai.yaml\n\ninterface:\n  display_name: \"MotuArt Color Engine\"\n  short_description: \"Portrait grading, AI headshots, outfits, masks, and ID photos\"\n  icon_small: \"./assets/motu-color-engine-logo.svg\"\n  icon_large: \"./assets/motu-color-engine-logo.png\"\n  brand_color: \"#F2542D\"\n  default_prompt: \"Use $motu-color-engine to preserve identity and produce the requested portrait grade, AI headshot, approved outfit, mask, or ID photo.\"\n\npolicy:\n  allow_implicit_invocation: true\n\nArchive v1.0.7: 24 files, 56566 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (462b), assets/motu-color-engine-logo.png (20946b), assets/motu-color-engine-logo.svg (2208b), references/api.md (10608b), references/crop-specs.md (4420b), references/headshots-api.md (7225b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/headshots.sh (17274b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3981b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/outfit.sh (1361b), scripts/outfits.sh (1149b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (3324b), SKILL.md (14497b), _meta.json (136b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: motu-color-engine\ndescription: AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, exporting mattes, replacing clothing, preparing identity references and generating professional headshot candidates, cropping to ID/passport/visa specs, replacing ID-photo backgrounds, checking compliance, optimizing uploads, or creating print sheets. Triggers include portrait grading, skin tone, retouch, skin mask, outfit replacement, AI headshots, professional headshot, business portrait, corporate portrait, LinkedIn photo, ID photo, passport photo, visa photo, background swap, print sheet, 调色, 肤色, 磨皮, 蒙版, 人像调色, AI形象照, 职业形象照, 商务形象照, 企业头像, 换装, 证件照, 裁剪, 换底, 合规检查, 排版, 一寸, 二寸.\n---\n\n# Motu Color Engine\n\nUse Motu Color Engine to process portrait images through the hosted HTTP API. Prefer the bundled scripts in `scripts/` over hand-written `curl` calls unless the user explicitly needs raw API details.\n\nThe engine preserves identity. Do not describe it as slimming, reshaping, face swapping, or changing facial structure. Skin smoothing only softens pores and blemishes inside detected skin regions. Cropping repositions and pads to a spec; it never stretches or compresses the face.\n\n## Setup\n\n- Require `curl` and `python3`.\n- Read `MCE_API_BASE` from the environment; default is `https://mce.motu.art`.\n- Read `MCE_API_KEY` from the environment; send it only as `X-API-Key`.\n- If the key is missing, direct the user to `https://mce.motu.art/account` (English: `/en/account`) to sign in by email and create one. Ask them to export it securely in their own environment; do not ask them to paste the full key into chat.\n- Never hard-code, print, log, commit, or expose API keys in browser/client code. The full key is shown once and can be rotated or revoked from the account page.\n- Request only the scopes needed: `catalog:read` for portrait/ID discovery, `portrait:process` for grading/smoothing/masks, `id-photo:process` for ID-photo workflows, `outfit:process` for outfit replacement, and `headshot:process` for private AI Headshots projects and generation. An ID package with an outfit needs both `id-photo:process` and `outfit:process`.\n- Processing calls consume account credits; catalog discovery does not. Surface `402 insufficient_credits` instead of retrying.\n- Check service health with `curl -sS \"${MCE_API_BASE:-https://mce.motu.art}/v1/health\"` when diagnosing connectivity.\n\n## Choose The Workflow\n\n- Use `scripts/grade.sh` when the user wants color grading, skin-tone correction, a film/commercial look, or grading plus optional crop.\n- Use `scripts/smooth.sh` when the user wants smoothing only with no color or white-balance change.\n- Use `scripts/mask.sh` when the user wants a skin, valid-skin, face, or person mask/matte.\n- Use `scripts/crop.sh` when the user wants crop-only ID/passport/visa/headshot/avatar output, optionally with a solid background color.\n- Use `scripts/outfit.sh` when the user wants clothing replacement only. The outfit id must come from the approved catalog; never accept or invent a custom prompt or outfit id.\n- Use `scripts/outfits.sh` before clothing replacement to discover currently enabled outfit ids. Do not infer an id from a garment name.\n- Use `scripts/id-pack.sh` when the user wants a complete ID/passport photo delivery package: one graded/smoothed master, multiple specs, upload-ready files, compliance report, and optional print sheets.\n- Use `scripts/id-check.sh` when the user wants to validate an ID photo against a spec or understand compliance warnings.\n- Use `scripts/optimize.sh` when the user needs a website/upload-ready file with format, pixel size, DPI, or maximum KB constraints.\n- Use `scripts/print-sheet.sh` when the user wants cropped ID photos laid out on photo paper for printing.\n- Use `scripts/headshots.sh` when the user wants AI-generated professional, business, corporate, LinkedIn, or studio headshots. Keep reference preparation, confirmation, generation, candidate download, post-processing, and export as explicit stages; do not turn them into one automatic operation.\n- Use `scripts/styles.sh` to discover live style ids. Read `references/styles.md` only when the user needs style-selection guidance or offline context.\n- Use `scripts/crop-specs.sh` to discover live crop specs. Read `references/crop-specs.md` only when choosing specs or background palettes without live discovery.\n- Read `references/api.md` for endpoint parameters, response fields, headers, limits, and error codes.\n- Read `references/headshots-api.md` before operating the AI Headshots workflow or when the user needs its raw API details.\n\n## Grade Portraits\n\n```bash\nscripts/grade.sh <input-image> <output-image> [style-id] [strength] [smooth-strength] [smooth-texture-retain] [crop-spec] [bg-color] [pad-color]\n```\n\n- Omit `style-id` for the default skin base, or choose a style from `scripts/styles.sh`.\n- Use `strength` for look intensity; default is `1.0`, `0` disables the look, and values up to about `1.5` are stronger.\n- Pass `smooth-strength` from `0` to `1` only when the user asks for softened pores or blemishes. Omit it, or pass `0`, to preserve natural texture.\n- Use `smooth-texture-retain` from `0` to `1` to keep natural texture over smoothing; default is `0.35`.\n- Pass `crop-spec` when the same output should be graded and cropped in one API call.\n- Pass `bg-color` only with `crop-spec`; use an allowed palette name such as `white`, `blue`, or `red`, `default`, or explicit `#RRGGBB`.\n- Pass `pad-color` only with `crop-spec` when a specific padding color is needed; otherwise let the API edge-replicate.\n- Report `skin_dE` from script output when summarizing quality; lower means closer skin color to the target.\n\nFor a folder, run the script once per image. Keep batch loops serial unless the user asks for parallelism and accepts API/load implications.\n\n## Smooth Skin Only\n\n```bash\nscripts/smooth.sh <input-image> <output.png> [strength] [texture-retain]\n```\n\n- Use this for pore/blemish softening without style, color, or white-balance changes.\n- Default `strength` is `0.6`.\n- Default `texture-retain` is `0.35`; raise it to preserve more natural texture.\n\n## Export Masks\n\n```bash\nscripts/mask.sh <input-image> <output.png> [mask-kind]\n```\n\n- Use `skin` by default.\n- Other mask kinds are `valid_skin`, `face`, and `person`.\n- Output is an 8-bit grayscale PNG aligned to the input.\n\n## Crop ID Or Portrait Photos\n\n```bash\nscripts/crop.sh <input-image> <output-image> [spec-id] [bg-color] [pad-color]\n```\n\n- Default `spec-id` is `one_inch`.\n- Use `scripts/crop-specs.sh` to list supported specs and allowed background colors.\n- Use `bg-color` only when the spec declares a background palette, mostly ID-photo specs.\n- Use `pad-color` only when a source image lacks required margins and the user wants a specific fill.\n- Surface crop warnings from script output, especially warnings about margins, resolution, or background limitations.\n- Use `grade.sh` with crop arguments when the user wants grading and crop in one output.\n\n## Make ID Photo Packages\n\n```bash\nscripts/id-pack.sh <input-image> <output-dir> [specs] [style-id] [smooth-strength] [bg-color] [upload] [print-sheet] [outfit-id] [outfit-long-edge]\n```\n\n- Use this for passport/visa/ID-photo deliverables rather than calling `grade.sh` once per spec. The API generates one graded/smoothed master first, then crops multiple specs from that master so colour and retouching stay consistent.\n- `specs` is comma-separated, e.g. `passport_cn,one_inch,us_visa`; default is `passport_cn`. School/enrollment specs include `shanghai_compulsory_education_cn`, `college_graduation_image_cn`, and `national_k12_student_status_cn`.\n- Default style is `motu_business_neutral`; pass `smooth-strength` from `0` to `1` only when the user asks for smoothing.\n- `bg-color` defaults to `default`, which applies each spec's standard background palette. Use `white`, `blue`, `light_blue`, `red`, or `#RRGGBB` when the user asks and the spec allows it.\n- `upload` defaults to `true`, writing upload-optimized JPG files using the spec's `upload` rules from `crop_specs.json`.\n- `print-sheet` is optional, e.g. `6x4` or `a4`; when specs have different sizes, separate sheets may be generated.\n- `outfit-id` is optional. When present, it must be an id returned by `scripts/outfits.sh`; omitted keeps the original clothing.\n- `outfit-long-edge` controls the upstream outfit result size, defaults to 1536, and is bounded by the service to 512–2048px.\n- Output folder contains `master.png`, `single/`, `upload/`, `print/`, and `report.json`. Surface compliance status and warnings from the report.\n- When the user requests a supported outfit, pass its approved catalog id. Outfit replacement runs before the corrected master is generated, so all crop specs share the same clothing result.\n\n## Replace Clothing Only\n\nDiscover the approved catalog first:\n\n```bash\nscripts/outfits.sh\n```\n\nSelect only an id returned by that command, then replace clothing:\n\n```bash\nscripts/outfit.sh <input-image> <output.png> <approved-outfit-id> [long-edge]\n```\n\n- Only use ids returned by `GET /v1/outfits`; the API maps each approved id to its controlled generation prompt and rejects custom prompts or arbitrary ids.\n- The catalog groups styles as `male`, `female`, `kids`, or `unisex`; use the category and localized name/description to help select a suitable style.\n- If the requested clothing is absent, explain that only catalog styles are available; do not substitute a custom prompt, URL, or upload.\n- The service protects the detected facial oval with the face mask and calls the configured Motu asynchronous workflow.\n- Default output long edge is 1536px; the service bounds requests to 512–2048px.\n- Clothing generation must preserve the face and identity. Report upstream failures or timeouts instead of silently returning the original image.\n\n## Create AI Headshots\n\nUse one work directory for the whole staged workflow. The script stores non-secret ids,\nresponses, and configuration in `headshots.json`; it never stores `MCE_API_KEY`.\n\nDiscover current options:\n\n```bash\nscripts/headshots.sh catalog [locale]\n```\n\nPrepare a graded, optionally smoothed, purpose-cropped identity reference:\n\n```bash\nscripts/headshots.sh prepare <input-image> <work-dir> \\\n  [--scene ID] [--garment male|female] [--skin-base ID] [--smoothing 0..1] \\\n  [--crop-spec ID] [--crop-anchor auto|center|manual] \\\n  [--crop-rect X,Y,W,H] [--rotation DEG]\n```\n\n- Inspect `source-check.json` and `reference-preview.png` before continuing.\n- Surface ineligible reasons and warnings. Do not submit generation for an ineligible source.\n- `skin-base` performs colour/skin-tone preparation; `smoothing=0` preserves natural texture.\n- Use an automatic crop unless the user provides a complete normalized manual rectangle.\n- Never confirm the reference without the user approving the preview.\n\nAfter approval, freeze that preview as the identity reference:\n\n```bash\nscripts/headshots.sh confirm <work-dir>\n```\n\nSubmit a compatible generation plan without waiting for the asynchronous worker:\n\n```bash\nscripts/headshots.sh generate <work-dir> [--scene ID] [--batch-size 1|2|4] \\\n  [--style ID] [--pose ID] [--outfit ID] [--background ID] \\\n  [--ratio 1:1|4:5|3:4] [--framing auto|close_up|half_body|three_quarter]\n```\n\n- Let the recommendation endpoint fill omitted options and correct incompatible defaults.\n- Use only ids returned by the live Headshots catalog. Never send custom generation prompts.\n- Generation consumes credits per requested image. Surface `402` and do not retry unchanged.\n- The command submits one job and returns; it does not hide asynchronous work behind a long synchronous call.\n\nCheck and download results explicitly:\n\n```bash\nscripts/headshots.sh status <work-dir>\nscripts/headshots.sh download <work-dir>\n```\n\nDownload only after the job is `completed`. Show all candidates rather than silently selecting one.\n\nPost-process a user-selected candidate and optionally export that render:\n\n```bash\nscripts/headshots.sh render <work-dir> --candidate ID-or-ordinal --style ID [--locale LOCALE]\nscripts/headshots.sh export <work-dir> --candidate ID-or-ordinal [--render] \\\n  [--crop SPEC] [--format jpeg|png|webp] [--quality 70..100]\n```\n\n- Require an explicit candidate id or ordinal.\n- Without `--render`, export the generated master candidate. With `--render`, use the latest explicit render saved in the work directory.\n- Keep `project_id`, `reference_id`, `job_id`, and derivative ids so an interrupted workflow can resume.\n\n## Check ID Photo Compliance\n\n```bash\nscripts/id-check.sh <input-image> [spec-id] [report-json]\n```\n\n- Without `report-json`, the input is treated as a source portrait: the API crop-checks it against the spec and reports practical compliance.\n- With `report-json`, the input is treated as the already-cropped ID photo and the supplied crop metrics are checked.\n- Report failures and warnings plainly; this is a practical QA check, not a government guarantee.\n\n## Optimize Upload Files\n\n```bash\nscripts/optimize.sh <input-image> <output-image> [format] [max-kb] [quality] [resize] [dpi]\n```\n\n- Use for official website upload limits such as JPG under a maximum KB, exact pixel dimensions, or DPI metadata.\n- `format` is `jpg`, `png`, or `webp`; `resize` is `WIDTHxHEIGHT`; lossy formats search quality down to the server default floor when `max-kb` is set.\n\n## Make Print Sheets\n\n```bash\nscripts/print-sheet.sh <output-image> <paper> <input1> [input2 ...]\n```\n\n- Use after generating cropped ID photos when the user wants a printable sheet.\n- `paper` supports common values such as `6x4`, `4x6`, `5x7`, and `a4`. Inputs on a single sheet must have the same pixel size; use `id-pack.sh` for automatic grouping by size.\n\n## Constraints To Surface\n\n- Upload limit is about 15 MB per image.\n- Supported upload formats are JPG, PNG, and WebP.\n- Processing is synchronous; batch jobs are repeated one-image calls.\n- Background replacement is limited to specs that declare `bg_colors`.\n- If a script fails, read its HTTP status and error detail before deciding whether to retry, change arguments, or ask the user for configuration.\n\nFile v1.0.7:_meta.json\n\n{\n  \"ownerId\": \"kn7b98pvjtsm6a4bw8gd87ttbs8a3ycc\",\n  \"slug\": \"motu-color-engine\",\n  \"version\": \"1.0.7\",\n  \"publishedAt\": 1785678218288\n}\n\nFile v1.0.7:references/api.md\n\n# MotuArt Color Engine — API reference\n\nBase URL: `$MCE_API_BASE` (default `https://mce.motu.art`).\nAuth: create a key at `https://mce.motu.art/account` (English: `/en/account`), then send\n`X-API-Key: $MCE_API_KEY` (or `Authorization: Bearer $MCE_API_KEY`) on private and\nprocessing endpoints. `/v1/health` and public Headshots discovery endpoints do not need\na key. The full key is displayed once; store it securely and rotate or revoke it from\nthe account page if exposed.\n\nScopes:\n- `catalog:read` — styles, crop specs and approved outfits.\n- `portrait:process` — process, smooth and mask.\n- `id-photo:process` — crop, id-pack, id-check, optimize and print-sheet.\n- `outfit:process` — standalone outfit replacement. Also required in addition to\n  `id-photo:process` or `portrait:process` when those requests include `outfit_id`.\n- `headshot:process` — private AI Headshots projects, reference preparation,\n  generation, candidates, post-processing, and exports. See `headshots-api.md`.\n\nSuccessful processing calls consume account credits; catalog requests do not. A `402`\nresponse uses `detail.code=\"insufficient_credits\"` and includes `required`, `available`,\nand whether the request included outfit replacement.\n\n## GET /v1/health\nLiveness/version. No key required.\n\n## GET /v1/styles\nReturns `{ styles: [{id, name, kind, name_zh, ...}], composite_separator, bases, flavours }`.\n`kind` is `base` or `flavour`. Combine as `<flavour><composite_separator><base>`\n(default separator `@`), e.g. `kodak_gold@motu_korean_id`.\n\n## POST /v1/process  (multipart/form-data)\nGrade an image. Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `style` — style id (default `motu_korean_id`).\n- `strength` — look intensity, default `1.0` (0–~1.5).\n- `smooth_strength` — optional M15 pro skin smoothing, `0`–`1`. Omitted/`0` leaves skin\n  texture untouched (default). Softens pores/blemishes only; never reshapes the face.\n- `smooth_texture_retain` — optional, `0`–`1` (default `0.35`), how much natural\n  texture to keep on top of the smoothing. Only used when `smooth_strength` > 0.\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n- `max_long_edge` — cap working long edge (default 1024; server ceiling applies).\n- `mask` — `true` to also return a mask inline (base64).\n- `mask_kind` — mask type when `mask=true` (see below).\n- `crop_spec` — optional M16 purpose crop spec id (see `GET /v1/crop/specs`). When set,\n  the graded output is additionally cropped to that spec (grade + crop in one call).\n  Omitted — full graded frame, uncropped.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin; only used with `crop_spec`. Omitted — edge-replicate padding (the default).\n- `bg_color` — optional background replacement (换底), only used with `crop_spec`: a\n  palette name the spec allows (e.g. `white`/`blue`/`red`), `default` for the spec's\n  standard color, or an explicit `#RRGGBB`. Omitted — original background kept.\n\nResponse JSON:\n```\n{ \"trace_id\", \"style_id\", \"image_base64\", \"content_type\",\n  \"processing_time_ms\", \"quality\": { \"skin_delta_e_to_target\", \"warnings\" },\n  \"report_url\", \"compare_base64\",\n  \"mask_base64\", \"mask_kind\", \"mask_content_type\" }   // mask_* only when mask=true\n```\nDecode `image_base64` to bytes to get the graded image. `skin_delta_e_to_target`\nis the skin ΔE to the target skin (lower = closer).\n\n## POST /v1/mask  (multipart/form-data)\nSegmentation only (decode + parse; **skips grading/render/score** — faster). Fields:\n- `file` (required).\n- `mask_kind` — `skin` (default) | `valid_skin` | `face` | `person`.\n- `max_long_edge` — optional.\n\nReturns the mask as a raw **grayscale PNG** (`Content-Type: image/png`), with header\n`X-MCE-Mask-Kind`. Save the response body directly.\n\n## POST /v1/smooth  (multipart/form-data)\nStandalone M15 pro skin smoothing — runs decode + parse + smoothing + render only,\n**skipping the entire color-grading stack**. Softens pores/blemishes on the detected\nskin region; never reshapes the face or changes color. Fields:\n- `file` (required).\n- `strength` — smoothing amount, default `0.6`.\n- `texture_retain` — how much natural texture to keep, default `0.35`.\n- `radius_frac` — optional blur radius override (fraction of face size).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the smoothed image as a raw payload (default `image/png`), like `/v1/mask`.\n\n## GET /v1/crop/specs\nList the available purpose-crop specs (证件照/形象照/头像 standards). Returns\n`{ specs: [{id, name, name_zh, category, width_px, height_px, width_mm, height_mm,\ndpi, head_ratio, bg_colors, default_bg, description_zh}] }`.\n- `category` — `id_photo` | `portrait` | `avatar`.\n- `width_mm`/`height_mm`/`dpi` — physical print size; `null` for portrait/avatar specs\n  (pixel-only, no print standard).\n- `bg_colors` — `{name: \"#RRGGBB\"}` palette the spec allows for background\n  replacement; `{}` when the spec does not standardize a background (most\n  portrait/avatar specs). `default_bg` is the palette name applied when a caller\n  requests `bg_color=\"default\"`.\n- See `references/crop-specs.md` for a curated overview of the shipped specs.\n\n## POST /v1/crop  (multipart/form-data)\nStandalone M16 purpose-crop. Runs decode + face/head geometry + crop **only** — no\nhuman parsing, no color grading (use `/v1/process` with `crop_spec` to grade and crop\ntogether). Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `spec` — crop spec id (default `one_inch`); see `GET /v1/crop/specs`.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin. Omitted — edge-replicate padding.\n- `bg_color` — optional background replacement (换底): a palette name the spec\n  allows, `default` for the spec's standard color, or an explicit `#RRGGBB`. Omitted —\n  original background kept.\n- `max_long_edge` — optional working-resolution cap; `0`/omitted means **full source\n  resolution** (crop quality is bounded by source resolution, not a latency budget —\n  unlike `/v1/process`, which defaults to 1024).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the cropped image as a raw payload (default `image/png`, with the spec's DPI\nembedded), like `/v1/mask`/`/v1/smooth`. The achieved geometry and any warnings are in\nthe `X-MCE-Crop-Info` response header (JSON), alongside `X-MCE-Trace-Id`.\n\n## POST /v1/id-pack  (multipart/form-data)\nGenerate a complete ID-photo delivery package. The service creates one graded/smoothed\nmaster, detects face/head geometry once, then crops multiple specs from that master.\nFields:\n- `file` (required) — image upload.\n- `specs` (required) — comma-separated crop spec ids, e.g. `passport_cn,one_inch`.\n- `style` — style id (default `motu_korean_id`).\n- `smooth_strength`, `smooth_texture_retain` — optional skin smoothing.\n- `strength`, `output_space`, `max_long_edge` — same meaning as `/v1/process`.\n- `bg_color` — `default` (recommended for ID photos), palette name, or `#RRGGBB`.\n- `pad_color` — optional padding colour.\n- `output_format` — `png` (default) | `jpeg` | `webp` for single-spec files.\n- `quality` — output quality for lossy formats.\n- `upload` — `true` to include upload-optimized files using spec `upload` rules.\n- `print_sheet` — optional paper id such as `6x4`/`a4`; groups same-size photos.\n\nResponse JSON includes `trace_id`, `style_id`, `master_base64`, `items[]` with\n`image_base64`, `crop_info`, `compliance`, optional `upload.image_base64`, optional\n`print_sheets[].image_base64`, and the master quality report.\n\nOptional outfit fields:\n- `outfit_id` — approved id returned by `GET /v1/outfits`; omitted keeps the original clothing.\n- `outfit_long_edge` — upstream generation long edge, bounded to 512–2048; default 1536.\n\n## GET /v1/outfits\nReturns the approved outfit catalog. Each item includes `id`, localized names and\ndescriptions, `category` (`male`/`female`/`kids`/`unisex`), `order`, `available`, and\noptional `preview_url`. `available` mirrors the catalog's `enabled` switch. The\ncontrolled `generation_prompt` used by the workflow is never exposed.\n\n## POST /v1/outfit  (multipart/form-data)\nControlled standalone clothing replacement. Fields:\n- `file` (required) — source JPG, PNG, or WebP.\n- `outfit_id` (required) — approved catalog id. Custom prompts and arbitrary ids are rejected.\n- `long_edge` — requested generation long edge, bounded to 512–2048; default 1536.\n\nResponse JSON contains `task_id`, `outfit_id`, `image_base64`, `content_type`,\n`long_edge`, and `processing_time_ms`. MCE resolves the id to its controlled\n`generation_prompt`, then submits the source, prompt, face mask, and long edge to the\nconfigured asynchronous Motu workflow and polls it.\n\n## POST /v1/id-check  (multipart/form-data)\nCheck an ID photo against a crop spec. Fields:\n- `file` (required) — source portrait, or already-cropped ID photo when `report_json` is supplied.\n- `spec` (required) — crop spec id.\n- `report_json` — optional crop report containing `metrics.crop`; use this when checking an already-cropped output.\n- `bg_color` — optional background for the temporary crop-check path (default `default`).\n\nResponse JSON: `{ ok, status, checks, warnings, errors }`. This is practical QA, not\na government acceptance guarantee.\n\n## POST /v1/optimize  (multipart/form-data)\nExport an upload-ready file. Fields:\n- `file` (required).\n- `output_format` — `jpg`/`jpeg` (default), `png`, or `webp`.\n- `max_kb` — optional maximum file size in KB.\n- `quality`, `min_quality` — lossy encoder quality range.\n- `resize` — optional `WIDTHxHEIGHT`.\n- `dpi` — optional DPI metadata.\n\nReturns the optimized image as a raw payload. Metadata is in `X-MCE-Export-Info`.\n\n## POST /v1/print-sheet  (multipart/form-data)\nLayout one or more same-size ID photos on paper. Fields:\n- `files` — one or more image uploads.\n- `paper` — `6x4` (default), `4x6`, `5x7`, `7x5`, `a4`, or `WIDTHxHEIGHTin`.\n- `dpi`, `margin_mm`, `gap_mm`, `cut_lines`, `output_format`.\n\nReturns the print sheet as a raw image payload. Metadata is in `X-MCE-Print-Sheet-Info`.\n\n## Errors\n- `400` bad params / empty upload · `401` missing/invalid key ·\n  `413` too large · `415` unsupported content-type · `422` processing/segmentation failed.\nError bodies are JSON `{ \"detail\": \"...\" }`.\n\nFile v1.0.7:references/crop-specs.md\n\n# MotuArt Color Engine — crop specs overview (M16 purpose crop)\n\nThe live catalog is authoritative — run `scripts/crop-specs.sh` (or `GET\n/v1/crop/specs`) to list current ids/sizes. This is a quick orientation to the\nthree categories and the shipping specs.\n\n## Three categories\n\n- **id_photo** — official ID/passport/visa/license photo standards. Fixed pixel size\n  + physical `width_mm`/`height_mm` + `dpi` (embedded on save, so exports print at the\n  right physical size). Most declare a `bg_colors` palette for background replacement\n  (换底) since these documents require a specific solid background. ID-photo specs may\n  also include `compliance`, `upload`, and `print` metadata used by `id-pack`,\n  `id-check`, upload optimization, and print-sheet layout.\n- **portrait** — professional/editorial portrait framings (headshot to full body).\n  Pixel-only, no print standard, no background palette (original background kept).\n- **avatar** — square social-avatar framing. Pixel-only, no background palette.\n\nPass only a `spec` id — the engine auto-detects the face/head and positions it to\nthat spec's `head_ratio` (crown-to-chin as a fraction of output height) and margins;\nyou never draw a crop box by hand.\n\n## id_photo specs (fixed background palette, mostly white/blue/red)\n\n| id | Use | Size | Print |\n| --- | --- | --- | --- |\n| `one_inch` | 简历/证件 general 1-inch | 295×413px | 25×35mm@300dpi |\n| `two_inch` | Standard 2-inch | 413×579px | 35×49mm@300dpi |\n| `small_two_inch` | Small 2-inch (passport/visa common) | 413×531px | 35×45mm@300dpi |\n| `small_one_inch` | Driver's license / some certificates | 260×378px | 22×32mm@300dpi |\n| `big_two_inch` | Diploma (blue background common) | 413×626px | 35×53mm@300dpi |\n| `id_card_cn` | CN ID card / social security card (GA 461) | 358×441px | 26×32mm@350dpi |\n| `shanghai_compulsory_education_cn` | 上海义务教育入学免冠证件照 | 272×354px | 20×26mm@350dpi |\n| `college_graduation_image_cn` | 大学生毕业图像信息采集免冠证件照 | 480×640px | 41×54mm@300dpi |\n| `national_k12_student_status_cn` | 全国中小学生学籍电子版照片 | 358×441px | 26×32mm@350dpi |\n| `passport_cn` | CN passport / HK-Macau-Taiwan permit / CN visa | 390×567px | 33×48mm@300dpi |\n| `us_visa` | US visa 2×2 | 600×600px | 51×51mm@300dpi |\n| `schengen_visa` | Schengen/UK visa | 413×531px | 35×45mm@300dpi |\n| `japan_visa` | Japan visa | 531×531px | 45×45mm@300dpi |\n| `canada_visa` | Canada visa/immigration | 590×826px | 50×70mm@300dpi |\n\n## portrait specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `headshot_3x4` | Close face headshot (actor/streamer/résumé) | 900×1200px | 0.55 |\n| `profile_4x5` | Professional headshot (LinkedIn/website/business card) | 1200×1500px | 0.42 |\n| `bust_3x4` | Chest-up bust portrait (team page/instructor bio) | 1200×1600px | 0.33 |\n| `half_body_2x3` | Waist-up half body (magazine-style, needs waist+ in source) | 1200×1800px | 0.26 |\n| `three_quarter_2x3` | Knee-up three-quarter body (needs knee+ in source) | 1200×1800px | 0.19 |\n| `full_body_9x16` | Full body, vertical poster/social (needs full body in source) | 1080×1920px | 0.13 |\n| `banner_16x9` | Wide head-and-shoulders banner (website/video cover) | 1920×1080px | 0.45 |\n\n## avatar specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `avatar_1x1` | Square social avatar (WeChat/DingTalk/general) | 800×800px | 0.45 |\n\n## Background replacement (换底)\n\nOnly `id_photo` specs declare a `bg_colors` palette (e.g. `{\"white\": \"#FFFFFF\",\n\"blue\": \"#438EDB\", \"light_blue\": \"#D6EAF8\", \"red\": \"#FF0000\"}` for the CN sizes). Pass a palette name, `default`\n(the spec's standard choice), or an explicit `#RRGGBB` as `bg_color` — an\nunrecognized name is rejected (the palette *is* the compliance rule for these\ndocuments). Background swap runs a portrait-matting pass on the crop window at source\nresolution, so hair/ear edges stay clean (no crude-cutout fringe).\n\n## Framing guarantee\n\nCropping only repositions the frame (head ratio + margins) — it never stretches or\ncompresses facial proportions. Wide framings (`half_body_2x3`, `three_quarter_2x3`,\n`full_body_9x16`) require the source photo to actually contain that much of the body;\nthe engine pads (edge-replicate or `pad_color`) rather than invent missing content.\n\nFile v1.0.7:references/headshots-api.md\n\n# AI Headshots API\n\nUse this reference for the staged professional-headshot workflow. Use\n`scripts/headshots.sh` for normal operation instead of assembling requests manually.\n\n## Authentication and ownership\n\nSend an account API key with the `headshot:process` scope:\n\n```http\nX-API-Key: $MCE_API_KEY\n```\n\n`Authorization: Bearer $MCE_API_KEY` is also accepted. The account user becomes the\nowner of every project and private asset. Another account receives a not-found response\ninstead of access to that data. Server environment keys are not sufficient without a\nuser identity.\n\nThese discovery endpoints are public:\n\n- `GET /v1/headshots/catalog?locale=en`\n- `GET /v1/headshots/showcases?locale=en`\n- `GET /v1/headshots/showcases/{showcase_id}?locale=en`\n- `GET /v1/headshots/scenes/{scene_id}?locale=en`\n\nSupported locales are `en`, `zh-CN`, `ja`, and `ko`.\n\n## Workflow\n\nKeep the identifiers returned by each stage:\n\n```text\nproject_id -> preview_id -> reference_id -> job_id -> candidate_id\n                                                   -> render_id -> export_id\n```\n\nDo not submit generation before the user has reviewed and confirmed the reference\npreview. Generation consumes credits; preparation and discovery do not.\n\n## Prepare a reference\n\n### Create or restore a project\n\n`POST /v1/headshots/projects` is multipart form data:\n\n- `image` — required JPG, PNG, or WebP, subject to the service upload limit.\n- `scene_id` — optional live scene id.\n- `entry_source` — normally `direct_upload`, or `scene_gallery` when a scene led to the upload.\n\nUse `POST /v1/headshots/projects/{project_id}/source` with an `image` part to replace\nthe source while preserving the project history. Use `GET /v1/headshots/projects/{id}`\nto restore a project, `GET /v1/headshots/projects` to list projects, and `DELETE` on the\nproject resource to remove it and its private derivatives.\n\n### Inspect the source\n\n`POST /v1/headshots/projects/{project_id}/inspect` returns practical eligibility:\n\n```json\n{\"eligible\": true, \"status\": \"ready\", \"reasons\": [], \"warnings\": []}\n```\n\nStop when `eligible` is false. Surface warnings before creating a preview.\n\nSet the garment catalog preference with\n`POST /v1/headshots/projects/{project_id}/garment-preference`:\n\n```json\n{\"garment_preference\": \"female\"}\n```\n\nThe value is `male`, `female`, or `null` to clear it. This selects catalog variants; it\ndoes not infer or alter gender identity.\n\n### Grade, smooth, and crop the reference preview\n\n`POST /v1/headshots/projects/{project_id}/previews` accepts JSON:\n\n```json\n{\n  \"skin_base_id\": \"motu_business_neutral\",\n  \"smoothing_strength\": 0.2,\n  \"crop_spec_id\": \"profile_4x5\",\n  \"crop_anchor\": \"auto\",\n  \"crop_rotation\": 0\n}\n```\n\n- `skin_base_id` — allowed portrait base style; corrects skin colour and white balance.\n- `smoothing_strength` — `0`–`1`; `0` preserves texture and applies no smoothing.\n- `crop_spec_id` — normally `avatar_1x1`, `profile_4x5`, or `headshot_3x4`.\n- `crop_anchor` — `auto`, `center`, or `manual`.\n- `crop_zoom` — `1`–`2`; used by non-manual crop modes.\n- `crop_offset_x`, `crop_offset_y` — `-1`–`1`.\n- `crop_x`, `crop_y`, `crop_width`, `crop_height` — normalized complete rectangle for a manual crop.\n- `crop_rotation` — `-15`–`15` degrees.\n\nThe response contains `preview_id`, the applied `parameters`, and a private image URL.\nDownload it with `GET /v1/headshots/projects/{project_id}/previews/{preview_id}/image`.\n\nAfter the user approves the downloaded preview, confirm an immutable reference with\n`POST /v1/headshots/projects/{project_id}/references`:\n\n```json\n{\"preview_id\": \"hprev_...\"}\n```\n\nDownload it with\n`GET /v1/headshots/projects/{project_id}/references/{reference_id}/image`.\n\n## Configure and generate\n\nUse the public catalog or scene endpoint to discover ids. Never invent ids or generation\nprompts. The public API exposes controlled ids and compatibility, not internal prompts.\n\n`POST /v1/headshots/recommendation` validates a partial selection and returns a complete\ncompatible configuration:\n\n```json\n{\n  \"project_id\": \"hproj_...\",\n  \"reference_id\": \"href_...\",\n  \"scene_id\": \"professional_profile\",\n  \"generation_style_id\": null,\n  \"pose_id\": null,\n  \"outfit_id\": null,\n  \"background_id\": null,\n  \"output_ratio\": \"4:5\",\n  \"framing\": \"auto\"\n}\n```\n\nOptional booleans are `hair_grooming_enabled` and `face_refinement_enabled`. Set\n`allow_incompatible=true` only when the user explicitly chooses catalog options outside\nthe scene recommendation.\n\nSubmit the complete returned selection to `POST /v1/headshots/jobs` with an\n`Idempotency-Key` header. `batch_size` is `1`, `2`, or `4`; `output_ratio` is `1:1`,\n`4:5`, or `3:4`. A successful request returns HTTP 202 and a `job_id`.\n\nGeneration is asynchronous. Query `GET /v1/headshots/jobs/{job_id}`. Terminal states are\n`completed` and `failed`; do not repeatedly submit a replacement job while one is queued\nor running. Candidate entries contain `candidate_id`, `ordinal`, `status`, and an\n`image_url` when ready. Download each private URL with the same API key.\n\nSelect a candidate with `POST /v1/headshots/jobs/{job_id}/selection` and\n`{\"candidate_id\":\"hcand_...\"}`. Favorites are available under\n`/v1/headshots/projects/{project_id}/favorites`.\n\n## Post-process\n\nList styles with:\n\n```http\nGET /v1/headshots/postprocess/styles?reference_id={reference_id}&locale=en\n```\n\nEach style maps a public style id to `base_id` and an optional `flavour_id`. Create a\nrender with `POST /v1/headshots/candidates/{candidate_id}/renders`:\n\n```json\n{\"base_id\": \"motu_business_neutral\", \"flavour_id\": null}\n```\n\nDownload `GET /v1/headshots/renders/{render_id}/image`.\n\n## Export\n\nCreate a controlled crop with `POST /v1/headshots/candidates/{candidate_id}/exports`:\n\n```json\n{\n  \"source_type\": \"master\",\n  \"crop_spec_id\": \"profile_4x5\",\n  \"format\": \"jpeg\",\n  \"quality\": 92\n}\n```\n\nUse `source_type=\"render\"` plus the explicit `render_id` to export a post-processed\nversion. Supported crop specs include `avatar_1x1`, `profile_4x5`, `headshot_3x4`,\n`bust_3x4`, `half_body_2x3`, `three_quarter_2x3`, `full_body_9x16`, and `banner_16x9`.\nFormats are `jpeg`, `png`, and `webp`; quality is `70`–`100`.\n\nOptional automatic adjustments are `offset_x` and `offset_y` from `-0.15` to `0.15`.\nA manual crop requires the complete normalized rectangle and may include\n`crop_rotation` from `-15` to `15`.\n\nDownload the returned `download_url`. Exports are immutable and tied to their explicit\ncandidate or render source.\n\n## Errors and credits\n\n- `400` — invalid transition, ids, compatibility, or parameters.\n- `401` — missing or invalid session/API key.\n- `402` — insufficient credits; do not retry unchanged.\n- `403` — missing `headshot:process` or a non-user-bound service key.\n- `404` — missing resource or owner mismatch.\n- `409` — conflicting or duplicate state transition when applicable.\n- `413` / `415` — invalid upload size or type.\n- `503` — Headshots storage, worker, catalog, or post-processing is unavailable.\n\nPreserve `Idempotency-Key` for a generation retry after an uncertain network response.\nSurface provider or moderation failure details from the job instead of returning an old\ncandidate as if it were new.\n\nFile v1.0.7:references/styles.md\n\n# MotuArt Color Engine — styles overview\n\nThe live catalog is authoritative — run `scripts/styles.sh` to list current ids.\nThis is a quick orientation to the two style tiers and the shipping looks.\n\n## Two tiers\n\n- **base** — a skin-tone target (the anchor the engine grades skin toward).\n  Pick one as the foundation. Default: `motu_korean_id`.\n- **flavour** — a look/grade layered on top (film, clean, teal, etc.).\n  Optional. Combine with a base using the composite separator (default `@`):\n  `<flavour>@<base>`, e.g. `kodak_gold@motu_korean_id`.\n\nPassing only a base gives clean skin-tone correction with no stylization.\n\n## Shipping looks (flavours)\n\n| Look | When to use |\n| --- | --- |\n| Leica Classic | Neutral, true-to-life editorial; restrained contrast. |\n| Kodak Gold | Warm nostalgic film; golden skin, cozy mood. |\n| Clean Cool | Crisp, cool, commercial/e-commerce clarity. |\n| Cine Teal | Cinematic teal shadows; moody outdoor/urban. |\n| Milk Tea | Soft warm beige; lifestyle, gentle portraits. |\n| JP Airy | Bright, airy, low-contrast Japanese style. |\n\nStyle ids differ from display names — always resolve the exact id via\n`scripts/styles.sh` before calling `grade.sh`.\n\n## Strength\n\n`strength` scales the look (default `1.0`). Use `0` to disable stylization (base\ncorrection only), and up to ~`1.5` for a stronger grade. Report `skin_dE` from the\nresult so the user can judge accuracy.\n\nFile v1.0.7:skill-card.md\n\n## Description: <br>\nMotuArt Color Engine helps agents use the hosted MotuArt Color Engine API for identity-preserving portrait grading, skin smoothing, mask export, approved outfit replacement, AI headshots, and ID/passport photo packages. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[chancipher](https://clawhub.ai/user/chancipher) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to prepare portrait, headshot, passport, visa, ID-photo, avatar, and print-sheet outputs through MotuArt's hosted API while preserving identity and surfacing practical compliance warnings. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Portrait, headshot, passport, visa, or ID-style images are privacy-sensitive and are sent to the hosted MotuArt Color Engine service for processing. <br>\nMitigation: Use the skill only when this upload is acceptable for the user's data, and store generated images and workflow state in private output directories. <br>\nRisk: An exposed or over-scoped MCE_API_KEY could allow unintended account usage. <br>\nMitigation: Keep MCE_API_KEY in the local environment, request only the scopes needed for the chosen workflow, and rotate or revoke the key if exposure is suspected. <br>\nRisk: Overriding MCE_API_BASE could redirect image uploads and API keys to an unintended endpoint. <br>\nMitigation: Verify MCE_API_BASE before running processing commands, especially when using non-default environments. <br>\nRisk: Processing and headshot generation consume account credits, and retrying unchanged insufficient-credit requests will not help. <br>\nMitigation: Surface 402 insufficient_credits responses to the user and avoid retrying until credits or request parameters change. <br>\nRisk: ID-photo compliance checks are practical QA signals, not a government guarantee. <br>\nMitigation: Report compliance warnings plainly and have users verify final files against the destination authority's current requirements. <br>\n\n\n## Reference(s): <br>\n- [MotuArt Color Engine API Reference](references/api.md) <br>\n- [AI Headshots API](references/headshots-api.md) <br>\n- [MotuArt Color Engine Crop Specs Overview](references/crop-specs.md) <br>\n- [MotuArt Color Engine Styles Overview](references/styles.md) <br>\n- [MotuArt Color Engine Developer Site](https://mce.motu.art/developers) <br>\n- [ClawHub Skill Page](https://clawhub.ai/chancipher/skills/motu-color-engine) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Guidance, Shell commands, Configuration, Files] <br>\n**Output Format:** [Markdown guidance with inline shell commands; generated workflows may produce image files, JSON reports, and local workflow state.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Uses MCE_API_BASE and MCE_API_KEY environment variables; processing calls may consume account credits.] <br>\n\n## Skill Version(s): <br>\n1.0.7 (source: server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.7:.claude-plugin/plugin.json\n\n{\n  \"name\": \"motu-color-engine\",\n  \"description\": \"AI portrait color grading, pro skin smoothing, segmentation masks, ID/passport crop generation, compliance checks, upload optimization, and print-sheet packaging via the MotuArt Color Engine API.\",\n  \"version\": \"1.1.0\",\n  \"author\": {\n    \"name\": \"MotuArt\",\n    \"email\": \"hi@motu.art\"\n  },\n  \"homepage\": \"https://mce.motu.art/developers\",\n  \"license\": \"MIT\"\n}\n\nFile v1.0.7:agents/openai.yaml\n\ninterface:\n  display_name: \"MotuArt Color Engine\"\n  short_description: \"Portrait grading, AI headshots, outfits, masks, and ID photos\"\n  icon_small: \"./assets/motu-color-engine-logo.svg\"\n  icon_large: \"./assets/motu-color-engine-logo.png\"\n  brand_color: \"#F2542D\"\n  default_prompt: \"Use $motu-color-engine to preserve identity and produce the requested portrait grade, AI headshot, approved outfit, mask, or ID photo.\"\n\npolicy:\n  allow_implicit_invocation: true\n\nArchive v1.0.6: 21 files, 26664 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (459b), assets/motu-color-engine-logo.svg (2208b), references/api.md (10382b), references/crop-specs.md (4420b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3981b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/outfit.sh (1361b), scripts/outfits.sh (1149b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2827b), SKILL.md (11237b), _meta.json (136b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: motu-color-engine\ndescription: AI portrait color grading, skin-tone correction, identity-preserving skin smoothing, skin/person/face mask export, approved clothing replacement, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for grading or retouching portraits, normalizing skin tone, exporting mattes, batch-processing portraits, replacing clothing with a server-approved outfit, cropping to ID/passport/visa/headshot specs, replacing an ID-photo background, validating compliance, optimizing upload files, or creating print sheets. Trigger examples include portrait grading, skin tone, retouch, skin mask, outfit replacement, change clothes, ID photo, passport photo, visa photo, headshot, crop to size, background swap, print sheet, 调色, 肤色, 磨皮, 蒙版, 人像调色, 换装, 换衣, 服装替换, 证件照, 裁剪, 换底, 合规检查, 排版, 一寸, 二寸.\n---\n\n# Motu Color Engine\n\nUse Motu Color Engine to process portrait images through the hosted HTTP API. Prefer the bundled scripts in `scripts/` over hand-written `curl` calls unless the user explicitly needs raw API details.\n\nThe engine preserves identity. Do not describe it as slimming, reshaping, face swapping, or changing facial structure. Skin smoothing only softens pores and blemishes inside detected skin regions. Cropping repositions and pads to a spec; it never stretches or compresses the face.\n\n## Setup\n\n- Require `curl` and `python3`.\n- Read `MCE_API_BASE` from the environment; default is `https://mce.motu.art`.\n- Read `MCE_API_KEY` from the environment; send it only as `X-API-Key`.\n- If the key is missing, direct the user to `https://mce.motu.art/account` (English: `/en/account`) to sign in by email and create one. Ask them to export it securely in their own environment; do not ask them to paste the full key into chat.\n- Never hard-code, print, log, commit, or expose API keys in browser/client code. The full key is shown once and can be rotated or revoked from the account page.\n- Request only the scopes needed: `catalog:read` for discovery, `portrait:process` for grading/smoothing/masks, `id-photo:process` for ID-photo workflows, and `outfit:process` for outfit replacement. An ID package with an outfit needs both `id-photo:process` and `outfit:process`.\n- Processing calls consume account credits; catalog discovery does not. Surface `402 insufficient_credits` instead of retrying.\n- Check service health with `curl -sS \"${MCE_API_BASE:-https://mce.motu.art}/v1/health\"` when diagnosing connectivity.\n\n## Choose The Workflow\n\n- Use `scripts/grade.sh` when the user wants color grading, skin-tone correction, a film/commercial look, or grading plus optional crop.\n- Use `scripts/smooth.sh` when the user wants smoothing only with no color or white-balance change.\n- Use `scripts/mask.sh` when the user wants a skin, valid-skin, face, or person mask/matte.\n- Use `scripts/crop.sh` when the user wants crop-only ID/passport/visa/headshot/avatar output, optionally with a solid background color.\n- Use `scripts/outfit.sh` when the user wants clothing replacement only. The outfit id must come from the approved catalog; never accept or invent a custom prompt or outfit id.\n- Use `scripts/outfits.sh` before clothing replacement to discover currently enabled outfit ids. Do not infer an id from a garment name.\n- Use `scripts/id-pack.sh` when the user wants a complete ID/passport photo delivery package: one graded/smoothed master, multiple specs, upload-ready files, compliance report, and optional print sheets.\n- Use `scripts/id-check.sh` when the user wants to validate an ID photo against a spec or understand compliance warnings.\n- Use `scripts/optimize.sh` when the user needs a website/upload-ready file with format, pixel size, DPI, or maximum KB constraints.\n- Use `scripts/print-sheet.sh` when the user wants cropped ID photos laid out on photo paper for printing.\n- Use `scripts/styles.sh` to discover live style ids. Read `references/styles.md` only when the user needs style-selection guidance or offline context.\n- Use `scripts/crop-specs.sh` to discover live crop specs. Read `references/crop-specs.md` only when choosing specs or background palettes without live discovery.\n- Read `references/api.md` for endpoint parameters, response fields, headers, limits, and error codes.\n\n## Grade Portraits\n\n```bash\nscripts/grade.sh <input-image> <output-image> [style-id] [strength] [smooth-strength] [smooth-texture-retain] [crop-spec] [bg-color] [pad-color]\n```\n\n- Omit `style-id` for the default skin base, or choose a style from `scripts/styles.sh`.\n- Use `strength` for look intensity; default is `1.0`, `0` disables the look, and values up to about `1.5` are stronger.\n- Pass `smooth-strength` from `0` to `1` only when the user asks for softened pores or blemishes. Omit it, or pass `0`, to preserve natural texture.\n- Use `smooth-texture-retain` from `0` to `1` to keep natural texture over smoothing; default is `0.35`.\n- Pass `crop-spec` when the same output should be graded and cropped in one API call.\n- Pass `bg-color` only with `crop-spec`; use an allowed palette name such as `white`, `blue`, or `red`, `default`, or explicit `#RRGGBB`.\n- Pass `pad-color` only with `crop-spec` when a specific padding color is needed; otherwise let the API edge-replicate.\n- Report `skin_dE` from script output when summarizing quality; lower means closer skin color to the target.\n\nFor a folder, run the script once per image. Keep batch loops serial unless the user asks for parallelism and accepts API/load implications.\n\n## Smooth Skin Only\n\n```bash\nscripts/smooth.sh <input-image> <output.png> [strength] [texture-retain]\n```\n\n- Use this for pore/blemish softening without style, color, or white-balance changes.\n- Default `strength` is `0.6`.\n- Default `texture-retain` is `0.35`; raise it to preserve more natural texture.\n\n## Export Masks\n\n```bash\nscripts/mask.sh <input-image> <output.png> [mask-kind]\n```\n\n- Use `skin` by default.\n- Other mask kinds are `valid_skin`, `face`, and `person`.\n- Output is an 8-bit grayscale PNG aligned to the input.\n\n## Crop ID Or Portrait Photos\n\n```bash\nscripts/crop.sh <input-image> <output-image> [spec-id] [bg-color] [pad-color]\n```\n\n- Default `spec-id` is `one_inch`.\n- Use `scripts/crop-specs.sh` to list supported specs and allowed background colors.\n- Use `bg-color` only when the spec declares a background palette, mostly ID-photo specs.\n- Use `pad-color` only when a source image lacks required margins and the user wants a specific fill.\n- Surface crop warnings from script output, especially warnings about margins, resolution, or background limitations.\n- Use `grade.sh` with crop arguments when the user wants grading and crop in one output.\n\n## Make ID Photo Packages\n\n```bash\nscripts/id-pack.sh <input-image> <output-dir> [specs] [style-id] [smooth-strength] [bg-color] [upload] [print-sheet] [outfit-id] [outfit-long-edge]\n```\n\n- Use this for passport/visa/ID-photo deliverables rather than calling `grade.sh` once per spec. The API generates one graded/smoothed master first, then crops multiple specs from that master so colour and retouching stay consistent.\n- `specs` is comma-separated, e.g. `passport_cn,one_inch,us_visa`; default is `passport_cn`. School/enrollment specs include `shanghai_compulsory_education_cn`, `college_graduation_image_cn`, and `national_k12_student_status_cn`.\n- Default style is `motu_business_neutral`; pass `smooth-strength` from `0` to `1` only when the user asks for smoothing.\n- `bg-color` defaults to `default`, which applies each spec's standard background palette. Use `white`, `blue`, `light_blue`, `red`, or `#RRGGBB` when the user asks and the spec allows it.\n- `upload` defaults to `true`, writing upload-optimized JPG files using the spec's `upload` rules from `crop_specs.json`.\n- `print-sheet` is optional, e.g. `6x4` or `a4`; when specs have different sizes, separate sheets may be generated.\n- `outfit-id` is optional. When present, it must be an id returned by `scripts/outfits.sh`; omitted keeps the original clothing.\n- `outfit-long-edge` controls the upstream outfit result size, defaults to 1536, and is bounded by the service to 512–2048px.\n- Output folder contains `master.png`, `single/`, `upload/`, `print/`, and `report.json`. Surface compliance status and warnings from the report.\n- When the user requests a supported outfit, pass its approved catalog id. Outfit replacement runs before the corrected master is generated, so all crop specs share the same clothing result.\n\n## Replace Clothing Only\n\nDiscover the approved catalog first:\n\n```bash\nscripts/outfits.sh\n```\n\nSelect only an id returned by that command, then replace clothing:\n\n```bash\nscripts/outfit.sh <input-image> <output.png> <approved-outfit-id> [long-edge]\n```\n\n- Only use ids returned by `GET /v1/outfits`; the API maps each approved id to its controlled generation prompt and rejects custom prompts or arbitrary ids.\n- The catalog groups styles as `male`, `female`, `kids`, or `unisex`; use the category and localized name/description to help select a suitable style.\n- If the requested clothing is absent, explain that only catalog styles are available; do not substitute a custom prompt, URL, or upload.\n- The service protects the detected facial oval with the face mask and calls the configured Motu asynchronous workflow.\n- Default output long edge is 1536px; the service bounds requests to 512–2048px.\n- Clothing generation must preserve the face and identity. Report upstream failures or timeouts instead of silently returning the original image.\n\n## Check ID Photo Compliance\n\n```bash\nscripts/id-check.sh <input-image> [spec-id] [report-json]\n```\n\n- Without `report-json`, the input is treated as a source portrait: the API crop-checks it against the spec and reports practical compliance.\n- With `report-json`, the input is treated as the already-cropped ID photo and the supplied crop metrics are checked.\n- Report failures and warnings plainly; this is a practical QA check, not a government guarantee.\n\n## Optimize Upload Files\n\n```bash\nscripts/optimize.sh <input-image> <output-image> [format] [max-kb] [quality] [resize] [dpi]\n```\n\n- Use for official website upload limits such as JPG under a maximum KB, exact pixel dimensions, or DPI metadata.\n- `format` is `jpg`, `png`, or `webp`; `resize` is `WIDTHxHEIGHT`; lossy formats search quality down to the server default floor when `max-kb` is set.\n\n## Make Print Sheets\n\n```bash\nscripts/print-sheet.sh <output-image> <paper> <input1> [input2 ...]\n```\n\n- Use after generating cropped ID photos when the user wants a printable sheet.\n- `paper` supports common values such as `6x4`, `4x6`, `5x7`, and `a4`. Inputs on a single sheet must have the same pixel size; use `id-pack.sh` for automatic grouping by size.\n\n## Constraints To Surface\n\n- Upload limit is about 15 MB per image.\n- Supported upload formats are JPG, PNG, and WebP.\n- Processing is synchronous; batch jobs are repeated one-image calls.\n- Background replacement is limited to specs that declare `bg_colors`.\n- If a script fails, read its HTTP status and error detail before deciding whether to retry, change arguments, or ask the user for configuration.\n\nFile v1.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn7b98pvjtsm6a4bw8gd87ttbs8a3ycc\",\n  \"slug\": \"motu-color-engine\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1784045432798\n}\n\nFile v1.0.6:references/api.md\n\n# MotuArt Color Engine — API reference\n\nBase URL: `$MCE_API_BASE` (default `https://mce.motu.art`).\nAuth: create a key at `https://mce.motu.art/account` (English: `/en/account`), then send\n`X-API-Key: $MCE_API_KEY` (or `Authorization: Bearer $MCE_API_KEY`) on every endpoint\n**except** `/v1/health`. The full key is displayed once; store it securely and rotate or\nrevoke it from the account page if exposed.\n\nScopes:\n- `catalog:read` — styles, crop specs and approved outfits.\n- `portrait:process` — process, smooth and mask.\n- `id-photo:process` — crop, id-pack, id-check, optimize and print-sheet.\n- `outfit:process` — standalone outfit replacement. Also required in addition to\n  `id-photo:process` or `portrait:process` when those requests include `outfit_id`.\n\nSuccessful processing calls consume account credits; catalog requests do not. A `402`\nresponse uses `detail.code=\"insufficient_credits\"` and includes `required`, `available`,\nand whether the request included outfit replacement.\n\n## GET /v1/health\nLiveness/version. No key required.\n\n## GET /v1/styles\nReturns `{ styles: [{id, name, kind, name_zh, ...}], composite_separator, bases, flavours }`.\n`kind` is `base` or `flavour`. Combine as `<flavour><composite_separator><base>`\n(default separator `@`), e.g. `kodak_gold@motu_korean_id`.\n\n## POST /v1/process  (multipart/form-data)\nGrade an image. Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `style` — style id (default `motu_korean_id`).\n- `strength` — look intensity, default `1.0` (0–~1.5).\n- `smooth_strength` — optional M15 pro skin smoothing, `0`–`1`. Omitted/`0` leaves skin\n  texture untouched (default). Softens pores/blemishes only; never reshapes the face.\n- `smooth_texture_retain` — optional, `0`–`1` (default `0.35`), how much natural\n  texture to keep on top of the smoothing. Only used when `smooth_strength` > 0.\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n- `max_long_edge` — cap working long edge (default 1024; server ceiling applies).\n- `mask` — `true` to also return a mask inline (base64).\n- `mask_kind` — mask type when `mask=true` (see below).\n- `crop_spec` — optional M16 purpose crop spec id (see `GET /v1/crop/specs`). When set,\n  the graded output is additionally cropped to that spec (grade + crop in one call).\n  Omitted — full graded frame, uncropped.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin; only used with `crop_spec`. Omitted — edge-replicate padding (the default).\n- `bg_color` — optional background replacement (换底), only used with `crop_spec`: a\n  palette name the spec allows (e.g. `white`/`blue`/`red`), `default` for the spec's\n  standard color, or an explicit `#RRGGBB`. Omitted — original background kept.\n\nResponse JSON:\n```\n{ \"trace_id\", \"style_id\", \"image_base64\", \"content_type\",\n  \"processing_time_ms\", \"quality\": { \"skin_delta_e_to_target\", \"warnings\" },\n  \"report_url\", \"compare_base64\",\n  \"mask_base64\", \"mask_kind\", \"mask_content_type\" }   // mask_* only when mask=true\n```\nDecode `image_base64` to bytes to get the graded image. `skin_delta_e_to_target`\nis the skin ΔE to the target skin (lower = closer).\n\n## POST /v1/mask  (multipart/form-data)\nSegmentation only (decode + parse; **skips grading/render/score** — faster). Fields:\n- `file` (required).\n- `mask_kind` — `skin` (default) | `valid_skin` | `face` | `person`.\n- `max_long_edge` — optional.\n\nReturns the mask as a raw **grayscale PNG** (`Content-Type: image/png`), with header\n`X-MCE-Mask-Kind`. Save the response body directly.\n\n## POST /v1/smooth  (multipart/form-data)\nStandalone M15 pro skin smoothing — runs decode + parse + smoothing + render only,\n**skipping the entire color-grading stack**. Softens pores/blemishes on the detected\nskin region; never reshapes the face or changes color. Fields:\n- `file` (required).\n- `strength` — smoothing amount, default `0.6`.\n- `texture_retain` — how much natural texture to keep, default `0.35`.\n- `radius_frac` — optional blur radius override (fraction of face size).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the smoothed image as a raw payload (default `image/png`), like `/v1/mask`.\n\n## GET /v1/crop/specs\nList the available purpose-crop specs (证件照/形象照/头像 standards). Returns\n`{ specs: [{id, name, name_zh, category, width_px, height_px, width_mm, height_mm,\ndpi, head_ratio, bg_colors, default_bg, description_zh}] }`.\n- `category` — `id_photo` | `portrait` | `avatar`.\n- `width_mm`/`height_mm`/`dpi` — physical print size; `null` for portrait/avatar specs\n  (pixel-only, no print standard).\n- `bg_colors` — `{name: \"#RRGGBB\"}` palette the spec allows for background\n  replacement; `{}` when the spec does not standardize a background (most\n  portrait/avatar specs). `default_bg` is the palette name applied when a caller\n  requests `bg_color=\"default\"`.\n- See `references/crop-specs.md` for a curated overview of the shipped specs.\n\n## POST /v1/crop  (multipart/form-data)\nStandalone M16 purpose-crop. Runs decode + face/head geometry + crop **only** — no\nhuman parsing, no color grading (use `/v1/process` with `crop_spec` to grade and crop\ntogether). Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `spec` — crop spec id (default `one_inch`); see `GET /v1/crop/specs`.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin. Omitted — edge-replicate padding.\n- `bg_color` — optional background replacement (换底): a palette name the spec\n  allows, `default` for the spec's standard color, or an explicit `#RRGGBB`. Omitted —\n  original background kept.\n- `max_long_edge` — optional working-resolution cap; `0`/omitted means **full source\n  resolution** (crop quality is bounded by source resolution, not a latency budget —\n  unlike `/v1/process`, which defaults to 1024).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the cropped image as a raw payload (default `image/png`, with the spec's DPI\nembedded), like `/v1/mask`/`/v1/smooth`. The achieved geometry and any warnings are in\nthe `X-MCE-Crop-Info` response header (JSON), alongside `X-MCE-Trace-Id`.\n\n## POST /v1/id-pack  (multipart/form-data)\nGenerate a complete ID-photo delivery package. The service creates one graded/smoothed\nmaster, detects face/head geometry once, then crops multiple specs from that master.\nFields:\n- `file` (required) — image upload.\n- `specs` (required) — comma-separated crop spec ids, e.g. `passport_cn,one_inch`.\n- `style` — style id (default `motu_korean_id`).\n- `smooth_strength`, `smooth_texture_retain` — optional skin smoothing.\n- `strength`, `output_space`, `max_long_edge` — same meaning as `/v1/process`.\n- `bg_color` — `default` (recommended for ID photos), palette name, or `#RRGGBB`.\n- `pad_color` — optional padding colour.\n- `output_format` — `png` (default) | `jpeg` | `webp` for single-spec files.\n- `quality` — output quality for lossy formats.\n- `upload` — `true` to include upload-optimized files using spec `upload` rules.\n- `print_sheet` — optional paper id such as `6x4`/`a4`; groups same-size photos.\n\nResponse JSON includes `trace_id`, `style_id`, `master_base64`, `items[]` with\n`image_base64`, `crop_info`, `compliance`, optional `upload.image_base64`, optional\n`print_sheets[].image_base64`, and the master quality report.\n\nOptional outfit fields:\n- `outfit_id` — approved id returned by `GET /v1/outfits`; omitted keeps the original clothing.\n- `outfit_long_edge` — upstream generation long edge, bounded to 512–2048; default 1536.\n\n## GET /v1/outfits\nReturns the approved outfit catalog. Each item includes `id`, localized names and\ndescriptions, `category` (`male`/`female`/`kids`/`unisex`), `order`, `available`, and\noptional `preview_url`. `available` mirrors the catalog's `enabled` switch. The\ncontrolled `generation_prompt` used by the workflow is never exposed.\n\n## POST /v1/outfit  (multipart/form-data)\nControlled standalone clothing replacement. Fields:\n- `file` (required) — source JPG, PNG, or WebP.\n- `outfit_id` (required) — approved catalog id. Custom prompts and arbitrary ids are rejected.\n- `long_edge` — requested generation long edge, bounded to 512–2048; default 1536.\n\nResponse JSON contains `task_id`, `outfit_id`, `image_base64`, `content_type`,\n`long_edge`, and `processing_time_ms`. MCE resolves the id to its controlled\n`generation_prompt`, then submits the source, prompt, face mask, and long edge to the\nconfigured asynchronous Motu workflow and polls it.\n\n## POST /v1/id-check  (multipart/form-data)\nCheck an ID photo against a crop spec. Fields:\n- `file` (required) — source portrait, or already-cropped ID photo when `report_json` is supplied.\n- `spec` (required) — crop spec id.\n- `report_json` — optional crop report containing `metrics.crop`; use this when checking an already-cropped output.\n- `bg_color` — optional background for the temporary crop-check path (default `default`).\n\nResponse JSON: `{ ok, status, checks, warnings, errors }`. This is practical QA, not\na government acceptance guarantee.\n\n## POST /v1/optimize  (multipart/form-data)\nExport an upload-ready file. Fields:\n- `file` (required).\n- `output_format` — `jpg`/`jpeg` (default), `png`, or `webp`.\n- `max_kb` — optional maximum file size in KB.\n- `quality`, `min_quality` — lossy encoder quality range.\n- `resize` — optional `WIDTHxHEIGHT`.\n- `dpi` — optional DPI metadata.\n\nReturns the optimized image as a raw payload. Metadata is in `X-MCE-Export-Info`.\n\n## POST /v1/print-sheet  (multipart/form-data)\nLayout one or more same-size ID photos on paper. Fields:\n- `files` — one or more image uploads.\n- `paper` — `6x4` (default), `4x6`, `5x7`, `7x5`, `a4`, or `WIDTHxHEIGHTin`.\n- `dpi`, `margin_mm`, `gap_mm`, `cut_lines`, `output_format`.\n\nReturns the print sheet as a raw image payload. Metadata is in `X-MCE-Print-Sheet-Info`.\n\n## Errors\n- `400` bad params / empty upload · `401` missing/invalid key ·\n  `413` too large · `415` unsupported content-type · `422` processing/segmentation failed.\nError bodies are JSON `{ \"detail\": \"...\" }`.\n\nFile v1.0.6:references/crop-specs.md\n\n# MotuArt Color Engine — crop specs overview (M16 purpose crop)\n\nThe live catalog is authoritative — run `scripts/crop-specs.sh` (or `GET\n/v1/crop/specs`) to list current ids/sizes. This is a quick orientation to the\nthree categories and the shipping specs.\n\n## Three categories\n\n- **id_photo** — official ID/passport/visa/license photo standards. Fixed pixel size\n  + physical `width_mm`/`height_mm` + `dpi` (embedded on save, so exports print at the\n  right physical size). Most declare a `bg_colors` palette for background replacement\n  (换底) since these documents require a specific solid background. ID-photo specs may\n  also include `compliance`, `upload`, and `print` metadata used by `id-pack`,\n  `id-check`, upload optimization, and print-sheet layout.\n- **portrait** — professional/editorial portrait framings (headshot to full body).\n  Pixel-only, no print standard, no background palette (original background kept).\n- **avatar** — square social-avatar framing. Pixel-only, no background palette.\n\nPass only a `spec` id — the engine auto-detects the face/head and positions it to\nthat spec's `head_ratio` (crown-to-chin as a fraction of output height) and margins;\nyou never draw a crop box by hand.\n\n## id_photo specs (fixed background palette, mostly white/blue/red)\n\n| id | Use | Size | Print |\n| --- | --- | --- | --- |\n| `one_inch` | 简历/证件 general 1-inch | 295×413px | 25×35mm@300dpi |\n| `two_inch` | Standard 2-inch | 413×579px | 35×49mm@300dpi |\n| `small_two_inch` | Small 2-inch (passport/visa common) | 413×531px | 35×45mm@300dpi |\n| `small_one_inch` | Driver's license / some certificates | 260×378px | 22×32mm@300dpi |\n| `big_two_inch` | Diploma (blue background common) | 413×626px | 35×53mm@300dpi |\n| `id_card_cn` | CN ID card / social security card (GA 461) | 358×441px | 26×32mm@350dpi |\n| `shanghai_compulsory_education_cn` | 上海义务教育入学免冠证件照 | 272×354px | 20×26mm@350dpi |\n| `college_graduation_image_cn` | 大学生毕业图像信息采集免冠证件照 | 480×640px | 41×54mm@300dpi |\n| `national_k12_student_status_cn` | 全国中小学生学籍电子版照片 | 358×441px | 26×32mm@350dpi |\n| `passport_cn` | CN passport / HK-Macau-Taiwan permit / CN visa | 390×567px | 33×48mm@300dpi |\n| `us_visa` | US visa 2×2 | 600×600px | 51×51mm@300dpi |\n| `schengen_visa` | Schengen/UK visa | 413×531px | 35×45mm@300dpi |\n| `japan_visa` | Japan visa | 531×531px | 45×45mm@300dpi |\n| `canada_visa` | Canada visa/immigration | 590×826px | 50×70mm@300dpi |\n\n## portrait specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `headshot_3x4` | Close face headshot (actor/streamer/résumé) | 900×1200px | 0.55 |\n| `profile_4x5` | Professional headshot (LinkedIn/website/business card) | 1200×1500px | 0.42 |\n| `bust_3x4` | Chest-up bust portrait (team page/instructor bio) | 1200×1600px | 0.33 |\n| `half_body_2x3` | Waist-up half body (magazine-style, needs waist+ in source) | 1200×1800px | 0.26 |\n| `three_quarter_2x3` | Knee-up three-quarter body (needs knee+ in source) | 1200×1800px | 0.19 |\n| `full_body_9x16` | Full body, vertical poster/social (needs full body in source) | 1080×1920px | 0.13 |\n| `banner_16x9` | Wide head-and-shoulders banner (website/video cover) | 1920×1080px | 0.45 |\n\n## avatar specs (no background palette)\n\n| id | Use | Size | head_ratio |\n| --- | --- | --- | --- |\n| `avatar_1x1` | Square social avatar (WeChat/DingTalk/general) | 800×800px | 0.45 |\n\n## Background replacement (换底)\n\nOnly `id_photo` specs declare a `bg_colors` palette (e.g. `{\"white\": \"#FFFFFF\",\n\"blue\": \"#438EDB\", \"light_blue\": \"#D6EAF8\", \"red\": \"#FF0000\"}` for the CN sizes). Pass a palette name, `default`\n(the spec's standard choice), or an explicit `#RRGGBB` as `bg_color` — an\nunrecognized name is rejected (the palette *is* the compliance rule for these\ndocuments). Background swap runs a portrait-matting pass on the crop window at source\nresolution, so hair/ear edges stay clean (no crude-cutout fringe).\n\n## Framing guarantee\n\nCropping only repositions the frame (head ratio + margins) — it never stretches or\ncompresses facial proportions. Wide framings (`half_body_2x3`, `three_quarter_2x3`,\n`full_body_9x16`) require the source photo to actually contain that much of the body;\nthe engine pads (edge-replicate or `pad_color`) rather than invent missing content.\n\nFile v1.0.6:references/styles.md\n\n# MotuArt Color Engine — styles overview\n\nThe live catalog is authoritative — run `scripts/styles.sh` to list current ids.\nThis is a quick orientation to the two style tiers and the shipping looks.\n\n## Two tiers\n\n- **base** — a skin-tone target (the anchor the engine grades skin toward).\n  Pick one as the foundation. Default: `motu_korean_id`.\n- **flavour** — a look/grade layered on top (film, clean, teal, etc.).\n  Optional. Combine with a base using the composite separator (default `@`):\n  `<flavour>@<base>`, e.g. `kodak_gold@motu_korean_id`.\n\nPassing only a base gives clean skin-tone correction with no stylization.\n\n## Shipping looks (flavours)\n\n| Look | When to use |\n| --- | --- |\n| Leica Classic | Neutral, true-to-life editorial; restrained contrast. |\n| Kodak Gold | Warm nostalgic film; golden skin, cozy mood. |\n| Clean Cool | Crisp, cool, commercial/e-commerce clarity. |\n| Cine Teal | Cinematic teal shadows; moody outdoor/urban. |\n| Milk Tea | Soft warm beige; lifestyle, gentle portraits. |\n| JP Airy | Bright, airy, low-contrast Japanese style. |\n\nStyle ids differ from display names — always resolve the exact id via\n`scripts/styles.sh` before calling `grade.sh`.\n\n## Strength\n\n`strength` scales the look (default `1.0`). Use `0` to disable stylization (base\ncorrection only), and up to ~`1.5` for a stronger grade. Report `skin_dE` from the\nresult so the user can judge accuracy.\n\nFile v1.0.6:skill-card.md\n\n## Description: <br>\nMotuArt Color Engine helps agents use a hosted HTTP API for portrait color grading, skin-tone correction, identity-preserving skin smoothing, mask export, approved outfit replacement, and ID, passport, headshot, and avatar production. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[chancipher](https://clawhub.ai/user/chancipher) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill when an agent needs to prepare portrait, headshot, passport, visa, ID-photo, or avatar deliverables through the MotuArt Color Engine service. It is suited for guided retouching, crop-spec selection, compliance checks, upload optimization, and print-sheet preparation. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Portrait, headshot, and ID-photo images may be privacy-sensitive and are sent to the hosted MotuArt Color Engine service for processing. <br>\nMitigation: Confirm the user is comfortable with the upload and destination endpoint before processing sensitive identity photos. <br>\nRisk: API key exposure could allow unauthorized use of the service or account credits. <br>\nMitigation: Keep the API key in the user's environment, avoid pasting it into chat, and rotate or revoke exposed keys from the account page. <br>\nRisk: Processing calls consume account credits and may fail when credits are insufficient. <br>\nMitigation: Surface insufficient-credit errors plainly instead of retrying, and use catalog discovery where possible because it does not consume credits. <br>\n\n\n## Reference(s): <br>\n- [MotuArt Color Engine API reference](artifact/references/api.md) <br>\n- [MotuArt Color Engine crop specs overview](artifact/references/crop-specs.md) <br>\n- [MotuArt Color Engine styles overview](artifact/references/styles.md) <br>\n- [ClawHub skill page](https://clawhub.ai/chancipher/skills/motu-color-engine) <br>\n- [MotuArt account and API key page](https://mce.motu.art/account) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [guidance, shell commands, configuration, files] <br>\n**Output Format:** [Markdown guidance with inline shell commands and generated image or report files from API-backed workflows] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Uses environment configuration for MCE_API_BASE and MCE_API_KEY; processing calls may consume account credits.] <br>\n\n## Skill Version(s): <br>\n1.0.6 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.0.6:.claude-plugin/plugin.json\n\n{\n  \"name\": \"motu-color-engine\",\n  \"description\": \"AI portrait color grading, pro skin smoothing, segmentation masks, ID/passport crop generation, compliance checks, upload optimization, and print-sheet packaging via the MotuArt Color Engine API.\",\n  \"version\": \"1.1.0\",\n  \"author\": {\n    \"name\": \"MotuArt\",\n    \"email\": \"hi@motu.art\"\n  },\n  \"homepage\": \"https://mce.motu.art/developers\",\n  \"license\": \"MIT\"\n}\n\nFile v1.0.6:agents/openai.yaml\n\ninterface:\n  display_name: \"MotuArt Color Engine\"\n  short_description: \"Portrait grading, approved outfits, masks, and ID photos\"\n  icon_small: \"./assets/motu-color-engine-logo.svg\"\n  icon_large: \"./assets/motu-color-engine-logo.png\"\n  brand_color: \"#F2542D\"\n  default_prompt: \"Use $motu-color-engine to process this portrait, preserve identity, and produce the requested grade, approved outfit, mask, or ID photo.\"\n\npolicy:\n  allow_implicit_invocation: true\n\nArchive v1.0.5: 21 files, 26103 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (459b), assets/motu-color-engine-logo.svg (2208b), references/api.md (9614b), references/crop-specs.md (4420b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3981b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/outfit.sh (1361b), scripts/outfits.sh (1149b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2917b), SKILL.md (10569b), _meta.json (136b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: motu-color-engine\ndescription: AI portrait color grading, skin-tone correction, identity-preserving skin smoothing, skin/person/face mask export, approved clothing replacement, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for grading or retouching portraits, normalizing skin tone, exporting mattes, batch-processing portraits, replacing clothing with a server-approved outfit, cropping to ID/passport/visa/headshot specs, replacing an ID-photo background, validating compliance, optimizing upload files, or creating print sheets. Trigger examples include portrait grading, skin tone, retouch, skin mask, outfit replacement, change clothes, ID photo, passport photo, visa photo, headshot, crop to size, background swap, print sheet, 调色, 肤色, 磨皮, 蒙版, 人像调色, 换装, 换衣, 服装替换, 证件照, 裁剪, 换底, 合规检查, 排版, 一寸, 二寸.\n---\n\n# Motu Color Engine\n\nUse Motu Color Engine to process portrait images through the hosted HTTP API. Prefer the bundled scripts in `scripts/` over hand-written `curl` calls unless the user explicitly needs raw API details.\n\nThe engine preserves identity. Do not describe it as slimming, reshaping, face swapping, or changing facial structure. Skin smoothing only softens pores and blemishes inside detected skin regions. Cropping repositions and pads to a spec; it never stretches or compresses the face.\n\n## Setup\n\n- Require `curl` and `python3`.\n- Read `MCE_API_BASE` from the environment; default is `https://mce.motu.art`.\n- Read `MCE_API_KEY` from the environment when auth is enabled; send it only as `X-API-Key`.\n- Never hard-code API keys. If a key is missing and the service requires one, ask the user for it or ask them to export it.\n- Check service health with `curl -sS \"${MCE_API_BASE:-https://mce.motu.art}/v1/health\"` when diagnosing connectivity.\n\n## Choose The Workflow\n\n- Use `scripts/grade.sh` when the user wants color grading, skin-tone correction, a film/commercial look, or grading plus optional crop.\n- Use `scripts/smooth.sh` when the user wants smoothing only with no color or white-balance change.\n- Use `scripts/mask.sh` when the user wants a skin, valid-skin, face, or person mask/matte.\n- Use `scripts/crop.sh` when the user wants crop-only ID/passport/visa/headshot/avatar output, optionally with a solid background color.\n- Use `scripts/outfit.sh` when the user wants clothing replacement only. The outfit id must come from the approved catalog; never accept or invent a custom prompt or outfit id.\n- Use `scripts/outfits.sh` before clothing replacement to discover currently enabled outfit ids. Do not infer an id from a garment name.\n- Use `scripts/id-pack.sh` when the user wants a complete ID/passport photo delivery package: one graded/smoothed master, multiple specs, upload-ready files, compliance report, and optional print sheets.\n- Use `scripts/id-check.sh` when the user wants to validate an ID photo against a spec or understand compliance warnings.\n- Use `scripts/optimize.sh` when the user needs a website/upload-ready file with format, pixel size, DPI, or maximum KB constraints.\n- Use `scripts/print-sheet.sh` when the user wants cropped ID photos laid out on photo paper for printing.\n- Use `scripts/styles.sh` to discover live style ids. Read `references/styles.md` only when the user needs style-selection guidance or offline context.\n- Use `scripts/crop-specs.sh` to discover live crop specs. Read `references/crop-specs.md` only when choosing specs or background palettes without live discovery.\n- Read `references/api.md` for endpoint parameters, response fields, headers, limits, and error codes.\n\n## Grade Portraits\n\n```bash\nscripts/grade.sh <input-image> <output-image> [style-id] [strength] [smooth-strength] [smooth-texture-retain] [crop-spec] [bg-color] [pad-color]\n```\n\n- Omit `style-id` for the default skin base, or choose a style from `scripts/styles.sh`.\n- Use `strength` for look intensity; default is `1.0`, `0` disables the look, and values up to about `1.5` are stronger.\n- Pass `smooth-strength` from `0` to `1` only when the user asks for softened pores or blemishes. Omit it, or pass `0`, to preserve natural texture.\n- Use `smooth-texture-retain` from `0` to `1` to keep natural texture over smoothing; default is `0.35`.\n- Pass `crop-spec` when the same output should be graded and cropped in one API call.\n- Pass `bg-color` only with `crop-spec`; use an allowed palette name such as `white`, `blue`, or `red`, `default`, or explicit `#RRGGBB`.\n- Pass `pad-color` only with `crop-spec` when a specific padding color is needed; otherwise let the API edge-replicate.\n- Report `skin_dE` from script output when summarizing quality; lower means closer skin color to the target.\n\nFor a folder, run the script once per image. Keep batch loops serial unless the user asks for parallelism and accepts API/load implications.\n\n## Smooth Skin Only\n\n```bash\nscripts/smooth.sh <input-image> <output.png> [strength] [texture-retain]\n```\n\n- Use this for pore/blemish softening without style, color, or white-balance changes.\n- Default `strength` is `0.6`.\n- Default `texture-retain` is `0.35`; raise it to preserve more natural texture.\n\n## Export Masks\n\n```bash\nscripts/mask.sh <input-image> <output.png> [mask-kind]\n```\n\n- Use `skin` by default.\n- Other mask kinds are `valid_skin`, `face`, and `person`.\n- Output is an 8-bit grayscale PNG aligned to the input.\n\n## Crop ID Or Portrait Photos\n\n```bash\nscripts/crop.sh <input-image> <output-image> [spec-id] [bg-color] [pad-color]\n```\n\n- Default `spec-id` is `one_inch`.\n- Use `scripts/crop-specs.sh` to list supported specs and allowed background colors.\n- Use `bg-color` only when the spec declares a background palette, mostly ID-photo specs.\n- Use `pad-color` only when a source image lacks required margins and the user wants a specific fill.\n- Surface crop warnings from script output, especially warnings about margins, resolution, or background limitations.\n- Use `grade.sh` with crop arguments when the user wants grading and crop in one output.\n\n## Make ID Photo Packages\n\n```bash\nscripts/id-pack.sh <input-image> <output-dir> [specs] [style-id] [smooth-strength] [bg-color] [upload] [print-sheet] [outfit-id] [outfit-long-edge]\n```\n\n- Use this for passport/visa/ID-photo deliverables rather than calling `grade.sh` once per spec. The API generates one graded/smoothed master first, then crops multiple specs from that master so colour and retouching stay consistent.\n- `specs` is comma-separated, e.g. `passport_cn,one_inch,us_visa`; default is `passport_cn`. School/enrollment specs include `shanghai_compulsory_education_cn`, `college_graduation_image_cn`, and `national_k12_student_status_cn`.\n- Default style is `motu_business_neutral`; pass `smooth-strength` from `0` to `1` only when the user asks for smoothing.\n- `bg-color` defaults to `default`, which applies each spec's standard background palette. Use `white`, `blue`, `light_blue`, `red`, or `#RRGGBB` when the user asks and the spec allows it.\n- `upload` defaults to `true`, writing upload-optimized JPG files using the spec's `upload` rules from `crop_specs.json`.\n- `print-sheet` is optional, e.g. `6x4` or `a4`; when specs have different sizes, separate sheets may be generated.\n- `outfit-id` is optional. When present, it must be an id returned by `scripts/outfits.sh`; omitted keeps the original clothing.\n- `outfit-long-edge` controls the upstream outfit result size, defaults to 1536, and is bounded by the service to 512–2048px.\n- Output folder contains `master.png`, `single/`, `upload/`, `print/`, and `report.json`. Surface compliance status and warnings from the report.\n- When the user requests a supported outfit, pass its approved catalog id. Outfit replacement runs before the corrected master is generated, so all crop specs share the same clothing result.\n\n## Replace Clothing Only\n\nDiscover the approved catalog first:\n\n```bash\nscripts/outfits.sh\n```\n\nSelect only an id returned by that command, then replace clothing:\n\n```bash\nscripts/outfit.sh <input-image> <output.png> <approved-outfit-id> [long-edge]\n```\n\n- Only use ids returned by `GET /v1/outfits`; the API maps each approved id to its controlled generation prompt and rejects custom prompts or arbitrary ids.\n- The catalog groups styles as `male`, `female`, `kids`, or `unisex`; use the category and localized name/description to help select a suitable style.\n- If the requested clothing is absent, explain that only catalog styles are available; do not substitute a custom prompt, URL, or upload.\n- The service protects the detected facial oval with the face mask and calls the configured Motu asynchronous workflow.\n- Default output long edge is 1536px; the service bounds requests to 512–2048px.\n- Clothing generation must preserve the face and identity. Report upstream failures or timeouts instead of silently returning the original image.\n\n## Check ID Photo Compliance\n\n```bash\nscripts/id-check.sh <input-image> [spec-id] [report-json]\n```\n\n- Without `report-json`, the input is treated as a source portrait: the API crop-checks it against the spec and reports practical compliance.\n- With `report-json`, the input is treated as the already-cropped ID photo and the supplied crop metrics are checked.\n- Report failures and warnings plainly; this is a practical QA check, not a government guarantee.\n\n## Optimize Upload Files\n\n```bash\nscripts/optimize.sh <input-image> <output-image> [format] [max-kb] [quality] [resize] [dpi]\n```\n\n- Use for official website upload limits such as JPG under a maximum KB, exact pixel dimensions, or DPI metadata.\n- `format` is `jpg`, `png`, or `webp`; `resize` is `WIDTHxHEIGHT`; lossy formats search quality down to the server default floor when `max-kb` is set.\n\n## Make Print Sheets\n\n```bash\nscripts/print-sheet.sh <output-image> <paper> <input1> [input2 ...]\n```\n\n- Use after generating cropped ID photos when the user wants a printable sheet.\n- `paper` supports common values such as `6x4`, `4x6`, `5x7`, and `a4`. Inputs on a single sheet must have the same pixel size; use `id-pack.sh` for automatic grouping by size.\n\n## Constraints To Surface\n\n- Upload limit is about 15 MB per image.\n- Supported upload formats are JPG, PNG, and WebP.\n- Processing is synchronous; batch jobs are repeated one-image calls.\n- Background replacement is limited to specs that declare `bg_colors`.\n- If a script fails, read its HTTP status and error detail before deciding whether to retry, change arguments, or ask the user for configuration.\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7b98pvjtsm6a4bw8gd87ttbs8a3ycc\",\n  \"slug\": \"motu-color-engine\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1784000147802\n}\n\nFile v1.0.5:references/api.md\n\n# MotuArt Color Engine — API reference\n\nBase URL: `$MCE_API_BASE` (default `https://mce.motu.art`).\nAuth: if enabled, send `X-API-Key: $MCE_API_KEY` (or `Authorization: Bearer $MCE_API_KEY`)\non every endpoint **except** `/v1/health`.\n\n## GET /v1/health\nLiveness/version. No key required.\n\n## GET /v1/styles\nReturns `{ styles: [{id, name, kind, name_zh, ...}], composite_separator, bases, flavours }`.\n`kind` is `base` or `flavour`. Combine as `<flavour><composite_separator><base>`\n(default separator `@`), e.g. `kodak_gold@motu_korean_id`.\n\n## POST /v1/process  (multipart/form-data)\nGrade an image. Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `style` — style id (default `motu_korean_id`).\n- `strength` — look intensity, default `1.0` (0–~1.5).\n- `smooth_strength` — optional M15 pro skin smoothing, `0`–`1`. Omitted/`0` leaves skin\n  texture untouched (default). Softens pores/blemishes only; never reshapes the face.\n- `smooth_texture_retain` — optional, `0`–`1` (default `0.35`), how much natural\n  texture to keep on top of the smoothing. Only used when `smooth_strength` > 0.\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n- `max_long_edge` — cap working long edge (default 1024; server ceiling applies).\n- `mask` — `true` to also return a mask inline (base64).\n- `mask_kind` — mask type when `mask=true` (see below).\n- `crop_spec` — optional M16 purpose crop spec id (see `GET /v1/crop/specs`). When set,\n  the graded output is additionally cropped to that spec (grade + crop in one call).\n  Omitted — full graded frame, uncropped.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin; only used with `crop_spec`. Omitted — edge-replicate padding (the default).\n- `bg_color` — optional background replacement (换底), only used with `crop_spec`: a\n  palette name the spec allows (e.g. `white`/`blue`/`red`), `default` for the spec's\n  standard color, or an explicit `#RRGGBB`. Omitted — original background kept.\n\nResponse JSON:\n```\n{ \"trace_id\", \"style_id\", \"image_base64\", \"content_type\",\n  \"processing_time_ms\", \"quality\": { \"skin_delta_e_to_target\", \"warnings\" },\n  \"report_url\", \"compare_base64\",\n  \"mask_base64\", \"mask_kind\", \"mask_content_type\" }   // mask_* only when mask=true\n```\nDecode `image_base64` to bytes to get the graded image. `skin_delta_e_to_target`\nis the skin ΔE to the target skin (lower = closer).\n\n## POST /v1/mask  (multipart/form-data)\nSegmentation only (decode + parse; **skips grading/render/score** — faster). Fields:\n- `file` (required).\n- `mask_kind` — `skin` (default) | `valid_skin` | `face` | `person`.\n- `max_long_edge` — optional.\n\nReturns the mask as a raw **grayscale PNG** (`Content-Type: image/png`), with header\n`X-MCE-Mask-Kind`. Save the response body directly.\n\n## POST /v1/smooth  (multipart/form-data)\nStandalone M15 pro skin smoothing — runs decode + parse + smoothing + render only,\n**skipping the entire color-grading stack**. Softens pores/blemishes on the detected\nskin region; never reshapes the face or changes color. Fields:\n- `file` (required).\n- `strength` — smoothing amount, default `0.6`.\n- `texture_retain` — how much natural texture to keep, default `0.35`.\n- `radius_frac` — optional blur radius override (fraction of face size).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the smoothed image as a raw payload (default `image/png`), like `/v1/mask`.\n\n## GET /v1/crop/specs\nList the available purpose-crop specs (证件照/形象照/头像 standards). Returns\n`{ specs: [{id, name, name_zh, category, width_px, height_px, width_mm, height_mm,\ndpi, head_ratio, bg_colors, default_bg, description_zh}] }`.\n- `category` — `id_photo` | `portrait` | `avatar`.\n- `width_mm`/`height_mm`/`dpi` — physical print size; `null` for portrait/avatar specs\n  (pixel-only, no print standard).\n- `bg_colors` — `{name: \"#RRGGBB\"}` palette the spec allows for background\n  replacement; `{}` when the spec does not standardize a background (most\n  portrait/avatar specs). `default_bg` is the palette name applied when a caller\n  requests `bg_color=\"default\"`.\n- See `references/crop-specs.md` for a curated overview of the shipped specs.\n\n## POST /v1/crop  (multipart/form-data)\nStandalone M16 purpose-crop. Runs decode + face/head geometry + crop **only** — no\nhuman parsing, no color grading (use `/v1/process` with `crop_spec` to grade and crop\ntogether). Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `spec` — crop spec id (default `one_inch`); see `GET /v1/crop/specs`.\n- `pad_color` — optional `#RRGGBB` padding when the source lacks the spec's required\n  margin. Omitted — edge-replicate padding.\n- `bg_color` — optional background replacement (换底): a palette name the spec\n  allows, `default` for the spec's standard color, or an explicit `#RRGGBB`. Omitted —\n  original background kept.\n- `max_long_edge` — optional working-resolution cap; `0`/omitted means **full source\n  resolution** (crop quality is bounded by source resolution, not a latency budget —\n  unlike `/v1/process`, which defaults to 1024).\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n\nReturns the cropped image as a raw payload (default `image/png`, with the spec's DPI\nembedded), like `/v1/mask`/`/v1/smooth`. The achieved geometry and any warnings are in\nthe `X-MCE-Crop-Info` response \n\nArchive v1.0.4: 21 files, 26154 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (459b), assets/motu-color-engine-logo.svg (2208b), references/api.md (9614b), references/crop-specs.md (4420b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3981b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/outfit.sh (1361b), scripts/outfits.sh (1149b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (3210b), SKILL.md (10281b), _meta.json (136b)\n\nArchive v1.0.3: 19 files, 23037 bytes\n\nFiles: .claude-plugin/plugin.json (410b), agents/openai.yaml (419b), assets/motu-color-engine-logo.svg (2208b), references/api.md (8436b), references/crop-specs.md (4420b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/id-check.sh (1510b), scripts/id-pack.sh (3803b), scripts/mask.sh (860b), scripts/optimize.sh (1311b), scripts/print-sheet.sh (1160b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2474b), SKILL.md (8643b), _meta.json (136b)\n\nArchive v1.0.2: 15 files, 16765 bytes\n\nFiles: .claude-plugin/plugin.json (425b), agents/openai.yaml (419b), assets/motu-color-engine-logo.svg (2208b), references/api.md (5862b), references/crop-specs.md (3900b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/mask.sh (860b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (3248b), SKILL.md (5542b), _meta.json (136b)\n\nArchive v1.0.1: 14 files, 15831 bytes\n\nFiles: .claude-plugin/plugin.json (425b), agents/openai.yaml (290b), references/api.md (5862b), references/crop-specs.md (3900b), references/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/mask.sh (860b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2710b), SKILL.md (5542b), _meta.json (136b)\n\nArchive v1.0.0: 13 files, 16134 bytes\n\nFiles: .claude-plugin/plugin.json (422b), reference/api.md (5861b), reference/crop-specs.md (3900b), reference/styles.md (1414b), scripts/crop-specs.sh (1196b), scripts/crop.sh (1978b), scripts/grade.sh (3183b), scripts/mask.sh (860b), scripts/smooth.sh (1153b), scripts/styles.sh (846b), skill-card.md (2916b), SKILL.md (6980b), _meta.json (136b)","readmeExcerpt":"Skill: MotuArt Color Engine Owner: chancipher Summary: AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, expor Tags: latest:1.0.9 Version history: v1.0.9 | 2026-08-12T07:15:16","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"scripts/grade.sh <input-image> <output-image> [style-id] [strength] [smooth-strength] [smooth-texture-retain] [crop-spec] [bg-color] [pad-color] [lighting-style] [lighting-strength]"},{"language":"bash","snippet":"scripts/smooth.sh <input-image> <output.png> [strength] [texture-retain]"},{"language":"bash","snippet":"scripts/portrait-lighting.sh <input-image> <output.png> [style] [strength]"},{"language":"bash","snippet":"scripts/mask.sh <input-image> <output.png> [mask-kind]"},{"language":"bash","snippet":"scripts/crop.sh <input-image> <output-image> [spec-id] [bg-color] [pad-color]"},{"language":"bash","snippet":"scripts/id-pack.sh <input-image> <output-dir> [specs] [style-id] [smooth-strength] [bg-color] [upload] [print-sheet] [outfit-id] [outfit-long-edge]"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: motu-color-engine\ndescription: AI portrait grading, skin-tone correction, identity-preserving smoothing, mask export, approved clothing replacement, professional AI Headshots generation, and ID/passport/headshot/avatar production through the MotuArt Color Engine HTTP API. Use for retouching portraits, normalizing skin tone, exporting mattes, replacing clothing, preparing identity references and generating professional headshot candidates, cropping to ID/passport/visa specs, replacing ID-photo backgrounds, checking compliance, optimizing uploads, or creating print sheets. Triggers include portrait grading, skin tone, retouch, skin mask, outfit replacement, AI headshots, professional headshot, business portrait, corporate portrait, LinkedIn photo, ID photo, passport photo, visa photo, background swap, print sheet, 调色, 肤色, 磨皮, 蒙版, 人像调色, AI形象照, 职业形象照, 商务形象照, 企业头像, 换装, 证件照, 裁剪, 换底, 合规检查, 排版, 一寸, 二寸.\n---\n\n# Motu Color Engine\n\nUse Motu Color Engine to process portrait images through the hosted HTTP API. Prefer the bundled scripts in `scripts/` over hand-written `curl` calls unless the user explicitly needs raw API details.\n\nThe engine preserves identity. Do not describe it as slimming, reshaping, face swapping, or changing facial structure. Skin smoothing only softens pores and blemishes inside detected skin regions. Cropping repositions and pads to a spec; it never stretches or compresses the face.\n\n## Setup\n\n- Require `curl` and `python3`.\n- Read `MCE_API_BASE` from the environment; default is `https://mce.motu.art`.\n- Read `MCE_API_KEY` from the environment; send it only as `X-API-Key`.\n- If the key is missing, direct the user to `https://mce.motu.art/account` (English: `/en/account`) to sign in by email and create one. Ask them to export it securely in their own environment; do not ask them to paste the full key into chat.\n- Never hard-code, print, log, commit, or expose API keys in browser/client code. The full key is shown once and can be rotated or revoked from the account page.\n- Request only the scopes needed: `catalog:read` for portrait/ID discovery, `portrait:process` for grading/smoothing/masks, `id-photo:process` for ID-photo workflows, `outfit:process` for outfit replacement, and `headshot:process` for private AI Headshots projects and generation. An ID package with an outfit needs both `id-photo:process` and `outfit:process`.\n- Processing calls consume account credits; catalog discovery does not. Surface `402 insufficient_credits` instead of retrying.\n- Check service health with `curl -sS \"${MCE_API_BASE:-https://mce.motu.art}/v1/health\"` when diagnosing connectivity.\n\n## Choose The Workflow\n\n- Use `scripts/grade.sh` when the user wants color grading, skin-tone correction, a film/commercial look, or grading plus optional crop.\n- Use `scripts/smooth.sh` when the user wants smoothing only with no color or white-balance change.\n- Use `scripts/portrait-lighting.sh` when the user wants visibly more dimensional portrait lighting, a br"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7b98pvjtsm6a4bw8gd87ttbs8a3ycc\",\n  \"slug\": \"motu-color-engine\",\n  \"version\": \"1.0.9\",\n  \"publishedAt\": 1786518916479\n}"},{"path":"references/api.md","content":"# MotuArt Color Engine — API reference\n\nBase URL: `$MCE_API_BASE` (default `https://mce.motu.art`).\nAuth: create a key at `https://mce.motu.art/account` (English: `/en/account`), then send\n`X-API-Key: $MCE_API_KEY` (or `Authorization: Bearer $MCE_API_KEY`) on private and\nprocessing endpoints. `/v1/health` and public Headshots discovery endpoints do not need\na key. The full key is displayed once; store it securely and rotate or revoke it from\nthe account page if exposed.\n\nScopes:\n- `catalog:read` — styles, crop specs and approved outfits.\n- `portrait:process` — process, smooth and mask.\n- `id-photo:process` — crop, id-pack, id-check, optimize and print-sheet.\n- `outfit:process` — standalone outfit replacement. Also required in addition to\n  `id-photo:process` or `portrait:process` when those requests include `outfit_id`.\n- `headshot:process` — private AI Headshots projects, reference preparation,\n  generation, candidates, post-processing, and exports. See `headshots-api.md`.\n\nSuccessful processing calls consume account credits; catalog requests do not. A `402`\nresponse uses `detail.code=\"insufficient_credits\"` and includes `required`, `available`,\nand whether the request included outfit replacement.\n\n## GET /v1/health\nLiveness/version. No key required.\n\n## GET /v1/styles\nReturns `{ styles: [{id, name, kind, name_zh, ...}], composite_separator, bases, flavours }`.\n`kind` is `base` or `flavour`. Combine as `<flavour><composite_separator><base>`\n(default separator `@`), e.g. `kodak_gold@motu_korean_id`.\n\n## POST /v1/process  (multipart/form-data)\nGrade an image. Fields:\n- `file` (required) — image upload (JPG/PNG/WebP, ≤ ~15 MB).\n- `style` — style id (default `motu_korean_id`).\n- `strength` — look intensity, default `1.0` (0–~1.5).\n- `smooth_strength` — optional M15 pro skin smoothing, `0`–`1`. Omitted/`0` leaves skin\n  texture untouched (default). Softens pores/blemishes only; never reshapes the face.\n- `smooth_texture_retain` — optional, `0`–`1` (default `0.35`), how much natural\n  texture to keep on top of the smoothing. Only used when `smooth_strength` > 0.\n- `portrait_lighting_style` — optional M17 light-sculpting preset:\n  `natural_dimension`, `soft_luminous`, or `studio_definition`. Omit it and all\n  `portrait_lighting_*` fields to keep the existing grading output unchanged.\n- `portrait_lighting_strength` — optional `0`–`1`; omitted uses the selected preset's\n  calibrated strength. Supplying this without a style uses `natural_dimension`.\n- `portrait_lighting_face_light_balance`, `portrait_lighting_subject_separation`,\n  `portrait_lighting_local_contrast`, `portrait_lighting_skin_protection`, and\n  `portrait_lighting_highlight_protection` — optional advanced overrides, each `0`–`1`.\n- `output_format` — `png` (default) | `jpeg` | `webp`.\n- `quality` — 1–100 for lossy formats (default 90).\n- `max_long_edge` — cap working long edge (default 1024; server ceiling applies).\n- `mask` — `true` to also return a mask inline (base64).\n- `mask_kind` — mask"},{"path":"references/crop-specs.md","content":"# MotuArt Color Engine — crop specs overview (M16 purpose crop)\n\nThe live catalog is authoritative — run `scripts/crop-specs.sh` (or `GET\n/v1/crop/specs`) to list current ids/sizes. This is a quick orientation to the\nthree categories and the shipping specs.\n\n## Three categories\n\n- **id_photo** — official ID/passport/visa/license photo standards. Fixed pixel size\n  + physical `width_mm`/`height_mm` + `dpi` (embedded on save, so exports print at the\n  right physical size). Most declare a `bg_colors` palette for background replacement\n  (换底) since these documents require a specific solid background. ID-photo specs may\n  also include `compliance`, `upload`, and `print` metadata used by `id-pack`,\n  `id-check`, upload optimization, and print-sheet layout.\n- **portrait** — professional/editorial portrait framings (headshot to full body).\n  Pixel-only, no print standard, no background palette (original background kept).\n- **avatar** — square social-avatar framing. Pixel-only, no background palette.\n\nPass only a `spec` id — the engine auto-detects the face/head and positions it to\nthat spec's `head_ratio` (crown-to-chin as a fraction of output height) and margins;\nyou never draw a crop box by hand.\n\n## id_photo specs (fixed background palette, mostly white/blue/red)\n\n| id | Use | Size | Print |\n| --- | --- | --- | --- |\n| `one_inch` | 简历/证件 general 1-inch | 295×413px | 25×35mm@300dpi |\n| `two_inch` | Standard 2-inch | 413×579px | 35×49mm@300dpi |\n| `small_two_inch` | Small 2-inch (passport/visa common) | 413×531px | 35×45mm@300dpi |\n| `small_one_inch` | Driver's license / some certificates | 260×378px | 22×32mm@300dpi |\n| `big_two_inch` | Diploma (blue background common) | 413×626px | 35×53mm@300dpi |\n| `id_card_cn` | CN ID card / social security card (GA 461) | 358×441px | 26×32mm@350dpi |\n| `shanghai_compulsory_education_cn` | 上海义务教育入学免冠证件照 | 272×354px | 20×26mm@350dpi |\n| `college_graduation_image_cn` | 大学生毕业图像信息采集免冠证件照 | 480×640px | 41×54mm@300dpi |\n| `national_k12_student_status_cn` | 全国中小学生学籍电子版照片 | 358×441px | 26×32mm@350dpi |\n| `passport_cn` | CN passport / HK-Macau-Taiwan permit / CN visa | 390×567px | 33×48mm@300dpi |\n| `us_visa` | US visa 2×2 | 600×600px | 51×51mm@300dpi |\n| `schengen_visa` | Schengen/UK visa | 413×531px | 35×45mm@300dpi |\n| `japan_visa` | Japan visa | 531×531px | 45×45mm@300dpi |\n| `canada_visa` | Canada visa/immigration | 590×826px | 50×70mm@300dpi |\n| `china_visa` | China visa printed photo | 390×567px | 33×48mm@300dpi; digital upload uses a separate crop |\n| `us_passport_printed` | US passport (paper application) | 600×600px | 51×51mm@300dpi |\n| `japan_passport` | Japan passport | 413×531px | 35×45mm@300dpi |\n| `canada_passport_printed` | Canada passport (paper application) | 590×826px | 50×70mm@300dpi |\n| `uk_passport_printed` | UK printed passport photo | 413×531px | 35×45mm@300dpi |\n| `uk_visa` | UK visa or permission digital photo | 600×750px minimum | JPG/JPEG, 50KB–6MB |\n| `malaysia_passport_photo` / `malaysia_evisa`"},{"path":"references/headshots-api.md","content":"# AI Headshots API\n\nUse this reference for the staged professional-headshot workflow. Use\n`scripts/headshots.sh` for normal operation instead of assembling requests manually.\n\n## Authentication and ownership\n\nSend an account API key with the `headshot:process` scope:\n\n```http\nX-API-Key: $MCE_API_KEY\n```\n\n`Authorization: Bearer $MCE_API_KEY` is also accepted. The account user becomes the\nowner of every project and private asset. Another account receives a not-found response\ninstead of access to that data. Server environment keys are not sufficient without a\nuser identity.\n\nThese discovery endpoints are public:\n\n- `GET /v1/headshots/catalog?locale=en`\n- `GET /v1/headshots/showcases?locale=en`\n- `GET /v1/headshots/showcases/{showcase_id}?locale=en`\n- `GET /v1/headshots/scenes/{scene_id}?locale=en`\n\nSupported published locales are `en`, `zh-CN`, `ja-JP`, `ko-KR`, `th-TH`, `vi-VN`,\n`ms-MY`, `id-ID`, and `fil-PH`. Short content-language aliases are accepted where documented.\n\n## Workflow\n\nKeep the identifiers returned by each stage:\n\n```text\nproject_id -> preview_id -> reference_id -> job_id -> candidate_id\n                                                   -> render_id -> export_id\n```\n\nDo not submit generation before the user has reviewed and confirmed the reference\npreview. Generation consumes credits; preparation and discovery do not.\n\n## Prepare a reference\n\n### Create or restore a project\n\n`POST /v1/headshots/projects` is multipart form data:\n\n- `image` — required JPG, PNG, or WebP, subject to the service upload limit.\n- `scene_id` — optional live scene id.\n- `entry_source` — normally `direct_upload`, or `scene_gallery` when a scene led to the upload.\n\nDo not combine `entry_source=direct_upload` with `scene_id`. Use `scene_gallery` when sending\na scene id; `scene_gallery` requires one.\n\nUse `POST /v1/headshots/projects/{project_id}/source` with an `image` part to replace\nthe source while preserving the project history. Use `GET /v1/headshots/projects/{id}`\nto restore a project, `GET /v1/headshots/projects` to list projects, and `DELETE` on the\nproject resource to remove it and its private derivatives.\n\n### Inspect the source\n\n`POST /v1/headshots/projects/{project_id}/inspect` returns practical eligibility:\n\n```json\n{\"eligible\": true, \"status\": \"ready\", \"reasons\": [], \"warnings\": []}\n```\n\nStop when `eligible` is false. Surface warnings before creating a preview.\n\nSet the garment catalog preference with\n`POST /v1/headshots/projects/{project_id}/garment-preference`:\n\n```json\n{\"garment_preference\": \"female\"}\n```\n\nThe value is `male`, `female`, or `null` to clear it. This selects catalog variants; it\ndoes not infer or alter gender identity.\n\n### Grade, smooth, and crop the reference preview\n\n`POST /v1/headshots/projects/{project_id}/previews` accepts JSON:\n\n```json\n{\n  \"skin_base_id\": \"motu_business_neutral\",\n  \"smoothing_strength\": 0.2,\n  \"crop_spec_id\": \"profile_4x5\",\n  \"crop_anchor\": \"auto\",\n  \"crop_rotation\": 0\n}\n```\n\n- `skin_base_id` — allowed po"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2547,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T05:09:30.627Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:43:37.173Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}