AI 面部塑形

接入指南

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

AI 面部塑形接口的流程：

接口地址： /s2s/v2.0/file

需要鉴权： Authorization: Bearer YOUR_API_KEY

流程步骤：

1. 准备图片上传：

   • 准备好要上传的自拍照。
   • 调用 File 接口 /s2s/v2.0/file 取得上传 URL 与对应的 file_id。
   • 用提供的上传 URL 把自拍照上传上去。

2. 多张人脸时的可选预处理：

   • 图中有多于一张人脸时，请先对自拍照做预处理。

3. 设置 AI 面部塑形特效：

   • 先选好眼部、脸部、唇部或鼻部的合适塑形参数。

4. 发起 AI 任务并取得 Task ID：

   • 把 file_id 连同选好的特效配置，通过 HTTP POST 请求送到 /s2s/v2.0/task/face-reshape。
   • 响应会返回一个唯一的任务 ID，用于标识本次调用。

5. 轮询任务状态（持续检查）：

   • 用取得的 task_id 通过 HTTP GET 请求定期轮询任务状态（例如 GET /s2s/v2.0/task/face-reshape/${task_id}）。
   • 持续留意：
     • Task_status = "success"（处理完成）。
     • Task_status = "error"（视情况排查或重试）。
   • 状态转为 success 后，按流程继续往下走。

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

• API Playground

用官方演练场交互式地体验和测试接口：

API Playground： http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/

• 鉴权

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

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

1. 上传图片

   您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。

   • 上传接口

     POST /s2s/v2.0/file

   如果您已有公开可访问的图片 URL，这一步可以跳过。

2. 准备特效模板

   • 预处理 输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建 AI 面部塑形 AI 任务。

     {
         "timed": number,
         "result": [
             {
                 "left": number,
                 "top": number,
                 "width": number,
                 "height": number
             }
         ]
     }

     • 特效模板 JSON Schema
     {
         "version": "1.0",
         "index": 0,
         "features": {},
         "global": {
         "skin_smooth_strength": 50,
         "skin_smooth_color_intensity": 50,
         },
     }

     index：预处理检测到的人脸下标。选填，默认 0。 features：至少需要 1 项非零的 AI 面部塑形参数，不能全为 0。 skin_smooth_strength：0~100 skin_smooth_color_intensity：0~100

     • 特效格式
     • 脸部 默认范围：-100~100 颧骨与下颌的范围：0~100 所有特征值不得同时为 0，至少要有一项特征值非 0
     {
         "cheekbones": 0,
         "jaw": 0,
         "face_reshape_left": 0,
         "face_reshape_right": 0,
         "face_width": 0,
         "chin_reshape_left": 0,
         "chin_reshape_right": 0,
         "chin_length": 0,
     }

     • 眼部 默认范围：-100~100 所有特征值不得同时为 0，至少要有一项特征值非 0
     {
         "eye_size_left": 0,
         "eye_size_right": 0,
         "eye_distance": 0,
         "eye_angle": 0,
         "eye_height": 0,
         "eye_width": 0,
     }

     • 鼻部 默认范围：-100~100 所有特征值不得同时为 0，至少要有一项特征值非 0
     {
         "nose_bridge_width": 0,
         "nose_lift": 0,
         "nose_size": 0,
         "nose_tip": 0,
         "nose_tip_width": 0,
         "nose_wing": 0
     }

     • 唇部 默认范围：-100~100 所有特征值不得同时为 0，至少要有一项特征值非 0
     {
         "lip_size": 0,
         "lip_width": 0,
         "lip_peak": 0,
         "lip_height_top": 0,
         "lip_height_bottom": 0,
     }

     • 请求示例（可直接发送）
     {
     "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg",
     "version": "1.0",
     "source": "yco",
     "features": {
         "eye_size_left": 80,
         "eye_size_right": 80,
         "eye_width": 0,
         "eye_height": 0,
         "eye_distance": 0,
         "eye_angle": 0,
         "face_reshape_left": 0,
         "face_reshape_right": 0,
         "chin_reshape_left": 20,
         "chin_reshape_right": 20,
         "chin_length": 0,
         "face_width": -30,
         "cheekbones": 0,
         "jaw": 0,
         "lip_size": 10,
         "lip_width": 40,
         "lip_height_top": 10,
         "lip_height_bottom": 10,
         "lip_peak": -10,
         "nose_size": 30,
         "nose_lift": -20,
         "nose_bridge_width": 10,
         "nose_tip": -10,
         "nose_wing": 30,
         "nose_tip_width": 30
     },
     "global": {
         "skin_smooth_strength": 50,
         "skin_smooth_color_intensity": 50
     }
     }

3. 创建 AI 面部塑形 AI 任务并轮询结果

   图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 success 或 error。

   • 创建任务接口

     POST /s2s/v2.0/task/face-reshape

   • 轮询接口

     GET /s2s/v2.0/task/face-reshape/{task_id}

文件规格与错误码

• AI 面部塑形规格

支持的自拍视角 自拍照中脸部宽高需大于图片宽高的 1/20。 俯仰角、偏航角、翻滚角均须小于 30 度。

五官自定义参数说明

说明： “左”与“右”以人物自身视角为准，不是观看者屏幕的左右侧。

• 支持的格式与尺寸

• 错误码

• 运行环境与依赖

JS Camera Kit

点数消耗