{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_hairstyle.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_hairstyle.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_hairstyle"},"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用最前沿的 AI 技术试遍各式发型，男女都照顾到，满足不同的性别与风格偏好。\n风格的世界大门为您打开：卷发、长发、平头，还有更多。我们的 AI 发型变身让您轻松尝试，现在就找到您的理想发型！\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg)\n\n---\n\n## 接入指南\n\n* API Playground\n您可以用 API Playground 测试 AI 发型虚拟试戴功能，边试边熟悉试戴流程，理解会更透彻。\n\nAPI Playground 地址：\n\n\n---\n\n* 接口流程\n本指南将带您走完全流程：\n\nAI 发型虚拟试戴接口的流程：\n\n**接口地址：** `/s2s/v2.1/task/hair-transfer`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n - 第一步是准备一张自拍照。\n\n2. **列出预设模板，或使用您自己的参考照片**\n **选择参考来源**\n参考素材有两种方式：\n\n| 方式 | 适用场景 | 实现提示 |\n|-------|-----------|---------------------|\n| **预设模板**（`template_id`） | 快速上手（例如\"卷发波波头\"\"侧分刘海\"） | 调用 `/s2s/v2.1/task/template/hair-transfer`，挑一个 `template_id`。 |\n| **自定义参考图**（`ref_file_url` / `ref_file_id`） | 用户上传自己的风格照片，或使用提供的图片链接 | 用同一个 File 接口上传；
参考图若已托管在网上，用 `ref_file_url` 即可。 |\n\n3. **发起 AI 任务并取得 Task ID：**\n - 把上传好的图片连同发型配置，通过 HTTP POST 请求送到 `/s2s/v2.0/file`。\n - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n4. **轮询任务状态（持续检查）：**\n - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /task/${task_id}`）。\n - 持续留意：\n - `Task_status = \"success\"`（处理完成）。\n - `Task_status = \"error\"`（视情况排查或重试）。\n - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n---\n\n* 接口使用指引\n\n本指引说明如何上传图片、准备参考图，以及创建虚拟试戴任务。\n\n***\n\n * 第 1 步：用 File 接口上传文件，或提供一个有效的图片 URL\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\n\n如果您已有公开可访问的图片 URL，第 1 到第 3 步可以跳过。\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_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用 **模板接口**（`/s2s/v2.1/task/template/hair-transfer`）取得预设参考模板列表：\n\n```bash\ncurl --request GET \\\n --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \\\n --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n * 4.2 上传参考图\n\n您可以：\n\n* 用 File 接口（`/s2s/v2.0/file`）上传参考图，或\n* 提供一个有效的图片 URL。\n\n**支持的图片：**\n\n* 另一张自拍照，作为参考图。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n * 第 5 步：创建 AI 发型虚拟试戴任务\n\n用 **AI 任务接口**（`/s2s/v2.1/task/hair-transfer`）创建虚拟试戴任务。\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.1/task/hair-transfer \\\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/selfie_03_cccd5d4803.jpeg\",\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png\"\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.1/task/hair-transfer/ \\\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![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg)\n\n拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 发型虚拟试戴|长边 <= 1024，脸部宽度 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，须呈现完整脸部|< 10MB|jpg/jpeg|\n\n* 错误码\n\n|错误码|说明|\n| ---- | ---- |\n|error_no_shoulder\t|源图中看不到肩部\n|error_large_face_angle\t|上传图片中的脸部角度过大\n|error_insufficient_landmarks\t|源图中检测不到足够的脸部或人体关键点\n|error_hair_too_short\t|输入的头发太短\n|error_face_pose\t|源图的脸部姿态不受支持\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\n**答：** 当然可以，用您自己的参考照片就能试自定义发型。AI 发型虚拟试戴支持两种方式指定想要的发型：\n\n1. **上传您自己的参考图**\n 通过 File 接口（`/s2s/v2.0/file`）上传一张高分辨率的自拍照或风格照（例如展示目标发型的人物照）。上传完成后，创建 AI 任务时用返回的 `file_id` 或公开 URL 作为参考来源。\n\n2. **提供有效的图片 URL**\n 若参考图已托管在网上（例如您自己的服务器或 CDN），可直接在请求体的 `ref_file_url` 字段填入其 HTTPS URL。\n\n通过 `/s2s/v2.1/task/hair-transfer` 提交任务时，二选一填入：\n- `src_file_id`（您的自拍照）与 `ref_file_id`（您的自定义参考图），\n或\n- `src_file_url` 与 `ref_file_url`。\n\n请确保两张图片都符合要求：\n- 支持格式：仅限 JPG/JPEG\n- 文件大小 10 MB 以内\n- 长边 ≤ 1024 像素\n- 脸部宽度 ≥ 128 像素\n- 头部姿态在允许范围内（俯仰角：−10° 到 +10°，偏航角：−45° 到 +45°，翻滚角：−15° 到 +15°）\n- 画面中只有单人脸，正脸视角，头发清楚可见\n\n有了这份灵活度，只要照片里有参考，几乎任何发型都能套用，不限于预设模板。\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 发型虚拟试戴 V2.0 | 预设模式 1 点
自定义模式 2 点 |\n| AI 发型虚拟试戴 V2.1 | 预设模式 2 点
自定义模式 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_hairstyle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}