Developers

Bring MotuArt into your workflow

MotuArt Color Engine exposes portrait grading, skin segmentation, pro smoothing, curated outfit replacement, professional AI Headshots and ID-photo delivery through an Agent Skill, CLI or HTTP API.

Use as an Agent Skill

This standard Agent Skill works with Claude Code, Codex CLI, ZCode, OpenClaw, Augment, Windsurf and more. Install it in the agent's skills directory to grade portraits, export masks, smooth skin, create professional AI Headshots or make ID photos.

Claude Code: one-line install (plugin marketplace)

/plugin marketplace add motu-art/motu-skills
/plugin install motu-color-engine@motu-skills

Supported agents & install paths

Download skill (.tar.gz)
SKILLS_DIR=~/.claude/skills
mkdir -p "$SKILLS_DIR"

# download + extract in one line
curl -fsSL https://mce.motu.art/downloads/motu-color-engine-skill.tar.gz \
  | tar -xz -C "$SKILLS_DIR"

# ...or, if you downloaded the archive from this page:
tar -xzf motu-color-engine-skill.tar.gz -C "$SKILLS_DIR"

Configure environment

Create an API key from your account, then set these two environment variables. The full key is shown once; store it securely and never put it in source or client-side code.

export MCE_API_BASE=https://mce.motu.art
export MCE_API_KEY=<your-key>

Common commands

Scripts live under the skill scripts/ folder. headshots.sh creates professional portraits in explicit prepare, confirm, asynchronous submit, status, download, post-process and export stages; it never auto-confirms a reference or selects a candidate.

# list available styles
scripts/styles.sh

# grade a portrait (style + strength optional)
scripts/grade.sh photo.jpg graded.png kodak_gold 1.0

# grade with light smoothing enabled
scripts/grade.sh photo.jpg graded.png kodak_gold 1.0 0.6 0.35

# sculpt portrait lighting only (identity and geometry preserved)
scripts/portrait-lighting.sh photo.jpg lit.png natural_dimension 0.70

# grade + smooth + portrait lighting in one request
scripts/grade.sh photo.jpg finished.png kodak_gold 1.0 0.2 0.35 "" "" "" natural_dimension 0.70

# smooth only, no color grading
scripts/smooth.sh photo.jpg smoothed.png 0.6 0.35

# export just the skin mask (grayscale PNG)
scripts/mask.sh photo.jpg skin.png skin

# browse curated outfits and replace clothing
scripts/outfits.sh
scripts/outfit.sh photo.jpg outfitted.png business_navy_suit 1536

# generate an ID-photo delivery package
scripts/id-pack.sh photo.jpg out passport_cn,one_inch motu_business_neutral 0.35 default true 6x4 business_navy_suit 1536

# staged AI Headshots: prepare, approve, submit, then download
scripts/headshots.sh catalog en
scripts/headshots.sh prepare photo.jpg headshot-work --scene professional_profile --smoothing 0.2
scripts/headshots.sh confirm headshot-work
scripts/headshots.sh generate headshot-work --batch-size 4
scripts/headshots.sh status headshot-work
scripts/headshots.sh download headshot-work

# create a lighting render from a generated Headshot candidate
scripts/headshots.sh light headshot-work --candidate 1 --style natural_dimension --strength 0.70

# reuse a confirmed person in a new or existing project
scripts/headshots.sh people
scripts/headshots.sh start-person hperson_... another-headshot-work --scene professional_profile
scripts/headshots.sh use-person headshot-work hperson_...

# remove only the reusable library entry (projects and history remain)
scripts/headshots.sh remove-person hperson_...

Or call the HTTP API

Call the API directly without the skill. Private and processing endpoints require X-API-Key; /v1/health and Headshots catalog, showcase and scene discovery are public. Grant each account key only the scopes it needs.

Staged AI Headshots API

Create a project and inspect the source, then grade skin tone, optionally smooth and crop a reference preview. After the user confirms that reference, submit an asynchronous generation job, query its status, download candidates, and explicitly post-process or export a selection. Private resources belong to the API-key account.

GET/v1/headshots/catalogPublic scenes, poses, outfits, backgrounds, generation styles and compatibility

Input

Query: locale?

Output

