文件规格与错误码

AI 发型虚拟试戴

概览

用最前沿的 AI 技术试遍各式发型，男女都照顾到，满足不同的性别与风格偏好。风格的世界大门为您打开：卷发、长发、平头，还有更多。我们的 AI 发型变身让您轻松尝试，现在就找到您的理想发型！

接入指南

API Playground 您可以用 API Playground 测试 AI 发型虚拟试戴功能，边试边熟悉试戴流程，理解会更透彻。

API Playground 地址： https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/

接口流程本指南将带您走完全流程：

AI 发型虚拟试戴接口的流程：

接口地址： /s2s/v2.1/task/hair-transfer

需要鉴权： Authorization: Bearer YOUR_API_KEY

流程步骤：

准备图片上传：
- 第一步是准备一张自拍照。
列出预设模板，或使用您自己的参考照片 选择参考来源 参考素材有两种方式：

方式	适用场景	实现提示
预设模板（`template_id`）	快速上手（例如"卷发波波头""侧分刘海"）	调用 `/s2s/v2.1/task/template/hair-transfer`，挑一个 `template_id`。
自定义参考图（`ref_file_url` / `ref_file_id`）	用户上传自己的风格照片，或使用提供的图片链接	用同一个 File 接口上传；参考图若已托管在网上，用 `ref_file_url` 即可。

发起 AI 任务并取得 Task ID：
- 把上传好的图片连同发型配置，通过 HTTP POST 请求送到 /s2s/v2.0/file。
- 响应会返回一个唯一的任务 ID，用于标识本次调用。
轮询任务状态（持续检查）：
- 用取得的 task_id 通过 HTTP GET 请求定期轮询任务状态（例如 GET /task/${task_id}）。
- 持续留意：
  - Task_status = "success"（处理完成）。
  - Task_status = "error"（视情况排查或重试）。
- 状态转为 success 后，按流程继续往下走。

这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。

鉴权

请在请求头中以 Bearer Token 方式带上您的 API 密钥：
```
Authorization: Bearer YOUR_API_KEY
```

API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。

接口使用指引

本指引说明如何上传图片、准备参考图，以及创建虚拟试戴任务。

第 1 步：用 File 接口上传文件，或提供一个有效的图片 URL

用 File 接口（/s2s/v2.0/file）上传目标用户图片。

如果您已有公开可访问的图片 URL，第 1 到第 3 步可以跳过。

图片要求：

上传一张高分辨率的自拍照。
确保照片把整个人体完整、清楚地呈现出来。
避免背景里有多人，或杂乱干扰的物体。

请求示例：

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": "selfie_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'

第 2 步：取得 File 接口响应

响应中包含：

用于创建 AI 任务的 file_id。
用于上传实际图片文件的 requests.url。

响应示例：

{
  "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 上传图片：

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 取得预设图片模板

用 模板接口（/s2s/v2.1/task/template/hair-transfer）取得预设参考模板列表：

curl --request GET \
  --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \
  --header 'Authorization: Bearer YOUR_API_KEY'

4.2 上传参考图

您可以：

用 File 接口（/s2s/v2.0/file）上传参考图，或
提供一个有效的图片 URL。

支持的图片：

另一张自拍照，作为参考图。

详细规格见 文件规格与错误码。

第 5 步：创建 AI 发型虚拟试戴任务

用 AI 任务接口（/s2s/v2.1/task/hair-transfer）创建虚拟试戴任务。

参数：

用户图片：src_file_id 或 src_file_url。
参考图：ref_file_id、ref_file_url 或 template_id。

请求示例：

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg",
    "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png"
  }'

响应示例：

{
  "status": 200,
  "data": {
    "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
  }
}

第 6 步：轮询任务结果

用任务 ID 查看状态：

curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/<YOUR_TASK_ID> \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'

第 7 步：取回结果

成功的响应会给出结果图片的下载 URL：

{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}

API 密钥无效的报错响应：

{
  "status": 401,
  "error": "Unauthorized",
  "error_code": "InvalidAccessToken"
}

应用场景：应用场景：

拍摄建议：

文件规格与错误码

支持的格式与尺寸

AI 功能	支持尺寸	支持文件大小	支持格式
AI 发型虚拟试戴	长边 <= 1024，脸部宽度 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，须呈现完整脸部	< 10MB	jpg/jpeg

错误码

错误码	说明
error_no_shoulder	源图中看不到肩部
error_large_face_angle	上传图片中的脸部角度过大
error_insufficient_landmarks	源图中检测不到足够的脸部或人体关键点
error_hair_too_short	输入的头发太短
error_face_pose	源图的脸部姿态不受支持

运行环境与依赖

示例代码语言 / 工具	建议运行时版本
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 发型虚拟试戴支持两种方式指定想要的发型：

上传您自己的参考图 通过 File 接口（/s2s/v2.0/file）上传一张高分辨率的自拍照或风格照（例如展示目标发型的人物照）。上传完成后，创建 AI 任务时用返回的 file_id 或公开 URL 作为参考来源。
提供有效的图片 URL 若参考图已托管在网上（例如您自己的服务器或 CDN），可直接在请求体的 ref_file_url 字段填入其 HTTPS URL。

通过 /s2s/v2.1/task/hair-transfer 提交任务时，二选一填入：