开发者

把 MotuArt 接进你的工作流

MCE 的人像调色、皮肤分割、专业磨皮、精选换装、AI 职业形象照和证件照交付能力，可通过 Agent Skill、命令行或 HTTP API 调用。

作为 Agent Skill 使用

这是标准的 Agent Skill，兼容 Claude Code、Codex CLI、ZCode、OpenClaw、Augment、Windsurf 等。下载到对应 agent 的 skills 目录后，agent 会在你要求调色、导出蒙版、磨皮、制作 AI 职业形象照或证件照时调用。

Claude Code：一行安装（plugin marketplace）

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

支持的 Agent 与安装目录

下载 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"

配置环境变量

登录账户页创建 API Key 后，设置下面两个环境变量。完整 Key 只显示一次，请立即安全保存，不要写进源码或前端代码。

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

常用命令

脚本位于 skill 的 scripts/ 目录。headshots.sh 以准备参考图、确认、提交异步任务、查询、下载、后期和导出的显式阶段制作职业形象照；不会自动确认参考图或选择候选图。

# 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_...

直接用 HTTP API

不经过 skill 也可以直接调用。私有与处理端点需带 X-API-Key；/v1/health 和 Headshots 的 catalog、showcases、scenes 发现接口公开。账户 API Key 只应选择需要的最小权限。

AI Headshots 分阶段 API

上传照片并确认人物预览后，选择场景、姿势、服装和背景开始生成。任务会在后台处理，可随时查看进度、下载效果图，再按需要调色、裁切和导出。所有私人图片只属于当前 API Key 对应的账户。

GET/v1/headshots/catalog获取可以选择的场景、姿势、服装和背景

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/projects上传一张人物照片并开始新项目

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}/inspect检查照片是否只有一人、足够清晰且适合制作

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}/previews按肤色、磨皮和裁剪设置生成人物预览

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}/image获取人物预览图，供用户确认效果

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}/references保存用户确认的预览图，供后续生成使用

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/recommendation补齐未选择的姿势、服装、背景和构图，返回可直接生成的方案

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/jobs使用确认的人物和制作方案开始生成形象照

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}查看处理进度、失败原因和已经完成的效果图

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}/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/styles获取这张效果图可以使用的后期调色风格

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}/renders给选中的效果图应用后期调色

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}/image下载调色后的效果图

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}/exports按指定比例、尺寸和格式生成交付文件

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}/download下载最终交付文件

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>

人物库 API

可选的辅助接口：复用以前确认的人物、在现有项目中更换人物，或管理人物库。首次制作 Headshot 不需要调用。

GET/v1/headshots/person-references查看以前保存、可以再次使用的人物

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-reference使用以前保存的人物开始一个新项目

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-reference在当前项目中更换人物，并保留已有结果

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}从人物库移除人物，不删除已有项目

Input

Path: person_reference_id

Output

204 No Content; project history remains

Request example

person_reference_id=hperson_123

Response example

204 No Content

人像与证件照 API

通过同一套鉴权 API 完成人像调色、皮肤蒙版、磨皮、精选换装、证件照交付包与规格导出。

GET/v1/styles查看可以使用的人像调色风格

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/process上传人像，返回调色后的图片和质量报告

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-lighting单独增强人像明暗层次与主体分离，不改变人物身份和几何结构

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/smooth只做自然磨皮，不改变原图颜色

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/mask导出皮肤、人脸或人物区域的黑白蒙版图

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/specs查看证件照、头像和形象照可以使用的裁切规格

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/outfits查看可以使用的男装、女装、童装和通用服装

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/outfit为照片更换指定的精选服装

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/crop按指定规格裁切照片，也可以同时更换背景色

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-pack一次生成证件照母版、不同尺寸、上传文件和打印排版

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-check检查照片尺寸、头部比例、人脸和背景是否符合指定规格

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/optimize按尺寸、DPI、格式和文件大小生成可以上传的图片

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-sheet把同尺寸证件照排版到指定相纸或纸张

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>

限制：单图 ≤ 15MB，支持 JPG / PNG / WebP。人像与证件照处理为同步；Headshots 生成为异步任务。证件照交付包返回 base64 JSON，较大批量建议拆分规格。

获取 API Key

使用邮箱验证码登录或注册，进入账户页创建独立 Key。为每个应用分别命名并选择最小必要权限；Key 可随时轮换或撤销，调用消耗账户额度。

  1. 1.邮箱验证码登录或注册
  2. 2.创建 Key 并选择权限
  3. 3.立即复制并安全保存
  4. 4.设置 MCE_API_KEY 后调用

权限范围

catalog:read

查询风格、证件照规格和允许的服装

portrait:process

人像调色、磨皮和蒙版处理

id-photo:process

证件照裁切、检查、优化、排版和交付包

outfit:process

独立换装；证件照交付包带换装时也必须选择

headshot:process

AI 职业形象照的私有项目、参考图准备、生成、候选图、后期和导出

登录并创建 Key
← 返回首页
开发者 | MotuArt Color Engine API 与 Agent Skill