# AI 面部塑形 # 概览 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/](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，这一步可以跳过。 --- 1. 准备特效模板 * 预处理 输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建 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 } } ``` 2. 创建 AI 面部塑形 AI 任务并轮询结果 图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。 * 创建任务接口 ``` POST /s2s/v2.0/task/face-reshape ``` * 轮询接口 ``` GET /s2s/v2.0/task/face-reshape/{task_id} ``` --- ## 文件规格与错误码 * AI 面部塑形规格 **支持的自拍视角** 自拍照中脸部宽高需大于图片宽高的 1/20。 俯仰角、偏航角、翻滚角均须小于 30 度。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) **五官自定义参数说明** | 类别 | 参数 | 作用 | 最小（-100 / 0） | 最大（100） | | --- | --- | --- | --- | --- | | 眼睛 | Size（左/右） | 缩放每只眼睛的整体大小 | 小 | 大 | | 眼睛 | Width | 调整水平跨度 | 窄 | 宽 | | 眼睛 | Height | 调整垂直跨度 | 窄 / 扁 | 圆 / 高 | | 眼睛 | Distance | 调整两眼间距 | 近距 | 宽距 | | 眼睛 | Angle | 调整旋转倾斜 | 内倾 | 外倾 | | 脸部 | Size（左/右） | 缩放脸部每一侧的大小 | 小 | 大 | | 脸部 | Chin Shape（左/右） | 调整下巴轮廓宽度 | 窄 | 宽 | | 脸部 | Chin Length | 调整下巴的垂直长度 | 短 | 长 | | 脸部 | Width | 调整整体脸部宽度 | 窄 | 宽 | | 脸部 | Cheekbone | 调整颧骨突出程度 | 原样（0） | 收进去 | | 脸部 | Jaw | 调整下颌线突出程度 | 原样（0） | 收进去 | | 嘴唇 | Size | 缩放唇部整体体积 | 小 | 大 | | 嘴唇 | Width | 调整水平跨度 | 窄 | 宽 | | 嘴唇 | Upper Height | 调整上唇厚度 | 薄 | 丰 | | 嘴唇 | Lower Height | 调整下唇厚度 | 薄 | 丰 | | 嘴唇 | Peak | 调整唇峰锐度 | 平滑 | 明显 | | 鼻子 | Size | 缩放鼻子整体大小 | 小 | 大 | | 鼻子 | Lift | 调整垂直位置 | 低 | 高 | | 鼻子 | Bridge | 调整鼻梁宽度 | 窄 | 宽 | | 鼻子 | Tip | 调整鼻头的垂直角度 | 上 | 下 | | 鼻子 | Wing | 调整鼻翼宽度 | 窄 | 宽 | | 鼻子 | Width | 调整鼻头宽度 | 窄 | 宽 | **说明：** *“左”与“右”以人物自身视角为准，不是观看者屏幕的左右侧。* --- * 支持的格式与尺寸 | AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | AI 面部塑形 | 长边 <= 4096 | < 10MB | jpg/jpeg/png | * 错误码 | 错误码 | 说明 | | --- | --- | | RUNTIME_ERROR | 运行时发生未知错误 | | PHOTO_DETECTION_FAIL | 用户图片无法正确处理，例如未检测到手 | | OBJECT_DETECTION_FAIL | 对象图片无法正确处理，例如未检测到商品 | | PHOTO_CHECK_INVALID | 用户图片的姿态或尺寸不符合要求 | | INPUT_ERROR | 输入文件格式有误 | | INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 | * 运行环境与依赖 | 示例代码语言 / 工具 | 建议运行时版本 | | --- | --- | | 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 | --- ## JS Camera Kit --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 面部塑形 V1.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 面部塑形](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_face_reshape.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-reshape/pre-process](https://docs.perfectcorp.com/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post.md): 当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 `index` 取值、您的应用也不需要手动挑选目标，这一步可以省略。 预处理任务会在源图中检测候选目标，并把它们的坐标返回在 `data.results.result` 中。结果数组里的每一项对应一个检测到的目标。请查看返回的坐标，与源图中您要处理的脸部或区域对 - [GET /s2s/v2.0/task/face-reshape/pre-process/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1%7Btask_id%7D/get.md): 当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 `index` 取值、您的应用也不需要手动挑选目标，这一步可以省略。 预处理任务会在源图中检测候选目标，并把它们的坐标返回在 `data.results.result` 中。结果数组里的每一项对应一个检测到的目标。请查看返回的坐标，与源图中您要处理的脸部或区域对 - [POST /s2s/v2.0/task/face-reshape](https://docs.perfectcorp.com/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/face-reshape/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1%7Btask_id%7D/get.md)