{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_bag.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_bag.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_bag"},"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":"# 概览\nAR 让精品包的选购变得实实在在！AR 技术让品牌以极致的真实感呈现手袋：从肩带长度到包款搭配，顾客通过相机就能即刻看到上身效果。\n\n## 接入指南\n本指南将带您走完全流程：\n\n* **接口地址：** `/s2s/v2.0/task/bag`\n* **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n* **流程：**\n 1. **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试背的目标。\n 1. **准备包图片：** 上传包商品图，或提供一位无遮挡的拎包人物图片的有效 URL。\n 1. **选择风格与性别：** 挑选您偏好的风格，以及您想呈现的性别。\n 1. **发起 AI 任务并取得 Task ID：** 从响应中取回 `task_id`。\n 1. **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\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\": \"selfie_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\": \"selfie_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 @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * 第 4 步：准备参考包图片\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挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/bag`）创建虚拟试背任务。\n\n**参数：**\n\n* 用户图片：`src_file_id` 或 `src_file_url`。\n* 包图片：`ref_file_id` 或 `ref_file_url`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\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/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\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\n* AI 包虚拟试戴规格\n\n**支持的包图片**\n\n* 商品图要求\n * 最低分辨率：512 × 512 像素\n * 每张图片只放一件商品\n * 商品应占图片高度的 25% 以上\n\n\n\n* 实拍照要求\n * 最低分辨率：800 × 800 像素\n\n\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 建议脸部占比：超过图片高度的 15%。\n* 图片必须清楚呈现单一真人主体，脸部完整可见，画面至少包含从头顶到胸口的头像照，半身照更佳。\n\n\n\n**试背风格**\n\n* 生成虚拟试背结果有四种预设风格：\"style_parisian_chic\"、\"style_urban_chic\"、\"style_mediterranean_chic\" 与 \"style_art_deco_style\"。创建 AI 任务时可指定该风格参数；不指定时，系统默认随机挑选。\n\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 包虚拟试戴|输入：长边 <= 4096
输出：1104 x 1472 |< 10MB|jpg/jpeg/png/heic|\n\n* 错误码\n\n|错误码|说明|\n| ---- | ---- |\n| error_download_image | 下载 srcKeys/refKeys 出错 |\n| error_inference | 推理流程出错 |\n| error_no_face | 源图中未检测到人脸 |\n| error_nsfw_content_detected| 在结果图中检测到不适宜内容（NSFW） |\n| exceed_max_filesize | 输入文件大小超出上限（10 MB） |\n| invalid_parameter | 性别选项取值无效
风格选项取值无效 |\n| unknown_internal_error | 其他 |\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\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_bag","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}