{
"openapi": "3.0.0",
"info": {
"title": "肌肤拟真",
"description": "# 概览\n**AI 驱动的显老/肤质模拟：精准、专业地可视化护理成效**\n\n我们这套前沿的 AI 肤质模拟技术，能对脸部皮肤状态做出高度还原的调整前后对比，让专业人员和消费者都能客观追踪护肤方案随时间的效果。方案以高保真写实与临床级洞察为设计目标，最多可支持 10 项皮肤问题的可视化：光泽度、痘痘、出油、眼袋、黑眼圈、斑点、毛孔、肤质纹理、皱纹、泛红。\n\n\n\n系统把精密的机器学习模型与强大的增强现实能力结合在一起，只用一部普通手机相机或电脑摄像头，就能给出逼真、非侵入式的成效预览。每次模拟几秒钟完成，用户立刻就能得到一个有科学依据的直观认知：针对性的护肤干预会怎样让肤色肤质随时间变好。\n\n\n\n这套平台专为护肤品牌、皮肤科诊所、医美机构、美妆零售打造，在数字与线下各触点都能轻松接入，包括电商网站、移动应用、线上咨询、门店自助终端。可用场景很广：个性化护肤方案推荐、产品效果模拟、专业疗程方案规划，以及互动式科普工具——这些都能提升客户参与度，让品牌主张更可信。\n\n\n\n借助客观的可视化与数据驱动的呈现，我们的 AI 肤质模拟帮助护肤专业人员设定合理预期、定制护理方案、展示可量化的进展，最终把客户体验抬上一个台阶，在日趋竞争的市场里坐实\"有效果、有依据\"。\n\n\n\n---\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 年龄模拟器接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/skin-simulation`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n - 第一步是准备一张自拍照。\n\n2. **肌肤拟真**\n 每项皮肤问题（例如皱纹、毛孔、泛红）都用 **0.0 到 1.0** 的数值调整 **模拟强度**：\n\n - **0.0**：显示您*原本*的皮肤状态——不做任何改变。\n - **1.0**：套用 AI 能为该项问题生成的*最自然、最健康*的改善。\n\n **运作方式：**\n - 低强度（例如 0.2–0.4）时，细纹与小瑕疵只是轻轻柔化。\n - 高强度（例如 0.7–1.0）时，改善更明显，例如中度到较深的皱纹显著变浅、纹理更平滑、肤色更均匀，同时仍保留皮肤的自然细节。\n\n 一点点调，调到您满意的样子！\n\n1. **发起 AI 任务并取得 Task ID：**\n - 把上传好的图片连同 AI 年龄模拟器配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/skin-simulation`。\n - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n2. **轮询任务状态（持续检查）：**\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您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 调整 AI 年龄模拟器强度\n**肌肤拟真**\n\n每项皮肤问题（例如皱纹、毛孔、泛红）都可以在 **0.0 到 1.0** 的范围内调整 **模拟强度**：\n\n- **0.0** → *原本状态* — 不做任何 AI 增强。\n- **1.0** → 该项问题*最大幅度的自然健康改善*，由我们的 AI 模型按写实方式呈现。\n\n**不同强度档位能看到的效果：**\n\n| 强度区间 | 效果 |\n|-----------------|--------|\n| **0.1 – 0.3** | 轻度修饰 — 细纹轻微柔化、毛孔略微变浅、泛红温和减轻。适合自然的\"素净好气色\"。 |\n| **0.4 – 0.6** | 均衡增强 — 纹理与通透度有明显改善，同时保留个人皮肤的特点。 |\n| **0.7 – 1.0** | 全面改善 — 中度到较深的皱纹显著变浅、肤色更均匀、毛孔与泛红减少、整体光泽提升，*不会*有过度磨皮的假感。 |\n\n**行家提示：** 从低档位开始（例如 0.2），一点点调高，直到效果的真实感达到您要的程度。\n\n---\n\n* 创建 AI 年龄模拟器任务并轮询结果\n\n上传图片后，只要把**至少一项**皮肤问题的模拟强度调到 0.0 以上，就可以发起任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/skin-simulation\n```\n\n * 轮询接口\n\n```\nGET /s2s/v2.0/task/skin-simulation/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 年龄模拟器规格\n\n**相机与拍摄指引**\n\n**光线条件**\n环境要明亮、光照均匀。避免强逆光、局部过曝，或脸上有大片阴影。尽量使用自然日光或柔和的室内光。不要使用彩色灯光，包括粉色、蓝色等带色温的光源，它们会让肤色呈现失真。\n\n**脸部位置与遮挡**\n采用正面视角，脸部正对相机。头部转动要小，避免向任一侧过度倾斜或转动。整张脸——包括额头、脸颊、下巴——都要完整可见、无遮挡。不要用头发、口罩、手、镜框、手机等任何部分遮挡面部特征的物体。\n\n**表情与姿态**\n保持自然放松的表情，双眼睁开。嘴巴可以闭合也可以微张，不要绷脸或做夸张姿态。\n\n**画面中的脸部大小**\n脸部宽度需至少占图片宽度的 60%，以确保有足够的细节支撑准确分析。不要拍摄过小、过远或构图不当的对象。\n\n\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 年龄模拟器|短边 >= 480，长边 <= 2560|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n| **错误码** | **说明** |\n|------------------------------------|----------------|\n| `error_below_min_image_size` | 输入图片分辨率低于最小要求（例如 < 256×256 像素）。请上传更高分辨率的图片。 |\n| `error_exceed_max_image_size` | 输入图片分辨率超出允许上限（例如 > 2560×2560 像素）。请先缩放或缩小图片再上传。 |\n| `error_invalid_params` | 提供的请求参数无效。 |\n| `error_src_face_too_small` | 检测到的人脸占图片宽度不足 60%——太小，无法准确做皮肤分析。请改用脸部更大、更清楚且居于画面中央的图片。 |\n| `error_src_face_out_of_bound` | 检测到的人脸部分或完全超出画面边界（例如裁得太紧）。请确保整张脸——包括额头、脸颊、下巴——可见且构图得当。 |\n| `error_lighting_dark` | 图片环境光线不足以支撑可靠的皮肤分析（例如曝光不足、脸部被阴影主导）。请上传在明亮环境下拍摄、脸部光照均匀的图片。 |\n\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## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 点数消耗\n\n* AI 年龄模拟器\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| 分析 1~4 项皮肤问题 | 4 |\n| 分析 5~10 项皮肤问题 | 6 |\n\n---\n",
"version": "",
"termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api",
"contact": {
"email": "YouCamOnlineEditor_API@perfectcorp.com"
},
"license": {
"name": "Privacy policy",
"url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api"
}
},
"servers": [
{
"url": "https://yce-api-01.makeupar.com"
}
],
"tags": [
{
"name": "V1.0",
"description": "用 AI 处理上传的图片，模拟肤质变化（皱纹、光泽、出油等）。"
}
],
"paths": {
"/s2s/v2.0/task/skin-simulation": {
"post": {
"summary": "执行 肌肤拟真 任务。",
"description": "本接口用于发起肌肤拟真流程。您需要提供源文件（URL 或文件 ID），并指定模拟参数（皱纹、光泽等），且至少有一项不能为 0。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"description": "模拟强度不能全部为 0。\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunSkinSimulationTaskV2"
}
}
}
},
"responses": {
"200": {
"description": "任务执行成功",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskResponseV2"
}
}
}
},
"400": {
"description": "任务执行失败",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/RunError"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/s2s/v2.0/task/skin-simulation/{task_id}": {
"get": {
"summary": "查询 肌肤拟真 任务的状态。",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
},
"description": "要查询的任务 ID"
}
],
"responses": {
"200": {
"description": "任务状态查询成功",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskStatusResponseV2"
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidTaskId"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"500": {
"$ref": "#/components/responses/TaskTimeout"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuthenticationV2": {
"type": "http",
"scheme": "bearer",
"description": "使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。"
}
},
"schemas": {
"RunSkinSimulationTaskV2": {
"title": "Run Skin Simulation Task V2",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2"
},
{
"type": "object",
"properties": {
"wrinkle": {
"type": "number",
"description": "淡化皱纹与细纹，让肌肤更平滑紧致，肉眼可见地恢复饱满年轻。
0.0 为原本肌肤，1.0 为皱纹基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"radiance": {
"type": "number",
"description": "提升肌肤光泽与明亮度，呈现焕新、有活力的亮泽好肤色。
0.0 为原本亮度，1.0 为光泽与通透感最强。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"oiliness": {
"type": "number",
"description": "控制多余油光，让肌肤清爽洁净、不泛油光，触感平衡、舒适雾面。
0.0 为原本肌肤，1.0 为油光与亮感最强。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"acne": {
"type": "number",
"description": "净透易长痘的肌肤，减少痘疹与黑头，呈现更平滑细致、近乎无瑕的透亮肤色。
0.0 为原本肌肤，1.0 为痘痘与粉刺基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"eye_bags": {
"type": "number",
"description": "明显改善眼下浮肿，让眼周更平滑紧致、精神饱满。
0.0 为原本眼周状态，1.0 为眼袋基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"dark_circle": {
"type": "number",
"description": "明显淡化黑眼圈，让眼周更明亮、像睡足了一样，整体气色焕亮。
0.0 为原本眼周肤色，1.0 为黑眼圈基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"spots": {
"type": "number",
"description": "针对色斑明显淡化，同时提升肌肤通透度，呈现更平滑、更匀净的年轻光采。
0.0 为原本肌肤，1.0 为色斑与瑕疵基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"pores": {
"type": "number",
"description": "细致并明显收敛粗大毛孔，呈现更平滑、更精致、近乎无瑕的肤质。
0.0 为原本毛孔可见度，1.0 为毛孔几乎不可见。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"texture": {
"type": "number",
"description": "把肤质打磨到高级定制般的平滑，明显改善不平顺之处，呈现丝滑、精致、透亮的肤色。
0.0 为原本肤质，1.0 为最平滑的肤质。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"redness": {
"type": "number",
"description": "安抚并平衡敏感肌，明显减淡泛红，舒缓易长玫瑰疹的部位，让肤色更匀净通透、肤感更舒适细致。
0.0 为原本肤色，1.0 为泛红与刺激感基本消除。",
"example": 1,
"minimum": 0,
"maximum": 1
}
},
"not": {
"properties": {
"wrinkle": {
"type": "number",
"enum": [
0
]
},
"radiance": {
"type": "number",
"enum": [
0
]
},
"oiliness": {
"type": "number",
"enum": [
0
]
},
"acne": {
"type": "number",
"enum": [
0
]
},
"eye_bags": {
"type": "number",
"enum": [
0
]
},
"dark_circle": {
"type": "number",
"enum": [
0
]
},
"spots": {
"type": "number",
"enum": [
0
]
},
"pores": {
"type": "number",
"enum": [
0
]
},
"texture": {
"type": "number",
"enum": [
0
]
},
"redness": {
"type": "number",
"enum": [
0
]
}
}
}
}
]
},
"BasicRunTaskV2SrcFileUrl": {
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "用于运行任务的文件 URL，该 URL 需可公开访问。",
"example": "https://example.com/selfie.jpg"
}
}
},
"BasicRunTaskV2SrcFileId": {
"type": "object",
"required": [
"src_file_id"
],
"properties": {
"src_file_id": {
"type": "string",
"description": "用于运行任务的文件 ID，取自上传文件接口返回的 file_id。",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2": {
"title": "BasicRunTaskV2",
"anyOf": [
{
"title": "用源文件 URL 运行任务",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
}
]
},
{
"title": "用源文件 ID 运行任务",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
}
]
}
]
},
"BasicRunTaskResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "该任务的 ID。凭这个 ID 可在 24 小时内查询任务结果。",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
}
}
}
}
},
"RunError": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 400
},
"error": {
"type": "string",
"description": "错误信息",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"InvalidParameters",
"CreditInsufficiency",
"InvalidStyleGroup",
"InvalidStyle",
"BadRequest"
],
"description": "错误码：\n * InvalidParameters - 请求参数无效\n * CreditInsufficiency - 点数不足，无法运行\n * BadRequest - 请求参数不符合预期\n * InvalidStyleGroup - 风格分组 ID 无效\n * InvalidStyle - 风格 ID 无效\n"
}
}
},
"EngineErrorCode": {
"type": "string",
"nullable": true,
"enum": [
"error_exceed_max_image_size",
"exceed_max_filesize",
"invalid_parameter",
"error_download_image",
"error_download_mask",
"error_decode_image",
"error_decode_mask",
"error_nsfw_content_detected",
"error_no_face",
"error_pose",
"error_face_parsing",
"error_inference",
"exceed_nsfw_retry_limits",
"error_upload",
"unknown_internal_error"
],
"description": "错误码：\n- \\`error_exceed_max_image_size\\` - 输入图片尺寸超出上限\n- \\`exceed_max_filesize\\` - 输入文件大小超出上限\n- \\`invalid_parameter\\` - 参数取值无效\n- \\`error_download_image\\` - 下载原图出错\n- \\`error_download_mask\\` - 下载蒙版图片出错\n- \\`error_decode_image\\` - 解码原图出错\n- \\`error_decode_mask\\` - 解码蒙版图片出错\n- \\`error_nsfw_content_detected\\` - 在原图中检测到不适宜内容（NSFW）\n- \\`error_no_face\\` - 原图中没有检测到人脸\n- \\`error_pose\\` - 原图的姿态检测失败\n- \\`error_face_parsing\\` - 原图的人脸分割失败\n- \\`error_inference\\` - 推理流程中出现错误\n- \\`exceed_nsfw_retry_limits\\` - 为避免生成不适宜内容， 重试次数已用尽\n- \\`error_upload\\` - 上传结果图片出错\n- \\`unknown_internal_error\\` - 其他错误\n"
},
"TaskStatusResponseBodySingleUrlResultsV2": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "下载该结果的 URL，有效期 2 小时",
"example": "https://example.com/sample-result-url"
}
}
},
"TaskStatusResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_status": {
"type": "string",
"enum": [
"running",
"success",
"error"
],
"description": "任务状态"
},
"error": {
"$ref": "#/components/schemas/EngineErrorCode"
},
"error_message": {
"type": "string",
"description": "错误的详细说明"
},
"results": null
}
}
},
"$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
}
},
"responses": {
"InvalidApiKey": {
"description": "API 密钥无效或缺失",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401,
"description": "响应状态"
},
"error": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
},
"TooManyRequests": {
"description": "请求过多",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429,
"description": "响应状态"
},
"error": {
"type": "string",
"example": "Too many requests"
}
}
}
}
}
},
"InvalidTaskId": {
"description": "任务 ID 无效",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400,
"description": "响应状态"
},
"error": {
"type": "string",
"example": "Invalid task ID"
}
}
}
}
}
},
"TaskTimeout": {
"description": "任务执行超时",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500,
"description": "响应状态"
},
"error": {
"type": "string",
"example": "Task execution timed out"
}
}
}
}
}
}
}
}
}