นักพัฒนา

นำ MotuArt ไปใช้ในเวิร์กโฟลว์ของคุณ

MotuArt Color Engine ให้บริการแต่งสีภาพบุคคล แบ่งส่วนผิว ปรับผิว เปลี่ยนเสื้อผ้าที่คัดสรร ภาพโปรไฟล์ AI และไฟล์รูปติดบัตรผ่าน Agent Skill, CLI หรือ HTTP API

ใช้เป็น Agent Skill

สกิลมาตรฐานนี้ใช้ได้กับ Claude Code, Codex CLI, ZCode, OpenClaw, Augment, Windsurf และเครื่องมืออื่น ติดตั้งในโฟลเดอร์ skills เพื่อแต่งสี ส่งออกมาสก์ ปรับผิว สร้างภาพโปรไฟล์ หรือทำรูปติดบัตร

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 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 โดยตรง

เรียก API โดยไม่ใช้สกิลก็ได้ จุดปลายทางส่วนตัวและการประมวลผลต้องใช้ X-API-Key ส่วน health, แคตตาล็อก Headshots, showcase และการค้นหาฉากเป็นสาธารณะ ให้สิทธิ์แต่ละคีย์เท่าที่จำเป็น

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/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ส่งงานสร้าง 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 ปกติ

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อัปโหลดภาพ → 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 มาสก์ผิว

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 ที่อนุญาต

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 รูปแบบ และเป้าหมาย KB

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จัดรูปขนาดเดียวกันลงกระดาษ 6×4, 4×6, 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 การแต่งสีและรูปติดบัตรทำงานแบบ synchronous ส่วน Headshots เป็นงานอะซิงโครนัส แพ็กเกจรูปติดบัตรคืน JSON แบบ base64 จึงควรแบ่งชุดใหญ่

สร้าง API key

เข้าสู่ระบบหรือสมัครด้วยรหัสยืนยันอีเมล แล้วสร้างคีย์เฉพาะในบัญชี ตั้งชื่อแต่ละการเชื่อมต่อและให้เฉพาะสิทธิ์ที่จำเป็น คีย์หมุนเวียนหรือเพิกถอนได้ทุกเมื่อ และการเรียกใช้จะใช้เครดิตบัญชี

1.เข้าสู่ระบบหรือสมัครด้วยอีเมล
2.สร้างคีย์และเลือกสิทธิ์
3.คัดลอกและเก็บทันที
4.ตั้ง MCE_API_KEY แล้วเรียก API

ขอบเขตสิทธิ์

catalog:read

อ่านสไตล์ สเปกรูปติดบัตร และเสื้อผ้าที่อนุมัติ

portrait:process

แต่งสี ปรับผิว และประมวลผลมาสก์ภาพบุคคล

id-photo:process

ครอป ตรวจ ปรับไฟล์ พิมพ์ และสร้างแพ็กเกจรูปติดบัตร

outfit:process

เปลี่ยนเสื้อผ้าแยกเดี่ยว รวมถึงเมื่อ id-pack มีเสื้อผ้า

headshot:process

โปรเจกต์ Headshots ส่วนตัว การเตรียมอ้างอิง สร้างภาพ ประมวลผลต่อ และส่งออก

เข้าสู่ระบบและสร้างคีย์

← กลับหน้าแรก