{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-TW/reference/ai_clothes.yaml","sidebar":"sidebar-@l10n/zh-TW/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-TW/reference/ai_clothes.yaml","settings":{"baseUrlPath":"/zh-tw/reference/ai_clothes"},"disableAutoScroll":true,"seo":{"title":"AI 虛擬換裝","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI 虛擬換裝","version":"","description":"# 概述\nAI 虛擬換裝是虛擬試衣間，讓使用者無需實際穿著即可試穿服裝。運用 AI 與照片編輯技術，這些應用將穿搭疊加到您的圖片上，讓你看見不同風格與合身度在您身形上的樣子。非常適合線上購物、風格靈感，或單純玩味時尚想法。用 AI 虛擬換裝服裝。上傳任何服飾參考，與您的照片交換穿搭，即刻完成虛擬衣櫃的轉換。\n\n---\n\n## 整合指南\n\n* API Playground\n您可以使用 API Playground 測試 AI 虛擬換裝功能。這讓您可以實驗自己的想法，並更深入了解試穿流程。\n\n在此存取 API Playground：\n\n\n---\n\n* AI 虛擬換裝 API 使用指南\n\n本指南說明如何使用 AI 虛擬換裝 API 上傳圖片、準備參考穿搭，以及建立虛擬試穿任務。\n\n***\n\n * 步驟 1. 使用 File API 上傳檔案\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n**圖片需求：**\n\n* 上傳高解析度的全身照片。\n* 確保照片清楚呈現整個身體。\n* 避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n* 用於建立 AI 任務的 `file_id`。\n* 用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"requests\": [\n {\n \"method\": \"PUT\",\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n \"headers\": {\n \"Content-Length\": \"547541\",\n \"Content-Type\": \"image/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * 步驟 4. 準備參考穿搭\n\n * 4.1 上傳參考穿搭圖片\n\n您可以：\n\n* 使用 File API（`/s2s/v2.0/file`）上傳穿搭圖片，或\n* 提供有效的圖片網址。\n\n**支援的穿搭圖片：**\n\n* 服裝的產品圖片。\n* 全身照片作為穿搭參考。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n * 步驟 5. 建立 AI 任務\n\n使用 **AI 任務 API**（`/s2s/v2.0/task/cloth-v4`）建立虛擬試穿任務。\n\n**參數：**\n\n* 使用者圖片：`src_file_id` 或 `src_file_url`。\n* 穿搭圖片：`ref_file_id`、`ref_file_url` 或 `template_id`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg\",\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png\",\n \"garment_category\": \"full_body\"\n }'\n```\n\n**回應範例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n }\n}\n```\n\n***\n\n * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n應用案例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg)\n\n拍攝建議：\n![拍攝建議](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png \"拍攝建議\")\n\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n|目標使用者圖片|建議 1024×768，最小 512×384，最大邊 4096 px。

- 僅限單人。
- 為達到最佳結果，人物應佔畫面至少 80%。
- 圖片應僅包含上半身，從胸部往上。無需呈現腹部，但肩膀應可見。
- 臉部必須完全可見，無遮擋。
- 身體必須面向前方並採站姿（不可坐著或蹲著）。 |< 10MB|jpg/png|\n|服裝參考圖片 |建議 1024×768，最小 512×384，最大邊 4096 px。

- 若使用真人服裝照片作為參考
   - 必須僅包含一人。
   - 可見的服裝區域必須完整覆蓋預期的試穿區域。
      - 範例：全身試穿時，半身服裝圖片不可接受。
      - 範例：下半身試穿時，部分褲子不可接受。
   - 服裝不得被嚴重遮擋（例如被長髮或手臂覆蓋）。
   - 臉部必須完全可見，無遮擋。
   - 身體必須面向前方並採站姿（不可坐著或蹲著）。

- 若使用產品圖片作為參考
   - 必須是單一服飾的正面產品照。
   - 不要使用合成圖片（例如上下裝在同一張照片）。
   - 下半身僅支援實際穿著的穿搭，不支援獨立的產品圖片。|< 10MB|jpg/png|\n\n* 錯誤代碼\n\n* 錯誤代碼（前處理）\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| exceed_max_filesize | SRC 或 REF 圖片過大。長邊不得超過 4096 像素。 |\n| error_below_min_image_size | SRC 或 REF 圖片過小。長邊至少需 128 像素。 |\n| error_pose | 無法從上傳的人物 SRC 圖片偵測姿勢。 |\n| error_invalid_ref | REF 圖片無效，例如為空，或主體未完全可見。 |\n| error_apply_region_mismatch | SRC 圖片的套用區域與 REF 圖片不符，因此無法套用任何編輯。 |\n| error_invalid_src | 當來源圖片僅顯示下半身或僅顯示腳部時。 |\n\n* 錯誤代碼（引擎）\n\n| 錯誤代碼 | 說明 |\n| ---------- | ----------- |\n| invalid_parameter | - 服飾類別無效。
- Style_id 不在 inference_style_list 中。
- src_keys、dst_keys 或 acts 無效。
- ref_keys 或 template_ref_image 無效。
- 必須提供其中恰好一項。 |\n| error_download_image | 無法下載 SRC 或 REF 圖片。 |\n| exceed_max_filesize | SRC 或 REF 圖片過大。檔案大小不得超過 10 MB。 |\n| error_nsfw_content_detected | 在結果圖片中偵測到潛在的 NSFW 內容。 |\n| error_editing_failed | 編輯過程失敗，因為結果圖片與來源圖片過於相似。 |\n| unknown_internal_error | - 載入模型失敗。
- 排程演算法類型無效。
- 未載入引擎。
- 檔案不在上傳結果中。 |\n| error_multi_person | 在「normal」或「strict」多人篩選設定下，系統在來源或參考圖片中偵測到多人。 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58（現代 TLS/HTTP 支援）
- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬換裝 V2.0 | 2 |\n| AI 虛擬換裝 V3.0 | 2 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-TW","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-tw/reference/ai_clothes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}