{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_clothes.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_clothes.yaml","settings":{"baseUrlPath":"/zh-cn/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\nAPI Playground 地址：\n\n\n---\n\n* AI 时装虚拟试穿接口使用指引\n\n本指引说明如何上传图片、准备参考服装，以及创建虚拟试穿任务。\n\n***\n\n * 第 1 步：用 File 接口上传文件\n\n用 **File 接口**（`/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 接口响应\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 步：把图片上传到提供的 URL\n\n用 File 接口响应中的 `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 接口（`/s2s/v2.0/file`）上传服装图片，或\n* 提供一个有效的图片 URL。\n\n**支持的服装图片：**\n\n* 服装的商品图。\n* 真人全身照，作为穿搭参考。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n * 第 5 步：创建 AI 任务\n\n用 **AI 任务接口**（`/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成功的响应会给出结果图片的下载 URL：\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 密钥无效的报错响应：\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 \"Suggestions for How to Shoot\")\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 | 源图或参考图过大。长边不得超过 4096 像素。 |\n| error_below_min_image_size | 源图或参考图过小。长边不得小于 128 像素。 |\n| error_pose | 无法从上传的人物源图中检测出姿态。 |\n| error_invalid_ref | 参考图无效，例如图片为空，或主体未完整呈现。 |\n| error_apply_region_mismatch | 源图中的套用区域与参考图不匹配，无法套用任何修改。 |\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 | 源图或参考图下载失败。 |\n| exceed_max_filesize | 源图或参考图过大。文件大小不得超过 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 (modern TLS/HTTP support)
- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for 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.216.199"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_clothes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}