개발자

MotuArt를 워크플로에 통합하세요

MotuArt Color Engine은 포트레이트 그레이딩, 피부 세그멘테이션, 프로 스무딩, 엄선 의상 변경, 전문 AI Headshots, 증명사진 납품을 Agent Skill, CLI 또는 HTTP API로 제공합니다.

Agent Skill로 사용하기

Claude Code, Codex CLI, ZCode, OpenClaw, Augment, Windsurf 등과 호환되는 표준 Agent Skill입니다. skills 디렉터리에 설치하면 그레이딩, 마스크, 스무딩, 전문 AI Headshots 및 증명사진을 요청할 수 있습니다.

Claude Code: 한 줄 설치(플러그인 마켓플레이스)

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

지원 에이전트 및 설치 경로

스킬 다운로드 (.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 키를 생성한 다음 이 두 환경 변수를 설정하세요. 전체 키는 한 번만 표시됩니다. 안전하게 보관하고 소스 코드나 클라이언트 측 코드에 넣지 마세요.

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 직접 호출

스킬 없이 직접 호출할 수 있습니다. 비공개 및 처리 엔드포인트에는 X-API-Key가 필요합니다. /v1/health와 Headshots의 catalog, showcases, scenes 탐색은 공개됩니다. 계정 키에는 필요한 최소 스코프만 부여하세요.

단계형 AI Headshots API

프로젝트를 만들고 원본을 검사한 뒤 피부톤 조정, 선택적 스무딩, 자르기 레퍼런스 미리보기를 만듭니다. 사용자가 reference를 확인한 후 비동기 생성 작업을 제출하고 상태 조회, 후보 다운로드, 명시적 후처리와 내보내기를 진행합니다. 비공개 리소스는 API 키 계정에 귀속됩니다.

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/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/jobs확인된 reference와 전체 구성으로 비동기 Headshots 생성 제출

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}/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>

인물 라이브러리 API

확인된 인물 재사용, 프로젝트 내 인물 변경, 라이브러리 관리에 사용하는 선택 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포트레이트 업로드 → 그레이딩된 이미지 + 품질 보고서(피부 ΔE, 선택적 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-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포트레이트 업로드 → 스무딩 전용 PNG(색상 변경 없음)

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포트레이트 업로드 → 피부 마스크 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/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허용된 outfit_id로 의상을 변경하고 처리된 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/crop단일 규격 자르기 및 배경 교체. DPI 및 자르기 보고서 헤더 포함

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같은 크기의 증명사진을 6x4, 4x6, A4 또는 사용자 정의 용지에 레이아웃

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 생성은 비동기 작업입니다. 큰 증명사진 패키지는 나누어 호출하세요.

API 키 받기

이메일 인증 코드로 로그인하거나 가입한 다음 계정에서 전용 키를 생성하세요. 연동마다 이름을 지정하고 필요한 스코프만 부여하세요. 키는 언제든지 교체하거나 폐기할 수 있으며, 호출 시 계정 크레딧이 소모됩니다.

  1. 1.이메일로 로그인 또는 가입
  2. 2.키 생성 및 스코프 선택
  3. 3.즉시 복사하여 보관
  4. 4.MCE_API_KEY를 설정하고 API 호출

권한 스코프

catalog:read

스타일, 증명사진 규격, 승인된 의상 조회

portrait:process

포트레이트 그레이딩, 스무딩, 마스크 처리

id-photo:process

증명사진 자르기, 검사, 최적화, 인쇄, 납품 패키지

outfit:process

독립 의상 변경. id-pack에 의상을 포함할 때도 필요

headshot:process

비공개 AI Headshots 프로젝트, 레퍼런스 준비, 생성, 후보, 후처리 및 내보내기

로그인하여 키 생성
← 홈으로 돌아가기
개발자 | MotuArt Color Engine API & Agent Skill