scenes, poses, outfits, backgrounds, generation_styles, compatibility

Request example

?locale=zh-CN

Response example

{
  "scenes": [{ "id": "professional_profile" }],
  "poses": [...], "outfits": [...], "backgrounds": [...]
}
POST/v1/headshots/projectsUpload a source portrait and create a Headshots project

Input

multipart: image; scene_id?; entry_source?

Output

project_id, status, scene_id, source_image_url

Request example

image=@photo.jpg
scene_id=professional_profile
entry_source=scene_gallery

Response example

{
  "project_id": "hproj_123",
  "status": "inspecting",
  "scene_id": "professional_profile",
  "source_image_url": "/v1/headshots/projects/hproj_123/source/image"
}
POST/v1/headshots/projects/{project_id}/inspectCheck whether the source portrait is eligible for reference preparation

Input

Path: project_id

Output

eligible, status, reasons[], warnings[]

Request example

project_id=hproj_123

Response example

{
  "eligible": true,
  "status": "ready",
  "reasons": [],
  "warnings": []
}
POST/v1/headshots/projects/{project_id}/previewsCreate a graded, optionally smoothed and cropped reference preview

Input

JSON: skin_base_id; smoothing_strength?; crop_spec_id; crop_anchor?; crop_zoom?; crop_offset_x/y?; crop_x/y/width/height?; crop_rotation?

Output

preview_id, parameters, image: content_type, size_bytes, width, height, url

Request example

{
  "skin_base_id": "motu_business_neutral",
  "smoothing_strength": 0.2,
  "crop_spec_id": "profile_4x5",
  "crop_anchor": "auto"
}

Response example

{
  "preview_id": "hprev_123",
  "parameters": { "crop_spec_id": "profile_4x5" },
  "image": {
    "content_type": "image/png",
    "size_bytes": 482310,
    "width": 1200,
    "height": 1500,
    "url": "/v1/headshots/projects/hproj_123/previews/hprev_123/image"
  }
}
GET/v1/headshots/projects/{project_id}/previews/{preview_id}/imageDownload the private preview image for user review

Input

Path: project_id, preview_id

Output

Private preview image bytes

Request example

project_id=hproj_123
preview_id=hprev_123

Response example

200 OK
Content-Type: image/png
<binary image bytes>
POST/v1/headshots/projects/{project_id}/referencesConfirm an approved preview as an immutable identity reference

Input

JSON: preview_id

Output

reference_id, version, parameters

Request example

{ "preview_id": "hprev_123" }

Response example

{
  "reference_id": "href_123",
  "version": 1,
  "parameters": { "crop_spec_id": "profile_4x5", "smoothing_strength": 0.2 }
}
POST/v1/headshots/recommendationResolve a partial selection into a complete compatible generation plan

Input

JSON: project_id, reference_id; scene_id?; generation_style_id?; pose_id?; outfit_id?; background_id?; output_ratio?; framing?

Output

Complete compatible generation configuration, compatibility changes

Request example

{
  "project_id": "hproj_123",
  "reference_id": "href_123",
  "scene_id": "professional_profile",
  "output_ratio": "4:5",
  "framing": "auto"
}

Response example

{
  "scene_id": "professional_profile",
  "generation_style_id": "natural_editorial",
  "pose_id": "confident_front",
  "outfit_id": "business_navy_suit",
  "background_id": "studio_warm_gray",
  "output_ratio": "4:5",
  "framing": "half_body"
}
POST/v1/headshots/jobsSubmit asynchronous Headshots generation from a confirmed reference and complete configuration

Input

Header: Idempotency-Key · JSON: confirmed reference + complete configuration + batch_size

Output

202 Accepted: job_id, status, requested_count

Request example

Idempotency-Key: job-2026-001

{
  "project_id": "hproj_123",
  "reference_id": "href_123",
  "scene_id": "professional_profile",
  "generation_style_id": "natural_editorial",
  "pose_id": "confident_front",
  "outfit_id": "business_navy_suit",
  "background_id": "studio_warm_gray",
  "output_ratio": "4:5",
  "framing": "half_body",
  "batch_size": 4
}

Response example

