Pembangun

Bawa MotuArt ke dalam aliran kerja anda

MotuArt Color Engine menyediakan pelarasan potret, segmentasi kulit, pelicinan profesional, penggantian pakaian terpilih, foto profil AI profesional dan penghantaran foto ID melalui Agent Skill, CLI atau API HTTP.

Gunakan sebagai Agent Skill

Agent Skill standard ini berfungsi dengan Claude Code, Codex CLI, ZCode, OpenClaw, Augment, Windsurf dan banyak lagi. Pasangnya dalam direktori skill ejen untuk melaras warna potret, mengeksport topeng, melicinkan kulit, mencipta foto profil AI profesional atau membuat foto ID.

Claude Code: pemasangan satu baris (pasaran plugin)

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

Ejen dan laluan pemasangan yang disokong

Muat turun 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"

Konfigurasikan persekitaran

Cipta kunci API daripada akaun anda, kemudian tetapkan dua pemboleh ubah persekitaran ini. Kunci penuh hanya dipaparkan sekali; simpan dengan selamat dan jangan masukkannya dalam sumber atau kod sisi klien.

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

Perintah biasa

Skrip berada dalam folder skrip skill. headshots.sh mencipta potret profesional melalui peringkat persediaan, pengesahan, penghantaran tak segerak, status, muat turun, pascaproses dan eksport yang jelas; ia tidak mengesahkan rujukan atau memilih calon secara automatik.

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

Atau panggil API HTTP

Panggil API secara terus tanpa skill. Endpoint peribadi dan pemprosesan memerlukan X-API-Key; /v1/health serta penemuan katalog, showcase dan senario Headshots adalah awam. Berikan setiap kunci akaun hanya skop yang diperlukan.

API Foto Profil AI Berperingkat

Cipta projek dan periksa sumber, kemudian laras tona kulit serta pilihan pelicinan dan potongan pada pratonton rujukan. Selepas pengguna mengesahkan rujukan itu, hantar tugas penjanaan tak segerak, semak statusnya, muat turun calon dan pascaproses atau eksport pilihan secara jelas. Sumber peribadi dimiliki oleh akaun kunci API.

GET/v1/headshots/catalogSenario, pose, pakaian, latar belakang, gaya penjanaan dan keserasian awam

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/jobsHantar penjanaan Headshots tak segerak daripada rujukan yang disahkan dengan konfigurasi lengkap

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}Semak keadaan tugas dan calon foto profil profesional yang sedia

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 pustaka individu

API pilihan untuk menggunakan semula individu yang disahkan, menukar individu dalam projek atau mengurus pustaka. Aliran Headshot biasa tidak memerlukannya.

GET/v1/headshots/person-referencesSenaraikan individu disahkan yang boleh digunakan semula dan pratonton peribadi

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-referenceMulakan projek baharu daripada individu tersimpan

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-referenceTukar individu dalam projek sedia ada sambil mengekalkan sejarah

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}Padam lembut entri pustaka sahaja; projek kekal

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 potret dan foto ID

Gunakan API berautentikasi yang sama untuk penggredan potret, topeng kulit, pelicinan, pakaian terpilih, pakej foto ID dan eksport penghantaran.

GET/v1/stylesSenaraikan gaya tersedia (asas / rasa)

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/processMuat naik potret → imej terlaras + laporan kualiti (ΔE kulit, smooth_strength pilihan)

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-lightingTingkatkan dimensi cahaya dan pemisahan subjek tanpa mengubah identiti atau geometri

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/smoothMuat naik potret → PNG pelicinan sahaja (tiada perubahan warna)

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/maskMuat naik potret → PNG topeng kulit (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/specsSenaraikan spesifikasi potongan foto ID, potret dan avatar bersama peraturan latar belakang

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/outfitsSenaraikan pakaian terpilih dengan kategori lelaki, wanita, kanak-kanak dan uniseks serta pratonton

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/outfitGantikan pakaian dengan outfit_id yang dibenarkan dan kembalikan PNG yang diproses

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/cropPotongan satu spesifikasi dan penggantian latar belakang dengan DPI serta pengepala laporan potongan

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-packPakej foto ID: pakaian pilihan, master, imej pelbagai spesifikasi, fail muat naik, helaian cetak dan pematuhan

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-checkSemak saiz, nisbah kepala, pengesanan wajah dan status latar belakang berbanding spesifikasi

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/optimizeEksport fail sedia dimuat naik mengikut saiz, DPI, format dan sasaran saiz fail

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-sheetSusun foto ID bersaiz sama pada kertas 6x4, 4x6, A4 atau tersuai

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>

Had: ≤ 15MB setiap imej, JPG / PNG / WebP. Pemprosesan potret dan foto ID adalah segerak; penjanaan Foto Profil berjalan sebagai tugas tak segerak. Pakej foto ID mengembalikan JSON base64, jadi bahagikan kelompok yang sangat besar.

Dapatkan kunci API

Log masuk atau daftar dengan kod pengesahan e-mel, kemudian cipta kunci khusus dalam akaun anda. Namakan setiap integrasi dan berikan hanya skop yang diperlukannya. Kunci boleh diputar atau dibatalkan pada bila-bila masa, dan panggilan menggunakan kredit akaun.

1.Log masuk atau daftar melalui e-mel
2.Cipta kunci dan pilih skop
3.Salin dan simpan dengan segera
4.Tetapkan MCE_API_KEY dan panggil API

Skop kebenaran

catalog:read

Baca gaya, spesifikasi foto ID dan pakaian yang diluluskan

portrait:process

Pelarasan potret, pelicinan dan pemprosesan topeng

id-photo:process

Potongan, semakan, pengoptimuman, cetakan dan pakej penghantaran foto ID

outfit:process

Penggantian pakaian kendiri; turut diperlukan apabila id-pack menyertakan pakaian

headshot:process

Projek Foto Profil AI peribadi, persediaan rujukan, penjanaan, calon, pascaproses dan eksport

Log masuk dan cipta kunci

← Kembali ke halaman utama