{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_scarf.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_scarf.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_scarf"},"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":"# 概览\n用线上 AR AI 围巾虚拟试戴，把时尚体验再往上抬一档。顾客可以瞬间把围巾搭到身上的穿搭里，看花纹在真实画面里怎么垂坠流动。\n这套互动式虚拟围巾功能让顾客在线试遍各种风格与颜色，把到店体验搬到线上。依托高保真的 AR 模拟，用户随时随地都能享受细腻到位的围巾呈现。\n\n## 接入指南\n本指南将带您走完全流程：\n\n* **接口地址：** `/s2s/v2.0/task/scarf`\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 步：准备自拍照\n\n您可以：\n* 用 File 接口（`/s2s/v2.0/file`）上传自拍照，或\n* 提供一个有效的图片 URL。\n\n * 第 1.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 * 第 1.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 * 第 1.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 * 第 2 步：准备参考围巾图片\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 * 第 3 步：创建 AI 任务\n\n挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/scarf`）创建虚拟试戴任务。\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/scarf \\\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 * 第 4 步：轮询任务结果\n\n用任务 ID 查看状态：\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * 第 5 步：取回结果\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| ------ | ------------------ | ----- |\n| 自拍照 | 512 × 512 | 脸部可见，建议拍到头到胸 |\n| 围巾 | 512 × 512（商品图）
800 × 800（实拍照） | 围巾画面清楚、无遮挡 |\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_french_elegance\"、\"style_light_luxury\"、\"style_cottagecore\"、\"style_modern_chic\" 与 \"style_bohemian\"。创建 AI 任务时可指定该风格参数；不指定时，系统默认随机挑选。\n\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 围巾虚拟试戴|输入：长边 <= 4096
输出：896 x 1152 |< 10MB|jpg/jpeg/png/heic|\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image | 源图或参考图下载失败 |\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) - jquery >= 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_scarf","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}