{
  "job_id": "hjob_123",
  "project_id": "hproj_123",
  "status": "queued",
  "batch_size": 4,
  "credit_cost": 4
}
GET/v1/headshots/jobs/{job_id}Query job state and ready professional-headshot candidates

Input

Path: job_id

Output

status, candidates[], failure_reason? · terminal: completed | partially_completed | failed | cancelled

Request example

job_id=hjob_123

Response example

{
  "job_id": "hjob_123",
  "status": "completed",
  "candidates": [{ "candidate_id": "hcand_123", "ordinal": 1, "status": "ready" }],
  "failure_reason": null
}
GET/v1/headshots/jobs/{job_id}/candidates/{candidate_id}/imageDownload a generated candidate image

Input

Path: job_id, candidate_id

Output

Private candidate image bytes

Request example

job_id=hjob_123
candidate_id=hcand_123

Response example

200 OK
Content-Type: image/jpeg
<binary image bytes>
GET/v1/headshots/postprocess/stylesList post-processing styles compatible with the reference

Input

Query: reference_id; locale?

Output

styles[]: id, base_id, flavour_id?, localized labels

Request example

?reference_id=href_123&locale=zh-CN

Response example

{
  "styles": [{ "id": "business_neutral", "base_id": "motu_business_neutral", "flavour_id": null }]
}
POST/v1/headshots/candidates/{candidate_id}/rendersCreate a post-processed render from a selected candidate

Input

Path: candidate_id · JSON: grade uses base_id/flavour_id; portrait lighting uses render_kind, lighting_style, lighting_strength?, source_render_id?

Output

immutable render_id, render_kind, source_render_id, applied grade or lighting settings, image_url

Request example

Grade only:
{
  "base_id": "motu_business_neutral",
  "flavour_id": null
}

Grade + portrait lighting in one pass:
{
  "render_kind": "portrait_lighting",
  "base_id": "motu_business_neutral",
  "flavour_id": null,
  "lighting_style": "natural_dimension",
  "lighting_strength": 0.70
}

Response example

{
  "render_id": "hrender_123",
  "render_kind": "portrait_lighting",
  "source_render_id": null,
  "base_id": "motu_business_neutral",
  "lighting_style": "natural_dimension",
  "lighting_strength": 0.70,
  "image_url": "/v1/headshots/renders/hrender_123/image"
}
GET/v1/headshots/renders/{render_id}/imageDownload the post-processed render

Input

Path: render_id

Output

Private rendered image bytes

Request example

render_id=hrender_123

Response example

200 OK
Content-Type: image/png
<binary image bytes>
POST/v1/headshots/candidates/{candidate_id}/exportsCreate a controlled crop and format export

Input

Path: candidate_id · JSON: source_type; render_id?; crop_spec_id?; format?; quality?; crop rectangle/offsets?

Output

export_id, download_url, output metadata

Request example

{
  "source_type": "render",
  "render_id": "hrender_123",
  "crop_spec_id": "profile_4x5",
  "format": "jpeg",
  "quality": 92
}

Response example

{
  "export_id": "hexport_123",
  "download_url": "/v1/headshots/exports/hexport_123/download",
  "format": "jpeg"
}
GET/v1/headshots/exports/{export_id}/downloadDownload the final exported Headshot

Input

Path: export_id

Output

Final exported image bytes

Request example

export_id=hexport_123

Response example

200 OK
Content-Type: image/jpeg
<final exported image bytes>

Person library API

Optional helpers for reusing confirmed people, switching the person in a project, or managing the library. They are not required for the default Headshot flow.

GET/v1/headshots/person-referencesList reusable confirmed people and their private previews

Input

Query: limit?

Output

people[]: person_reference_id, garment_preference, created_at, last_used_at, image_url

Request example

?limit=20

Response example

{
  "people": [{
    "person_reference_id": "hperson_123",
    "garment_preference": "female",
    "created_at": "2026-08-11T10:00:00Z",
    "last_used_at": "2026-08-11T10:30:00Z",
    "image_url": "/v1/headshots/person-references/hperson_123/image"
  }]
}
POST/v1/headshots/projects/from-person-referenceStart a new project from a saved person

Input

JSON: person_reference_id; scene_id?

Output

project_id, reference_id, status

Request example

