# AI 时装虚拟试穿 # 概览 AI 时装虚拟试穿是一间虚拟试衣间，不用真穿就能试遍各种衣服。它借助 AI 与图片编辑技术，把服装叠合到您的照片上，让您看清不同风格、不同版型穿在自己身形上的样子。网购、找穿搭灵感，或纯粹玩一玩时尚点子，都很合适。用 AI 时装虚拟试穿体验虚拟试穿。上传任意服装参考图，与您的照片互换穿搭，瞬间换一整套行头。 --- ## 接入指南 * API Playground 您可以用 API Playground 测试 AI 时装虚拟试穿的虚拟试穿功能，边试边熟悉试穿流程，理解会更透彻。 API Playground 地址： [https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/](https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/) --- * AI 时装虚拟试穿接口使用指引 本指引说明如何上传图片、准备参考服装，以及创建虚拟试穿任务。 --- * 第 1 步：用 File 接口上传文件 用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。 **图片要求：** * 上传一张高分辨率的全身照。 * 确保照片把整个人体完整、清楚地呈现出来。 * 避免背景里有多人，或杂乱干扰的物体。 **请求示例：** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` --- * 第 2 步：取得 File 接口响应 响应中包含： * 用于创建 AI 任务的 `file_id` 。 * 用于上传实际图片文件的 `requests.url` 。 **响应示例：** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` --- * 第 3 步：把图片上传到提供的 URL 用 File 接口响应中的 `requests.url` 上传图片： ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` --- * 第 4 步：准备参考服装 * 4.1 上传参考服装图片 您可以： * 用 File 接口（ `/s2s/v2.0/file` ）上传服装图片，或 * 提供一个有效的图片 URL。 **支持的服装图片：** * 服装的商品图。 * 真人全身照，作为穿搭参考。 详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。 --- * 第 5 步：创建 AI 任务 用 **AI 任务接口**（`/s2s/v2.0/task/cloth-v4`）创建虚拟试穿任务。 **参数：** * 用户图片： `src_file_id` 或 `src_file_url` 。 * 服装图片： `ref_file_id` 、 `ref_file_url` 或 `template_id` 。 **请求示例：** ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4 \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_03_cccd5d4803.jpeg", "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png", "garment_category": "full_body" }' ``` **响应示例：** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- * 第 6 步：轮询任务结果 用任务 ID 查看状态： ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/cloth-v4/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` --- * 第 7 步：取回结果 成功的响应会给出结果图片的下载 URL： ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` API 密钥无效的报错响应： ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- 应用场景： ![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg) 拍摄建议： ![拍摄建议](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png) ## 文件规格与错误码 * 支持的格式与尺寸 | 类型 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | 目标用户图片 | 建议 1024×768，最小 512×384，最长边 4096 px。 - 仅支持单人。 - 为达到最佳效果，人物应占据画面至少 80%。 - 图片只需包含上半身，从胸部往上即可。腹部不必露出，但肩膀须可见。 - 脸部必须完整可见，不得被遮挡。 - 身体须正对镜头、站姿（不要坐着或蹲着）。 | < 10MB | jpg/png | | 服装参考图片 | 建议 1024×768，最小 512×384，最长边 4096 px。 - 使用真人服装照作为参考时   - 只能有一位人物。   - 可见的服装区域必须完整覆盖要试穿的部位。      - 举例：全身试穿时，不能拿半身服装图来用。      - 举例：下半身试穿时，不能只用裤子的一部分。   - 服装不得被严重遮挡（例如被长发或手臂盖住）。   - 脸部必须完整可见，不得被遮挡。   - 身体须正对镜头、站姿（不要坐着或蹲着）。 - 使用商品图作为参考时   - 必须是单件服装的正面商品图。   - 不要使用合成图（例如一张图里同时有上衣和下装）。   - 下半身只支持实际穿着的服装，不支持单件商品图。 | < 10MB | jpg/png | * 错误码 * 错误码（预处理） | 错误码 | 说明 | | --- | --- | | exceed_max_filesize | 源图或参考图过大。长边不得超过 4096 像素。 | | error_below_min_image_size | 源图或参考图过小。长边不得小于 128 像素。 | | error_pose | 无法从上传的人物源图中检测出姿态。 | | error_invalid_ref | 参考图无效，例如图片为空，或主体未完整呈现。 | | error_apply_region_mismatch | 源图中的套用区域与参考图不匹配，无法套用任何修改。 | | error_invalid_src | 源图只有下半身或只有脚部时。 | * 错误码（引擎） | 错误码 | 说明 | | --- | --- | | invalid_parameter | - 服装类别无效。 - Style_id 不在 inference_style_list 中。 - src_keys、dst_keys 或 acts 无效。 - ref_keys 或 template_ref_image 无效。 - 上述参数必须且只能提供一个。 | | error_download_image | 源图或参考图下载失败。 | | exceed_max_filesize | 源图或参考图过大。文件大小不得超过 10 MB。 | | error_nsfw_content_detected | 在结果图中检测到疑似不适宜内容（NSFW）。 | | error_editing_failed | 编辑失败：结果图与原图过于相似。 | | unknown_internal_error | - 模型加载失败。 - 调度算法类型无效。 - 未加载引擎。 - 文件不在上传结果中。 | | error_multi_person | 在"normal"或"strict"多人过滤设置下，系统在源图或参考图中检测到多人。 | * 运行环境与依赖 | 示例代码语言 / 工具 | 建议运行时版本 | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) | | Node.js (JavaScript) | Node >= 18 (for global fetch) | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 | | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 | --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 时装虚拟试穿 V2.0 | 2 | | AI 时装虚拟试穿 V3.0 | 2 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 时装虚拟试穿](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_clothes.yaml) ## V4.0 - [POST /s2s/v2.0/task/cloth-v4](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/cloth-v4/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1%7Btask_id%7D/get.md) ## V3.0 - [POST /s2s/v2.0/task/cloth-v3](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/cloth-v3/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1%7Btask_id%7D/get.md) ## V2.0 - [GET /s2s/v2.0/task/template/cloth](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get.md) - [POST /s2s/v2.0/task/cloth](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post.md): 本接口用于发起 AI 时装虚拟试穿流程。您可以使用模板 ID，或提供参考图（源文件与参考文件）。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。 - [GET /s2s/v2.0/task/cloth/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1%7Btask_id%7D/get.md)