{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_hat.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_hat.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_hat"},"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/hat`\n* **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n* **流程：**\n 1. **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试戴的目标。\n 1. **准备帽子图片：** 上传帽子商品图，或一位佩戴帽子的人物照片。\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/hat`）创建虚拟试戴任务。\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/hat \\\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/hat/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 * 占比要求：所穿戴商品须占整张图片高度的 20% 以上，确保它在画面中清楚、突出。\n\n\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 建议脸部占比：超过图片高度的 15%。\n* 单一主体要求：图片只能有一位真人主体，不允许出现其他人物或局部人体。\n* 脸部可见：主体的脸部必须完整可见、无遮挡。头发、配饰或物体不得盖住关键面部特征。\n* 构图：画面至少包含头像照，收录从头顶到胸口的区域；半身照（头到腰）更佳，分析效果最好。\n\n\n\n**试戴风格**\n\n* 生成虚拟试戴结果有五种预设风格：\"style_sporty_casual\" \"style_urban_fashion\" \"style_vacation_casual\" \"style_warm_cozy\" 与 \"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.216.199"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_hat","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}