{
  "person_reference_id": "hperson_123",
  "scene_id": "professional_profile"
}

Response example

{ "project_id": "hproj_456", "reference_id": "href_456", "status": "ready" }
POST/v1/headshots/projects/{id}/person-referenceSwitch the person in an existing project while preserving history

Input

Path: project_id · JSON: person_reference_id

Output

project_id, reference_id, active person reference

Request example

{ "person_reference_id": "hperson_123" }

Response example

{ "project_id": "hproj_123", "reference_id": "href_456" }
DELETE/v1/headshots/person-references/{id}Soft-delete only the library entry; projects remain intact

Input

Path: person_reference_id

Output

204 No Content; project history remains

Request example

person_reference_id=hperson_123

Response example

204 No Content

Portrait and ID-photo API

Use the same authenticated API for portrait grading, skin masks, smoothing, curated outfits, ID-photo packages and delivery exports.

GET/v1/stylesList available styles (base / flavour)

Input

No body

Output

styles[], bases[], flavours[], composite_separator

Request example

No parameters

Response example

{
  "styles": [{ "id": "kodak_gold", "kind": "flavour" }],
  "composite_separator": "@"
}
POST/v1/processUpload a portrait → graded image + quality report (skin ΔE, optional smooth_strength)

Input

multipart: file; style?; strength?; smooth_strength?; smooth_texture_retain?; portrait_lighting_style?; portrait_lighting_strength?; crop_spec?; bg_color?; output_format?; quality?

Output

trace_id, image_base64, content_type, quality, report_url; report includes lighting metrics when enabled

Request example

file=@photo.jpg
style=kodak_gold
strength=1.0
smooth_strength=0.2
portrait_lighting_style=natural_dimension
portrait_lighting_strength=0.55
output_format=png

Response example

{
  "trace_id": "trace_123",
  "style_id": "kodak_gold",
  "image_base64": "...",
  "content_type": "image/png",
  "quality": { "skin_delta_e_to_target": 3.2, "warnings": [] },
  "report_url": "/v1/report/trace_123"
}

GET report_url →
{
  "metrics": {
    "portrait_lighting": {
      "style": "natural_dimension",
      "requested_strength": 0.55,
      "max_applied_ev": 0.31
    }
  }
}
POST/v1/portrait-lightingEnhance portrait depth and subject separation without changing identity or geometry

Input

multipart: file; style?; strength?; face_light_balance?; subject_separation?; local_contrast?; skin_protection?; highlight_protection?; max_long_edge?; output_format?; quality?

Output

Processed image bytes + X-MCE-Trace-Id and X-MCE-Lighting-Info headers

Request example

file=@portrait.jpg
style=natural_dimension
strength=0.70
max_long_edge=1800
output_format=png

Response example

200 OK
Content-Type: image/png
X-MCE-Trace-Id: trace_123
X-MCE-Lighting-Info: {"style":"natural_dimension","strength":0.70,"max_applied_ev":0.31,"warnings":[]}
<processed image bytes>
POST/v1/smoothUpload a portrait → smoothing-only PNG (no color change)

Input

multipart: file; strength?; texture_retain?; output_format?; quality?

Output

Smoothed image bytes

Request example

file=@photo.jpg
strength=0.6
texture_retain=0.35

Response example

200 OK
Content-Type: image/png
<smoothed image bytes>
POST/v1/maskUpload a portrait → skin mask PNG (mask_kind / max_long_edge)

Input

multipart: file; mask_kind?; max_long_edge?

Output

Grayscale mask PNG + X-MCE-Mask-Kind

Request example

file=@photo.jpg
mask_kind=skin
max_long_edge=1536

Response example

200 OK
Content-Type: image/png
X-MCE-Mask-Kind: skin
<grayscale mask bytes>
GET/v1/crop/specsList ID photo, portrait and avatar crop specs with background rules

Input

No body

Output

specs[]: dimensions, DPI, head ratio, background rules

Request example

No parameters

Response example

{
  "specs": [{ "id": "passport_cn", "width_px": 390, "height_px": 567, "dpi": 300 }]
}
GET/v1/outfitsList curated outfits with men, women, kids and unisex categories and previews

Input

No body

Output

Approved outfits[] with category, availability and preview

Request example

No parameters

