開発者

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キーを作成し、次の2つの環境変数を設定します。キーの全文は一度だけ表示されます。安全に保管し、ソースコードやクライアント側コードに含めないでください。

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>

制限: 1画像あたり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