Response example

{
  "outfits": [{ "id": "business_navy_suit", "category": "male", "available": true }]
}
POST/v1/outfitReplace clothing with an allowed outfit_id and return the processed PNG

Input

multipart: file; outfit_id; long_edge?

Output

task_id, outfit_id, image_base64, content_type, processing_time_ms

Request example

file=@photo.jpg
outfit_id=business_navy_suit
long_edge=1536

Response example

{
  "task_id": "task_123",
  "outfit_id": "business_navy_suit",
  "image_base64": "...",
  "content_type": "image/png"
}
POST/v1/cropSingle-spec crop and background replacement with DPI and crop report headers

Input

multipart: file; spec; pad_color?; bg_color?; max_long_edge?; output_format?; quality?

Output

Cropped image bytes + X-MCE-Crop-Info

Request example

file=@photo.jpg
spec=passport_cn
bg_color=default
output_format=jpeg

Response example

200 OK
Content-Type: image/jpeg
X-MCE-Crop-Info: {"spec_id":"passport_cn","warnings":[]}
<cropped image bytes>
POST/v1/id-packID photo package: optional outfit, master, multi-spec images, upload files, print sheets and compliance

Input

multipart: file; specs; style?; smoothing?; bg_color?; outfit_id?; upload?; print_sheet?

Output

master_base64, items[], compliance, upload files?, print_sheets?

Request example

file=@photo.jpg
specs=passport_cn,one_inch
style=motu_business_neutral
bg_color=default
upload=true
print_sheet=6x4

Response example

{
  "trace_id": "trace_123",
  "master_base64": "...",
  "items": [{ "spec_id": "passport_cn", "image_base64": "...", "compliance": { "status": "pass" } }]
}
POST/v1/id-checkCheck size, head ratio, face detection and background status against a spec

Input

multipart: file; spec; report_json?; bg_color?

Output

ok, status, checks, warnings, errors

Request example

file=@passport.jpg
spec=passport_cn
bg_color=default

Response example

{
  "ok": true,
  "status": "pass",
  "checks": {},
  "warnings": [],
  "errors": []
}
POST/v1/optimizeExport upload-ready files by size, DPI, format and file-size target

Input

multipart: file; output_format?; max_kb?; quality?; min_quality?; resize?; dpi?

Output

Optimized image bytes + X-MCE-Export-Info

Request example

file=@photo.png
output_format=jpeg
max_kb=200
resize=600x800
dpi=300

Response example

200 OK
Content-Type: image/jpeg
X-MCE-Export-Info: {"width":600,"height":800,"size_kb":184}
<optimized image bytes>
POST/v1/print-sheetLayout same-size ID photos on 6x4, 4x6, A4 or custom paper

Input

multipart: files[]; paper?; dpi?; margin_mm?; gap_mm?; cut_lines?; output_format?

Output

Print-sheet image bytes + X-MCE-Print-Sheet-Info

Request example

files=@one-inch.jpg
paper=6x4
dpi=300
cut_lines=true

Response example

200 OK
Content-Type: image/png
X-MCE-Print-Sheet-Info: {"paper":"6x4","dpi":300}
<print sheet bytes>

Limits: ≤ 15MB per image, JPG / PNG / WebP. Portrait and ID-photo processing is synchronous; Headshots generation runs as an asynchronous job. ID-photo packages return base64 JSON, so split very large batches.

Get an API key

Sign in or register with an email verification code, then create a dedicated key in your account. Name each integration and grant only the scopes it needs. Keys can be rotated or revoked at any time, and calls consume account credits.

  1. 1.Sign in or register by email
  2. 2.Create a key and select scopes
  3. 3.Copy and store it immediately
  4. 4.Set MCE_API_KEY and call the API

Permission scopes

catalog:read

Read styles, ID-photo specs and approved outfits

portrait:process

Portrait grading, smoothing and mask processing

id-photo:process

ID-photo crop, check, optimize, print and delivery packages

outfit:process

Standalone outfit replacement; also required when id-pack includes an outfit

headshot:process

Private AI Headshots projects, reference preparation, generation, candidates, post-processing and exports

Sign in and create a key
← Back to home
Developers | MotuArt Color Engine API & Agent Skill