{"items":[{"type":"separator","label":"常用工具","labelTranslationKey":"sidebar.reference.separators.utility"},{"type":"group","fsPath":"@l10n/zh-CN/reference/unit_system.yaml","link":"/zh-cn/reference/unit_system","routeSlug":"/zh-cn/reference/unit_system","label":"点数体系","items":[{"label":"查询点数信息","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","routeSlug":"/zh-cn/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit/get","metadata":{"seo":{"title":"查询点数信息","description":"以两位小数显示可用点数"}},"httpPath":"/s2s/v1.0/client/credit"},{"label":"查看点数记录","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","routeSlug":"/zh-cn/reference/unit_system/paths/~1s2s~1v1.0~1client~1credit~1history/get","metadata":{"seo":{"title":"查看点数记录","description":"查看点数记录"}},"httpPath":"/s2s/v1.0/client/credit/history"},{"label":"查询功能花费","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","routeSlug":"/zh-cn/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get","metadata":{"seo":{"title":"查询功能花费","description":"查询各接口的点数消耗。数值与 https://yce.perfectcorp.com/ai-api/api-pricing 列出的一致。"}},"httpPath":"/s2s/v2.0/credit/feature-cost"}],"metadata":{"type":"openapi","title":"点数体系","version":"","description":"查询点数明细与使用记录。请注意，Units 是 YouCam API 的计费单位，不同 AI 功能扣减的点数各不相同。本文档中点数的代号为 \"Credit\"。\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/task_management.yaml","link":"/zh-cn/reference/task_management","routeSlug":"/zh-cn/reference/task_management","label":"任务管理","items":[{"label":"删除任务及其文件。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","routeSlug":"/zh-cn/reference/task_management/paths/~1s2s~1v2.0~1task~1delete/post","metadata":{"seo":{"title":"删除任务及其文件。","description":"删除指定 task_id 的已完成任务，同时删除其关联的输入文件与生成结果。请传入该任务运行接口返回的 task_id。"}},"httpPath":"/s2s/v2.0/task/delete"}],"metadata":{"type":"openapi","title":"任务管理","version":""}},{"type":"group","fsPath":"@l10n/zh-CN/reference/file.yaml","link":"/zh-cn/reference/file","routeSlug":"/zh-cn/reference/file","label":"文件管理","items":[{"label":"创建新文件。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/file/paths/~1s2s~1v2.0~1file/post","routeSlug":"/zh-cn/reference/file/paths/~1s2s~1v2.0~1file/post","metadata":{"seo":{"title":"创建新文件。","description":"上传新文件要先调用 File API。它会给您一个 URL， 用这个 URL 把文件传上去。上传完成后，就可以用同一次响应里的 file_id 开始使用我们的 AI 功能。"}},"httpPath":"/s2s/v2.0/file"}],"metadata":{"type":"openapi","title":"文件管理","version":""}},{"type":"separator","label":"肤质·面部·身体","labelTranslationKey":"sidebar.reference.separators.skinFaceBody"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_skin_analysis.yaml","link":"/zh-cn/reference/ai_skin_analysis","routeSlug":"/zh-cn/reference/ai_skin_analysis","label":"AI 肤质分析 V2.1","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_skin_analysis/section/概览","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_skin_analysis/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_skin_analysis/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_skin_analysis/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_skin_analysis/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/点数消耗"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_skin_analysis/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/js-camera-kit"},{"type":"link","label":"Mobile Camera Kit","link":"/zh-cn/reference/ai_skin_analysis/section/概览/mobile-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/mobile-camera-kit"},{"type":"link","label":"使用场景","link":"/zh-cn/reference/ai_skin_analysis/section/概览/使用场景","routeSlug":"/zh-cn/reference/ai_skin_analysis/section/概览/使用场景"}]},{"type":"group","label":"Standard Analysis","link":"/zh-cn/reference/ai_skin_analysis/standard-analysis","routeSlug":"/zh-cn/reference/ai_skin_analysis/standard-analysis","items":[{"type":"link","label":"接口总览","link":"/zh-cn/reference/ai_skin_analysis/standard-analysis/接口总览","routeSlug":"/zh-cn/reference/ai_skin_analysis/standard-analysis/接口总览"},{"label":"执行 AI 肤质分析（V2.1） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis/post","routeSlug":"/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis/post","metadata":{"seo":{"title":"执行 AI 肤质分析（V2.1） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis"},{"label":"查询 AI 肤质分析（V2.1） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_analysis/standard-analysis/paths/~1s2s~1v2.1~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 肤质分析（V2.1） 任务的状态。","description":"查询 AI 肤质分析（V2.1） 任务的状态。"}},"httpPath":"/s2s/v2.1/task/skin-analysis/{task_id}"}]},{"type":"group","label":"Analysis + Advanced Report","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report","items":[{"type":"link","label":"接口总览","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/接口总览","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/接口总览"},{"label":"执行「肤质分析 + 高级测肤报告」任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report/post","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report/post","metadata":{"seo":{"title":"执行「肤质分析 + 高级测肤报告」任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report"},{"label":"查询「肤质分析 + 高级测肤报告」任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-advanced-report/paths/~1s2s~1v2.1~1task~1skin-analysis-report~1{task_id}/get","metadata":{"seo":{"title":"查询「肤质分析 + 高级测肤报告」任务的状态。","description":"查询「肤质分析 + 高级测肤报告」任务的状态。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report/{task_id}"}]},{"type":"group","label":"Analysis + Product Recommendation","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation","items":[{"type":"link","label":"接口总览","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/接口总览","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/接口总览"},{"label":"执行「肤质分析 + 商品推荐」任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation/post","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation/post","metadata":{"seo":{"title":"执行「肤质分析 + 商品推荐」任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-recommendation"},{"label":"查询「肤质分析 + 商品推荐」任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-product-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-recommendation~1{task_id}/get","metadata":{"seo":{"title":"查询「肤质分析 + 商品推荐」任务的状态。","description":"查询「肤质分析 + 商品推荐」任务的状态。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-recommendation/{task_id}"}]},{"type":"group","label":"Analysis + Report + Recommendation","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation","items":[{"type":"link","label":"接口总览","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/接口总览","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/接口总览"},{"label":"执行「肤质分析 + 高级测肤报告 + 商品推荐」任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation/post","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation/post","metadata":{"seo":{"title":"执行「肤质分析 + 高级测肤报告 + 商品推荐」任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report-recommendation"},{"label":"查询「肤质分析 + 高级测肤报告 + 商品推荐」任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_analysis/analysis-+-report-+-recommendation/paths/~1s2s~1v2.1~1task~1skin-analysis-report-recommendation~1{task_id}/get","metadata":{"seo":{"title":"查询「肤质分析 + 高级测肤报告 + 商品推荐」任务的状态。","description":"查询「肤质分析 + 高级测肤报告 + 商品推荐」任务的状态。"}},"httpPath":"/s2s/v2.1/task/skin-analysis-report-recommendation/{task_id}"}]},{"type":"group","label":"Product Catalogs","link":"/zh-cn/reference/ai_skin_analysis/product-catalogs","routeSlug":"/zh-cn/reference/ai_skin_analysis/product-catalogs","items":[{"type":"link","label":"接口总览","link":"/zh-cn/reference/ai_skin_analysis/product-catalogs/接口总览","routeSlug":"/zh-cn/reference/ai_skin_analysis/product-catalogs/接口总览"},{"label":"上传商品目录。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/post","routeSlug":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/post","metadata":{"seo":{"title":"上传商品目录。","description":"以 CSV 文件上传商品目录。文件会在同一次请求中完成校验：校验通过的文件返回 status ready，并带上它的 catalog_id 与 sku_count；未通过校验的文件返回错误，同时仍会记录为一个 failed 目录，「列出目录」接口会把它列出来。"}},"httpPath":"/s2s/v2.1/product-catalog"},{"label":"列出商品目录。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/get","routeSlug":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog/get","metadata":{"seo":{"title":"列出商品目录。","description":"列出您账号下的所有目录，最新的排在最前面，ready 与 failed 都会列出。手上没有了某个 catalog_id 时，可以用它找回来。该接口不分页：每个账号可保留的目录数量有上限（见「商品目录」章节下的「限制」）。"}},"httpPath":"/s2s/v2.1/product-catalog"},{"label":"删除商品目录。","deprecated":false,"httpVerb":"delete","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog~1{catalog_id}/delete","routeSlug":"/zh-cn/reference/ai_skin_analysis/product-catalogs/paths/~1s2s~1v2.1~1product-catalog~1{catalog_id}/delete","metadata":{"seo":{"title":"删除商品目录。","description":"删除目录立即生效且不可撤销。从那一刻起，所有使用该 catalog_id 的测肤调用都会失败。已删除的目录无法恢复。"}},"httpPath":"/s2s/v2.1/product-catalog/{catalog_id}"}]}],"metadata":{"type":"openapi","title":"AI 肤质分析 V2.1","version":"","description":"# 概览\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\n\n**AI 肤质分析 V2.1** 只凭一张正脸自拍，就能给出细致的皮肤洞察。它检测 16 项皮肤指标，包括皱纹、毛孔、色斑、泛红与肤质，并标出每一项皮肤问题出现在脸上的哪个位置；同时估算肌肤年龄，并算出一个整体肌肤状况评分。\n\n在 V2.1 中，您可以按需加上两个加购能力，让接入更完整：\n\n- **高级测肤报告**：基于每位用户的检测结果，生成个性化、读起来轻松好懂的皮肤洞察。\n- **商品推荐**：把您商品目录里的商品对应用户的皮肤问题，做出有针对性的购物体验。\n\n可以只用肤质分析，也可以搭配加购能力一起用。想对比这几种用法，请见 [使用场景](#section/overview/use-cases)。\n\n## 接入指南\n* AI 肤质分析怎么拍照\n* 正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n  - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 接口流程\n**测肤接口使用指引**\n本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。\n\n   * **第 1 步：调整源图尺寸**</br>\n  把图片缩放到支持的尺寸范围——SD 为长边不超过 2560 像素、短边至少 480 像素；HD 为长边不超过 2560 像素、短边至少 1080 像素。详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n   * **第 2 步：通过 File 接口上传文件元数据**\n- 图片要求\n    - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n发送 POST 请求初始化文件上传：\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/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n- ***重要***：只调用 File 接口并不等于上传了文件。您必须**另外把文件上传到 File 接口响应中给出的那个 URL**。那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。\n\n  > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n***\n\n   * **第 3 步：取得上传 URL 与文件 ID**\n\n响应中包含：\n\n*   `requests.url` – 用于上传图片的预签名 URL。\n*   `file_id` – 创建 AI 任务用的标识。\n\n**响应示例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\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/png\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * **第 4 步：把图片上传到预签名 URL**\n\n使用提供的 `requests.url` 与请求头：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/png' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n   * **第 5 步：创建 AI 任务**\n\n用第 2 步取得的 `file_id` 创建 AI 肤质分析：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n    \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true,\n      \"enable_dark_background_hd_pore\": true,\n      \"color_dark_background_hd_pore\": \"3D3D3D\",\n      \"opacity_dark_background_hd_pore\": 0.4\n      // Additional parameters omitted for brevity\n    },\n    \"format\": \"json\"\n  }'\n```\n  上传完成后，就可以用文件 ID 或图片文件 URL 选择要分析的皮肤问题，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。</br>\n  随后用文件 ID 或图片文件 URL 调用 POST 'task/skin-analysis' 执行任务，\n  并取得 ***task_id***。\n  请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。\n\n- **使用已有的公开图片 URL**\n不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。\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用 `task_id` 取回任务结果：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json'\n```\n用这个 ***task_id*** 轮询 GET 'task/skin-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n处理完成的结果保留 30 天。\n- 不必用很短的间隔轮询。\n- 在保留期限内，轮询间隔可以自由安排。\n\n  > **重要：** 由于执行时长没有保证，仍然需要轮询来查看任务状态。\n\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n\n***\n\n   * **第 7 步：解读结果**\n\n响应中包含：\n\n*   `ui_score` – 面向用户的分数。\n*   `raw_score` – 原始分析分数。\n*   `mask_urls` – 检测蒙版的 URL。\n\n**响应示例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"output\": [\n        {\n          \"type\": \"texture\",\n          \"ui_score\": 68,\n          \"raw_score\": 57.33,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n        },\n        {\n          \"type\": \"pore\",\n          \"ui_score\": 92,\n          \"raw_score\": 95.34,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n        }\n        // Additional results omitted for brevity\n      ]\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n\n* 排障指引\n> **警告：** 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。偏离这些规范会得到 ***InvalidParameters*** 错误。\n\n  * 若您混用 HD 与 SD 的皮肤问题参数，会得到如下错误：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"cannot mix HD and SD dst_actions\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n  * 若您拼错皮肤问题名称，或传入未知的皮肤问题，会得到如下错误：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"Not available dst_action abc123\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n\n---\n\n* 实际案例：\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## 输入与输出\n* 输入参数说明\n控制 AI 肤质分析结果视觉呈现的方式有两种：要么生成多张图片，每项皮肤问题各出一张独立蒙版；要么用 ``enable_mask_overlay`` 参数合成一张叠加图。系统默认输出多张蒙版，如何把每项皮肤问题的蒙版与图片混合，完全由您掌握。\n\n* 默认：enable_mask_overlay false\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* 把 enable_mask_overlay 设为 true\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* 输出 ZIP 数据结构说明\n系统会提供一个 ZIP 文件，里面有一个 'skinanalysisResult' 文件夹。该文件夹中有一份 'score_info.json'，收录全部检测分数以及结果图片的对应关系。\n\n'score_info.json' 收录所有测肤检测结果，包含数值分数与对应输出蒙版文件的名称。\n\nPNG 文件是检测结果蒙版，可以叠加到您的原图上。直接用这些 PNG 的 alpha 值与原图混合，就能在原图上直接看到检测结果。\n\n* AI 肤质分析 ZIP 的文件结构\n* HD 护肤 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - hd_acne_output.png\n    - hd_age_spot_output.png\n    - hd_dark_circle_output.png\n    - hd_droopy_lower_eyelid_output.png\n    - hd_droopy_upper_eyelid_output.png\n    - hd_eye_bag_output.png\n    - hd_firmness_output.png\n    - hd_moisture_output.png\n    - hd_oiliness_output.png\n    - hd_radiance_output.png\n    - hd_redness_output.png\n    - hd_texture_output.png\n    - hd_pore_output_all.png\n    - hd_pore_output_cheek.png\n    - hd_pore_output_forehead.png\n    - hd_pore_output_nose.png\n    - hd_wrinkle_output_all.png\n    - hd_wrinkle_output_crowfeet.png\n    - hd_wrinkle_output_forehead.png\n    - hd_wrinkle_output_glabellar.png\n    - hd_wrinkle_output_marionette.png\n    - hd_wrinkle_output_nasolabial.png\n    - hd_wrinkle_output_periocular.png\n    - hd_tear_trough.png\n    - hd_skin_type.png\n\n* SD 护肤 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - acne_output.png\n    - age_spot_output.png\n    - dark_circle_v2_output.png\n    - droopy_lower_eyelid_output.png\n    - droopy_upper_eyelid_output.png\n    - eye_bag_output.png\n    - firmness_output.png\n    - moisture_output.png\n    - oiliness_output.png\n    - pore_output.png\n    - radiance_output.png\n    - redness_output.png\n    - texture_output.png\n    - wrinkle_output.png\n    - tear_trough.png\n    - skin_type.png\n\n* JSON 数据结构（score_info.json）\n  * \"all\"：1 到 100 之间的浮点数，代表整体皮肤状况。分数越高，皮肤越健康、观感越好。\n  * \"skin_age\"：由 AI 推算的皮肤年龄，参照全年龄段人群分布得出。\n  * 每个类别包含：\n    * \"raw_score\"：1 到 100 之间的浮点数。分数越高，皮肤越健康、观感越好。\n    * \"ui_score\"：1 到 100 之间的整数。UI 分数在美容评估中主要起心理激励的作用。我们会调整原始分数，让结果更讨喜——考虑到消费者普遍希望关于自己皮肤状况的评价更正面。这样的校准能让用户更有信心，同时守住美容心理学的底层框架。\n    * \"output_mask_name\"：对应输出蒙版图片的文件名。\n\n  * 类别与说明\n    * HD 护肤：\n        * \"hd_redness\"：衡量泛红严重程度。\n        * \"hd_oiliness\"：判定出油程度。\n        * \"hd_age_spot\"：检测老年斑与色素沉淀。\n        * \"hd_radiance\"：评估光泽度。\n        * \"hd_moisture\"：评估皮肤水润度。\n        * \"hd_dark_circle\"：分析眼下黑眼圈情况。\n        * \"hd_eye_bag\"：检测眼袋。\n        * \"hd_droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n        * \"hd_droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n        * \"hd_firmness\"：评估皮肤紧实度与弹性。\n        * \"hd_texture\"：子类别[whole]；分析整体皮肤纹理。\n        * \"hd_acne\"：子类别[whole]；检测痘痘情况。\n        * \"hd_pore\"：子类别[forehead, nose, cheek, whole]；检测并评估脸部各区域的毛孔。\n        * \"hd_wrinkle\"：子类别[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；衡量脸部各区域皱纹的严重程度。\n        * \"hd_tear_trough\"：检测泪沟。\n        * \"hd_skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n    * SD 护肤：\n        * \"wrinkle\"：皱纹综合分析。\n        * \"droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n        * \"droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n        * \"firmness\"：评估皮肤紧实度与弹性。\n        * \"acne\"：评估痘痘情况。\n        * \"moisture\"：衡量皮肤水润度。\n        * \"eye_bag\"：检测眼袋。\n        * \"dark_circle_v2\"：以另一套方法分析黑眼圈。\n        * \"age_spot\"：检测老年斑。\n        * \"radiance\"：评估皮肤明亮度。\n        * \"redness\"：衡量泛红程度。\n        * \"oiliness\"：判定出油程度。\n        * \"pore\"：衡量毛孔明显程度。\n        * \"texture\"：分析整体皮肤纹理。\n        * \"tear_trough\"：检测泪沟。\n        * \"skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n  * HD 护肤的 score_info.json 示例\n    ```json\n    {\n        \"hd_redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_redness_output.png\"\n        },\n        \"hd_oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"hd_oiliness_output.png\"\n        },\n        \"hd_age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_age_spot_output.png\"\n        },\n        \"hd_radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_radiance_output.png\"\n        },\n        \"hd_moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"hd_moisture_output.png\"\n        },\n        \"hd_dark_circle\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"hd_dark_circle_output.png\"\n        },\n        \"hd_eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_eye_bag_output.png\"\n        },\n        \"hd_droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n        },\n        \"hd_droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n        },\n        \"hd_firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"hd_firmness_output.png\"\n        },\n        \"hd_texture\": {\n            \"whole\": {\n                \"raw_score\": 66.3921568627451,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_texture_output.png\"\n            }\n        },\n        \"hd_acne\": {\n            \"whole\": {\n                \"raw_score\": 59.92677688598633,\n                \"ui_score\": 76,\n                \"output_mask_name\": \"hd_acne_output.png\"\n            }\n        },\n        \"hd_pore\": {\n            \"forehead\": {\n                \"raw_score\": 79.59770965576172,\n                \"ui_score\": 80,\n                \"output_mask_name\": \"hd_pore_output_forehead.png\"\n            },\n            \"nose\": {\n                \"raw_score\": 29.139814376831055,\n                \"ui_score\": 58,\n                \"output_mask_name\": \"hd_pore_output_nose.png\"\n            },\n            \"cheek\": {\n                \"raw_score\": 44.11081314086914,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_pore_output_cheek.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.23978805541992,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_pore_output_all.png\"\n            }\n        },\n        \"hd_wrinkle\": {\n            \"forehead\": {\n                \"raw_score\": 55.96956729888916,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n            },\n            \"glabellar\": {\n                \"raw_score\": 76.7251181602478,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n            },\n            \"crowfeet\": {\n                \"raw_score\": 83.4361481666565,\n                \"ui_score\": 78,\n                \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n            },\n            \"periocular\": {\n                \"raw_score\": 67.88706302642822,\n                \"ui_score\": 72,\n                \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n            },\n            \"nasolabial\": {\n                \"raw_score\": 74.03312683105469,\n                \"ui_score\": 74,\n                \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n            },\n            \"marionette\": {\n                \"raw_score\": 71.94477319717407,\n                \"ui_score\": 73,\n                \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.64699745178223,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n            }\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n  * SD 护肤的 score_info.json 示例\n    ```json\n    {\n        \"wrinkle\": {\n            \"raw_score\": 36.09360456466675,\n            \"ui_score\": 60,\n            \"output_mask_name\": \"wrinkle_output.png\"\n        },\n        \"droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n        },\n        \"droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n        },\n        \"firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"firmness_output.png\"\n        },\n        \"acne\": {\n            \"raw_score\": 92.29713000000001,\n            \"ui_score\": 88,\n            \"output_mask_name\": \"acne_output.png\"\n        },\n        \"moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"moisture_output.png\"\n        },\n        \"eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"eye_bag_output.png\"\n        },\n        \"dark_circle_v2\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"dark_circle_v2_output.png\"\n        },\n        \"age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"age_spot_output.png\"\n        },\n        \"radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"radiance_output.png\"\n        },\n        \"redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"redness_output.png\"\n        },\n        \"oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"oiliness_output.png\"\n        },\n        \"pore\": {\n            \"raw_score\": 88.38014125823975,\n            \"ui_score\": 84,\n            \"output_mask_name\": \"pore_output.png\"\n        },\n        \"texture\": {\n            \"raw_score\": 80.09742498397827,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"texture_output.png\"\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ---- | ---- |\n| SD 护肤 | 短边长度至少 480 像素。 <br> 长边不限制；但超过 2560 像素时，系统会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 护肤 | 短边长度至少 1080 像素。 <br> 长边不限制；但超过 2560 像素时，会自动缩放到 2560 像素。 |< 10MB | jpg/jpeg/png |\n\n> **警告：** 接口会自动把图片缩放到最大 2560 像素，但请自行确保所有人脸清楚合焦、画质够高、光线均匀、人脸足够大且正对相机。拍摄 HD 或 SD 护肤图片、准备跑 AI 肤质分析之前，务必避开运动模糊与遮挡。为获得最佳效果，强烈建议采用竖幅（肖像）比例，不要横幅。\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n* 开始测肤前的准备说明\n* 摘下眼镜，确认刘海没有遮住额头\n* 确保您处在光线充足的环境中\n* 卸妆后再测，结果更准\n* 直视镜头，把脸保持在画面中央\n\n* 照片要求\n我们会检查图片质量，确认它适合跑 AI 肤质分析。请确保脸部约占图片宽度的 60–80%，没有任何叠加物或遮挡。光线要明亮且分布均匀，避免过曝与高光溢出。姿态须正对镜头、自然放松，嘴巴闭合、眼睛睁开。\n\n请完整露出额头，把刘海往后梳或把头发扎起来，保证质量最佳。建议摘下眼镜，AI 肤质分析表现更好，这一项不是强制要求。\n> **警告：** 脸部宽度需大于图片宽度的 60%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|输入图片分辨率过小|\n|error_exceed_max_image_size|输入图片分辨率过大|\n|error_src_face_too_small|上传图片中的脸部区域太小。脸部宽度需大于图片宽度的 60%。|\n|error_src_face_out_of_bound|上传图片中的脸部区域超出画面边界|\n|error_lighting_dark|上传图片的光线太暗|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 肤质分析 V2.1\n\n| AI 功能 | SD | HD | 加购高级测肤报告 | 加购商品推荐 |\n|---|---|---|---|---|\n| 分析 1~4 项皮肤问题 | 9 | 12 | +15 点 | +10 点 |\n| 分析 5~8 项皮肤问题 | 12 | 16 | +25 点 | +15 点 |\n| 分析 9~12 项皮肤问题 | 14 | 20 | +35 点 | +20 点 |\n| 分析 13~16 项皮肤问题 | 16 | 22 | +40 点 | +25 点 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n\n## 使用场景\n\n**Base URL：** `https://yce-api-01.makeupar.com`\n**分析接口：** `POST /s2s/v2.1/task/skin-analysis`\n**鉴权：** `Authorization: Bearer YOUR_API_KEY` —— 请注意 `Bearer` 与密钥之间只有一个空格。\n\n```bash\nexport API_KEY=\"your-api-key\"\nexport BASE_URL=\"https://yce-api-01.makeupar.com\"\n```\n\n每种使用场景各自对应一个接口，按您需要哪些加购能力来选择：\n\n| 模式 | `advanced_report` | `product_recommendation` | `llm_results.json` 里能拿到什么 |\n|---|---|---|---|\n| **[AI 肤质分析（标准）](/reference/ai_skin_analysis/standard-analysis/endpoint-overview)** | 不传 | 不传 | 各检测维度的皮肤问题评分 |\n| **[AI 肤质分析 + 高级测肤报告](/reference/ai_skin_analysis/analysis-+-advanced-report/endpoint-overview)** | 传入 | 不传 | 评分，外加一份讲成因与护理建议的个性化报告 |\n| **[AI 肤质分析 + 商品推荐](/reference/ai_skin_analysis/analysis-+-product-recommendation/endpoint-overview)** | 不传 | 传入 | 评分，外加从您的商品目录里匹配出的商品 |\n| **[AI 肤质分析 + 高级测肤报告 + 商品推荐](/reference/ai_skin_analysis/analysis-+-report-+-recommendation/endpoint-overview)** | 传入 | 传入 | 一次调用同时拿到评分、报告与商品匹配结果 |\n\n> **说明：** 带加购能力的模式会在基础点数之外产生额外的点数消耗。详情请见 [点数消耗](/reference/ai_skin_analysis/section/overview/unit-consumption)。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_skin_analysis_v2_0.yaml","link":"/zh-cn/reference/ai_skin_analysis_v2_0","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0","label":"AI 肤质分析 V2.0","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/点数消耗"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/js-camera-kit"},{"type":"link","label":"Mobile Camera Kit","link":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/mobile-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/section/概览/mobile-camera-kit"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0","items":[{"label":"执行 AI 肤质分析 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis/post","metadata":{"seo":{"title":"执行 AI 肤质分析 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/skin-analysis"},{"label":"查询 AI 肤质分析 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_analysis_v2_0/v2.0/paths/~1s2s~1v2.0~1task~1skin-analysis~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 肤质分析 任务的状态。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/skin-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 肤质分析","version":"","description":"# 概览\n![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_demostore_skincarelive_topbanner.0cffe3a7.jpg)\nAI 肤质分析技术借助人工智能分析皮肤的方方面面——纹理、色素、水润度、毛孔大小——精准度相当高。依靠先进算法与机器学习，AI 肤质分析只凭一张正脸自拍照就能评估脸部皮肤问题，给出准确的问题评分与检测蒙版，从而为每个人的肤质与困扰量身推荐产品与护肤流程。\n\n这不但提升了护肤产品的有效性，也让用户能为自己的护肤方案做出明白的抉择。接入 AI 肤质分析之后，用户就能在数据洞察的指引下，走向更健康、更透亮的肌肤，收获更有效的护肤方案。\n\n\n## 接入指南\n* AI 肤质分析怎么拍照\n* 正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n  - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 接口流程\n**测肤接口使用指引**\n本指引说明如何用 File 接口与 AI 任务接口上传图片并创建 AI 肤质分析。\n\n   * **第 1 步：调整源图尺寸**</br>\n  把图片缩放到支持的尺寸范围——SD 为长边不超过 2560 像素、短边至少 480 像素；HD 为长边不超过 2560 像素、短边至少 1080 像素。详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n   * **第 2 步：通过 File 接口上传文件元数据**\n- 图片要求\n    - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n发送 POST 请求初始化文件上传：\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/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n- ***重要***：只调用 File 接口并不等于上传了文件。您必须**另外把文件上传到 File 接口响应中给出的那个 URL**。那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。\n\n  > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n***\n\n   * **第 3 步：取得上传 URL 与文件 ID**\n\n响应中包含：\n\n*   `requests.url` – 用于上传图片的预签名 URL。\n*   `file_id` – 创建 AI 任务用的标识。\n\n**响应示例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/png\",\n        \"file_name\": \"skin_analysis_01_3dbd1b6683.png\",\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/png\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n***\n\n   * **第 4 步：把图片上传到预签名 URL**\n\n使用提供的 `requests.url` 与请求头：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/png' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./skin_analysis_01_3dbd1b6683.png'\n```\n\n***\n\n   * **第 5 步：创建 AI 任务**\n\n用第 2 步取得的 `file_id` 创建 AI 肤质分析：\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"src_file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n    \"dst_actions\": [\"wrinkle\", \"pore\", \"texture\", \"acne\"],\n    \"miniserver_args\": {\n      \"enable_mask_overlay\": true,\n      \"enable_dark_background_hd_pore\": true,\n      \"color_dark_background_hd_pore\": \"3D3D3D\",\n      \"opacity_dark_background_hd_pore\": 0.4\n      // Additional parameters omitted for brevity\n    },\n    \"format\": \"json\"\n  }'\n```\n  上传完成后，就可以用文件 ID 或图片文件 URL 选择要分析的皮肤问题，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。</br>\n  随后用文件 ID 或图片文件 URL 调用 POST 'task/skin-analysis' 执行任务，\n  并取得 ***task_id***。\n  请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。\n\n- **使用已有的公开图片 URL**\n不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。\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用 `task_id` 取回任务结果：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/skin-analysis/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json'\n```\n用这个 ***task_id*** 轮询 GET 'task/skin-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n处理完成的结果保留 30 天。\n- 不必用很短的间隔轮询。\n- 在保留期限内，轮询间隔可以自由安排。\n\n  > **重要：** 由于执行时长没有保证，仍然需要轮询来查看任务状态。\n\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n\n***\n\n   * **第 7 步：解读结果**\n\n响应中包含：\n\n*   `ui_score` – 面向用户的分数。\n*   `raw_score` – 原始分析分数。\n*   `mask_urls` – 检测蒙版的 URL。\n\n**响应示例：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"output\": [\n        {\n          \"type\": \"texture\",\n          \"ui_score\": 68,\n          \"raw_score\": 57.33,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...texture_output.jpg\"]\n        },\n        {\n          \"type\": \"pore\",\n          \"ui_score\": 92,\n          \"raw_score\": 95.34,\n          \"mask_urls\": [\"https://yce-us.s3-accelerate.amazonaws.com/...pore_output.jpg\"]\n        }\n        // Additional results omitted for brevity\n      ]\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n\n* 排障指引\n> **警告：** 请注意，SD 与 HD 的皮肤问题参数**不可**同时混用。偏离这些规范会得到 ***InvalidParameters*** 错误。\n\n  * 若您混用 HD 与 SD 的皮肤问题参数，会得到如下错误：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"cannot mix HD and SD dst_actions\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n  * 若您拼错皮肤问题名称，或传入未知的皮肤问题，会得到如下错误：\n    ```json\n    {\n        \"status\": 400,\n        \"error\": \"Not available dst_action abc123\",\n        \"error_code\": \"InvalidParameters\"\n    }\n    ```\n\n---\n\n* 实际案例：\n![](https://plugins-media.makeupar.com/webconsultation/images/skincare-widget/img_webcm_skincare_service_survey_demo.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/skin_analysis_s5_poster_3_dt_85efe14952.png)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Skincare_Pro_Medspa_Situation_Image_6aea6046f9.jpg)\n\n## 输入与输出\n* 输入参数说明\n控制 AI 肤质分析结果视觉呈现的方式有两种：要么生成多张图片，每项皮肤问题各出一张独立蒙版；要么用 ``enable_mask_overlay`` 参数合成一张叠加图。系统默认输出多张蒙版，如何把每项皮肤问题的蒙版与图片混合，完全由您掌握。\n\n* 默认：enable_mask_overlay false\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_false_1920_ea1cde0ead.png)\n\n* 把 enable_mask_overlay 设为 true\n  ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/mask_overlay_1920_0fbb4786cc.png)\n\n----\n\n* 输出 ZIP 数据结构说明\n系统会提供一个 ZIP 文件，里面有一个 'skinanalysisResult' 文件夹。该文件夹中有一份 'score_info.json'，收录全部检测分数以及结果图片的对应关系。\n\n'score_info.json' 收录所有测肤检测结果，包含数值分数与对应输出蒙版文件的名称。\n\nPNG 文件是检测结果蒙版，可以叠加到您的原图上。直接用这些 PNG 的 alpha 值与原图混合，就能在原图上直接看到检测结果。\n\n* AI 肤质分析 ZIP 的文件结构\n* HD 护肤 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - hd_acne_output.png\n    - hd_age_spot_output.png\n    - hd_dark_circle_output.png\n    - hd_droopy_lower_eyelid_output.png\n    - hd_droopy_upper_eyelid_output.png\n    - hd_eye_bag_output.png\n    - hd_firmness_output.png\n    - hd_moisture_output.png\n    - hd_oiliness_output.png\n    - hd_radiance_output.png\n    - hd_redness_output.png\n    - hd_texture_output.png\n    - hd_pore_output_all.png\n    - hd_pore_output_cheek.png\n    - hd_pore_output_forehead.png\n    - hd_pore_output_nose.png\n    - hd_wrinkle_output_all.png\n    - hd_wrinkle_output_crowfeet.png\n    - hd_wrinkle_output_forehead.png\n    - hd_wrinkle_output_glabellar.png\n    - hd_wrinkle_output_marionette.png\n    - hd_wrinkle_output_nasolabial.png\n    - hd_wrinkle_output_periocular.png\n    - hd_tear_trough.png\n    - hd_skin_type.png\n\n* SD 护肤 ZIP\n  * skinanalysisResult\n    - score_info.json\n    - acne_output.png\n    - age_spot_output.png\n    - dark_circle_v2_output.png\n    - droopy_lower_eyelid_output.png\n    - droopy_upper_eyelid_output.png\n    - eye_bag_output.png\n    - firmness_output.png\n    - moisture_output.png\n    - oiliness_output.png\n    - pore_output.png\n    - radiance_output.png\n    - redness_output.png\n    - texture_output.png\n    - wrinkle_output.png\n    - tear_trough.png\n    - skin_type.png\n\n* JSON 数据结构（score_info.json）\n  * \"all\"：1 到 100 之间的浮点数，代表整体皮肤状况。分数越高，皮肤越健康、观感越好。\n  * \"skin_age\"：由 AI 推算的皮肤年龄，参照全年龄段人群分布得出。\n  * 每个类别包含：\n    * \"raw_score\"：1 到 100 之间的浮点数。分数越高，皮肤越健康、观感越好。\n    * \"ui_score\"：1 到 100 之间的整数。UI 分数在美容评估中主要起心理激励的作用。我们会调整原始分数，让结果更讨喜——考虑到消费者普遍希望关于自己皮肤状况的评价更正面。这样的校准能让用户更有信心，同时守住美容心理学的底层框架。\n    * \"output_mask_name\"：对应输出蒙版图片的文件名。\n\n  * 类别与说明\n    * HD 护肤：\n        * \"hd_redness\"：衡量泛红严重程度。\n        * \"hd_oiliness\"：判定出油程度。\n        * \"hd_age_spot\"：检测老年斑与色素沉淀。\n        * \"hd_radiance\"：评估光泽度。\n        * \"hd_moisture\"：评估皮肤水润度。\n        * \"hd_dark_circle\"：分析眼下黑眼圈情况。\n        * \"hd_eye_bag\"：检测眼袋。\n        * \"hd_droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n        * \"hd_droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n        * \"hd_firmness\"：评估皮肤紧实度与弹性。\n        * \"hd_texture\"：子类别[whole]；分析整体皮肤纹理。\n        * \"hd_acne\"：子类别[whole]；检测痘痘情况。\n        * \"hd_pore\"：子类别[forehead, nose, cheek, whole]；检测并评估脸部各区域的毛孔。\n        * \"hd_wrinkle\"：子类别[forehead, glabellar, crowfeet, periocular, nasolabial, marionette, whole]；衡量脸部各区域皱纹的严重程度。\n        * \"hd_tear_trough\"：检测泪沟。\n        * \"hd_skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n    * SD 护肤：\n        * \"wrinkle\"：皱纹综合分析。\n        * \"droopy_upper_eyelid\"：衡量上眼皮下垂程度。\n        * \"droopy_lower_eyelid\"：衡量下眼皮下垂程度。\n        * \"firmness\"：评估皮肤紧实度与弹性。\n        * \"acne\"：评估痘痘情况。\n        * \"moisture\"：衡量皮肤水润度。\n        * \"eye_bag\"：检测眼袋。\n        * \"dark_circle_v2\"：以另一套方法分析黑眼圈。\n        * \"age_spot\"：检测老年斑。\n        * \"radiance\"：评估皮肤明亮度。\n        * \"redness\"：衡量泛红程度。\n        * \"oiliness\"：判定出油程度。\n        * \"pore\"：衡量毛孔明显程度。\n        * \"texture\"：分析整体皮肤纹理。\n        * \"tear_trough\"：检测泪沟。\n        * \"skin_type\"：子类别[whole, t_zone, u_zone]，评估肤质：Normal、Oily、Dry、Combination、Redness、Dry & Redness、Oily & Redness、Combination & Redness。\n\n  * HD 护肤的 score_info.json 示例\n    ```json\n    {\n        \"hd_redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_redness_output.png\"\n        },\n        \"hd_oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"hd_oiliness_output.png\"\n        },\n        \"hd_age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"hd_age_spot_output.png\"\n        },\n        \"hd_radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_radiance_output.png\"\n        },\n        \"hd_moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"hd_moisture_output.png\"\n        },\n        \"hd_dark_circle\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"hd_dark_circle_output.png\"\n        },\n        \"hd_eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"hd_eye_bag_output.png\"\n        },\n        \"hd_droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"hd_droopy_upper_eyelid_output.png\"\n        },\n        \"hd_droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"hd_droopy_lower_eyelid_output.png\"\n        },\n        \"hd_firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"hd_firmness_output.png\"\n        },\n        \"hd_texture\": {\n            \"whole\": {\n                \"raw_score\": 66.3921568627451,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_texture_output.png\"\n            }\n        },\n        \"hd_acne\": {\n            \"whole\": {\n                \"raw_score\": 59.92677688598633,\n                \"ui_score\": 76,\n                \"output_mask_name\": \"hd_acne_output.png\"\n            }\n        },\n        \"hd_pore\": {\n            \"forehead\": {\n                \"raw_score\": 79.59770965576172,\n                \"ui_score\": 80,\n                \"output_mask_name\": \"hd_pore_output_forehead.png\"\n            },\n            \"nose\": {\n                \"raw_score\": 29.139814376831055,\n                \"ui_score\": 58,\n                \"output_mask_name\": \"hd_pore_output_nose.png\"\n            },\n            \"cheek\": {\n                \"raw_score\": 44.11081314086914,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_pore_output_cheek.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.23978805541992,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_pore_output_all.png\"\n            }\n        },\n        \"hd_wrinkle\": {\n            \"forehead\": {\n                \"raw_score\": 55.96956729888916,\n                \"ui_score\": 67,\n                \"output_mask_name\": \"hd_wrinkle_output_forehead.png\"\n            },\n            \"glabellar\": {\n                \"raw_score\": 76.7251181602478,\n                \"ui_score\": 75,\n                \"output_mask_name\": \"hd_wrinkle_output_glabellar.png\"\n            },\n            \"crowfeet\": {\n                \"raw_score\": 83.4361481666565,\n                \"ui_score\": 78,\n                \"output_mask_name\": \"hd_wrinkle_output_crowfeet.png\"\n            },\n            \"periocular\": {\n                \"raw_score\": 67.88706302642822,\n                \"ui_score\": 72,\n                \"output_mask_name\": \"hd_wrinkle_output_periocular.png\"\n            },\n            \"nasolabial\": {\n                \"raw_score\": 74.03312683105469,\n                \"ui_score\": 74,\n                \"output_mask_name\": \"hd_wrinkle_output_nasolabial.png\"\n            },\n            \"marionette\": {\n                \"raw_score\": 71.94477319717407,\n                \"ui_score\": 73,\n                \"output_mask_name\": \"hd_wrinkle_output_marionette.png\"\n            },\n            \"whole\": {\n                \"raw_score\": 49.64699745178223,\n                \"ui_score\": 65,\n                \"output_mask_name\": \"hd_wrinkle_output_all.png\"\n            }\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n  * SD 护肤的 score_info.json 示例\n    ```json\n    {\n        \"wrinkle\": {\n            \"raw_score\": 36.09360456466675,\n            \"ui_score\": 60,\n            \"output_mask_name\": \"wrinkle_output.png\"\n        },\n        \"droopy_upper_eyelid\": {\n            \"raw_score\": 79.05348539352417,\n            \"ui_score\": 80,\n            \"output_mask_name\": \"droopy_upper_eyelid_output.png\"\n        },\n        \"droopy_lower_eyelid\": {\n            \"raw_score\": 79.97175455093384,\n            \"ui_score\": 81,\n            \"output_mask_name\": \"droopy_lower_eyelid_output.png\"\n        },\n        \"firmness\": {\n            \"raw_score\": 89.66898322105408,\n            \"ui_score\": 85,\n            \"output_mask_name\": \"firmness_output.png\"\n        },\n        \"acne\": {\n            \"raw_score\": 92.29713000000001,\n            \"ui_score\": 88,\n            \"output_mask_name\": \"acne_output.png\"\n        },\n        \"moisture\": {\n            \"raw_score\": 48.694559931755066,\n            \"ui_score\": 70,\n            \"output_mask_name\": \"moisture_output.png\"\n        },\n        \"eye_bag\": {\n            \"raw_score\": 76.67280435562134,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"eye_bag_output.png\"\n        },\n        \"dark_circle_v2\": {\n            \"raw_score\": 80.1993191242218,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"dark_circle_v2_output.png\"\n        },\n        \"age_spot\": {\n            \"raw_score\": 83.23274230957031,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"age_spot_output.png\"\n        },\n        \"radiance\": {\n            \"raw_score\": 76.57244205474854,\n            \"ui_score\": 79,\n            \"output_mask_name\": \"radiance_output.png\"\n        },\n        \"redness\": {\n            \"raw_score\": 72.011962890625,\n            \"ui_score\": 77,\n            \"output_mask_name\": \"redness_output.png\"\n        },\n        \"oiliness\": {\n            \"raw_score\": 60.74365234375,\n            \"ui_score\": 72,\n            \"output_mask_name\": \"oiliness_output.png\"\n        },\n        \"pore\": {\n            \"raw_score\": 88.38014125823975,\n            \"ui_score\": 84,\n            \"output_mask_name\": \"pore_output.png\"\n        },\n        \"texture\": {\n            \"raw_score\": 80.09742498397827,\n            \"ui_score\": 76,\n            \"output_mask_name\": \"texture_output.png\"\n        },\n        \"all\": {\n            \"score\": 75.75757575757575\n        },\n        \"skin_age\": 37\n    }\n    ```\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ---- | ---- |\n| SD 护肤 | 短边长度至少 480 像素。 <br> 长边不限制；但超过 2560 像素时，系统会自动缩放到 2560 像素。 | < 10MB | jpg/jpeg/png |\n| HD 护肤 | 短边长度至少 1080 像素。 <br> 长边不限制；但超过 2560 像素时，会自动缩放到 2560 像素。 |< 10MB | jpg/jpeg/png |\n\n> **警告：** 接口会自动把图片缩放到最大 2560 像素，但请自行确保所有人脸清楚合焦、画质够高、光线均匀、人脸足够大且正对相机。拍摄 HD 或 SD 护肤图片、准备跑 AI 肤质分析之前，务必避开运动模糊与遮挡。为获得最佳效果，强烈建议采用竖幅（肖像）比例，不要横幅。\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n* 开始测肤前的准备说明\n* 摘下眼镜，确认刘海没有遮住额头\n* 确保您处在光线充足的环境中\n* 卸妆后再测，结果更准\n* 直视镜头，把脸保持在画面中央\n\n* 照片要求\n我们会检查图片质量，确认它适合跑 AI 肤质分析。请确保脸部约占图片宽度的 60–80%，没有任何叠加物或遮挡。光线要明亮且分布均匀，避免过曝与高光溢出。姿态须正对镜头、自然放松，嘴巴闭合、眼睛睁开。\n\n请完整露出额头，把刘海往后梳或把头发扎起来，保证质量最佳。建议摘下眼镜，AI 肤质分析表现更好，这一项不是强制要求。\n> **警告：** 脸部宽度需大于图片宽度的 60%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_error_src_face_too_small_cr_725792a7fb.png)\n\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|输入图片分辨率过小|\n|error_exceed_max_image_size|输入图片分辨率过大|\n|error_src_face_too_small|上传图片中的脸部区域太小。脸部宽度需大于图片宽度的 60%。|\n|error_src_face_out_of_bound|上传图片中的脸部区域超出画面边界|\n|error_lighting_dark|上传图片的光线太暗|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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* AI 肤质分析 V2.0\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| 分析 1~4 项皮肤问题 | SD 9 点；HD 12 点 | \n| 分析 5~8 项皮肤问题 | SD 12 点；HD 16 点 |\n| 分析 9~12 项皮肤问题 | SD 14 点；HD 20 点 |\n| 分析 13~16 项皮肤问题 | SD 16 点；HD 22 点 |\n\n---\n\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Mobile Camera Kit\n{% partial file=\"/_partials/mobile-camera-kit.md\" /%}\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_skin_simulation.yaml","link":"/zh-cn/reference/ai_skin_simulation","routeSlug":"/zh-cn/reference/ai_skin_simulation","label":"肌肤拟真","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_skin_simulation/section/概览","routeSlug":"/zh-cn/reference/ai_skin_simulation/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_skin_simulation/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_skin_simulation/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_skin_simulation/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_skin_simulation/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_skin_simulation/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_simulation/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_skin_simulation/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_skin_simulation/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_skin_simulation/v1.0","routeSlug":"/zh-cn/reference/ai_skin_simulation/v1.0","items":[{"label":"执行 肌肤拟真 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","routeSlug":"/zh-cn/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation/post","metadata":{"seo":{"title":"执行 肌肤拟真 任务。","description":"本接口用于发起肌肤拟真流程。您需要提供源文件（URL 或文件 ID），并指定模拟参数（皱纹、光泽等），且至少有一项不能为 0。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/skin-simulation"},{"label":"查询 肌肤拟真 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_simulation/v1.0/paths/~1s2s~1v2.0~1task~1skin-simulation~1{task_id}/get","metadata":{"seo":{"title":"查询 肌肤拟真 任务的状态。","description":"查询 肌肤拟真 任务的状态。"}},"httpPath":"/s2s/v2.0/task/skin-simulation/{task_id}"}]}],"metadata":{"type":"openapi","title":"肌肤拟真","version":"","description":"# 概览\n**AI 驱动的显老/肤质模拟：精准、专业地可视化护理成效**\n\n我们这套前沿的 AI 肤质模拟技术，能对脸部皮肤状态做出高度还原的调整前后对比，让专业人员和消费者都能客观追踪护肤方案随时间的效果。方案以高保真写实与临床级洞察为设计目标，最多可支持 10 项皮肤问题的可视化：光泽度、痘痘、出油、眼袋、黑眼圈、斑点、毛孔、肤质纹理、皱纹、泛红。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-17/4edad54f-ef6b-4842-b104-d114889318b1.jpg)\n\n系统把精密的机器学习模型与强大的增强现实能力结合在一起，只用一部普通手机相机或电脑摄像头，就能给出逼真、非侵入式的成效预览。每次模拟几秒钟完成，用户立刻就能得到一个有科学依据的直观认知：针对性的护肤干预会怎样让肤色肤质随时间变好。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_27e3ad50-7769-46de-822c-c9300f87f57d.webp)\n\n这套平台专为护肤品牌、皮肤科诊所、医美机构、美妆零售打造，在数字与线下各触点都能轻松接入，包括电商网站、移动应用、线上咨询、门店自助终端。可用场景很广：个性化护肤方案推荐、产品效果模拟、专业疗程方案规划，以及互动式科普工具——这些都能提升客户参与度，让品牌主张更可信。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_pores_b1e209ee58.jpg)\n\n借助客观的可视化与数据驱动的呈现，我们的 AI 肤质模拟帮助护肤专业人员设定合理预期、定制护理方案、展示可量化的进展，最终把客户体验抬上一个台阶，在日趋竞争的市场里坐实\"有效果、有依据\"。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Skin_Simulation_283421234a.jpg)\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![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_skin_analysis_01_5b5defd339.png)\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</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_skin_tone_analysis.yaml","link":"/zh-cn/reference/ai_skin_tone_analysis","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis","label":"AI 面部色调分析器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_skin_tone_analysis/v1.0","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/v1.0","items":[{"label":"执行 AI 面部色调分析器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post","metadata":{"seo":{"title":"执行 AI 面部色调分析器 任务。","description":"本接口用于发起 AI 面部色调分析器流程。您需要提供源文件（URL 或文件 ID），并可选指定脸部角度的严格程度。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis"},{"label":"查询 AI 面部色调分析器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 面部色调分析器 任务的状态。","description":"查询 AI 面部色调分析器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/skin-tone-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 面部色调分析器","version":"","description":"# 概览\nAI 面部色调分析器可检测脸部肤色，以及眼睛、眉毛、嘴唇和头发的颜色。这套包容性技术能让各种肤色的顾客都有量身定制的购物体验。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png)\n\n\n## 接入指南\n* AI 面部色调分析器怎么拍照\n\n  正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n  - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 如何用 AI 检测肌肤问题\n1. **调整源图尺寸**</br>\n  把图片缩放到支持的尺寸范围，详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n2. **用 File 接口上传文件**</br>\n  通过 ***/s2s/v2.0/file*** 接口上传目标用户图片。\n    - 图片要求\n      - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n3. **执行 AI 面部色调分析器任务**</br>\n  上传完成后，AI 会用您的文件 ID 分析嘴唇、眼睛、眉毛、皮肤与头发的色调，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。</br>\n  随后用文件 ID 调用 POST 'task/skin-tone-analysis' 执行任务，\n  并取得 ***task_id***。\n\n4. **轮询任务状态，直到成功或报错**</BR>\n用这个 ***task_id*** 轮询 GET 'task/skin-tone-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n    **警告：** 请注意，**轮询**任务状态必须按任务保留期来执行，是强制要求。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样（您的点数照样会被消耗）。\n\n    > **警告：** 若去查询已超时任务的状态，会收到 ***InvalidTaskId*** 错误。因此，执行 AI 任务之后，必须在保留期内持续**轮询**，直到状态变为 *success* 或 *error*。\n\n5. **任务成功后取回结果**</BR>\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。</BR>\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg)\n\n---\n\n## 输入与输出\n* 输入\nAI 会分析您皮肤的色调。您可以调整 `face_angle_strictness_level`，控制对输入脸部角度的校验严格度，档位从严格、高、中、低到宽松。该严格度作用于脸部角度检测，包括俯仰角、偏航角与翻滚角。档位越严，脸部属性结果越准。默认设置为高。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg)\n\n* 输出\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"success\",\n    \"results\": {\n      \"color\": {\n        \"eye_color\": \"#293F9B\",\n        \"eye_color_name\": \"Blue\",\n        \"lip_color\": \"#D23245\",\n        \"eyebrow_color\": \"#5B2B31\",\n        \"skin_color\": \"#b9947c\",\n        \"hair_color\": \"#a0a0a0\",\n        \"hair_color_name\": \"Auburn\"\n      }\n    }\n  }\n}\n```\n\n| **结果参数** | **结果类型** |\n|  --- | --- |\n| `skin_color` | 十六进制色值 |\n| `eye_color`| 十六进制色值 |\n| `eye_color_name` | Amber、Brown、Green、Blue、Gray、Other |\n| `lip_color` | 十六进制色值 |\n| `eyebrow_color` | 十六进制色值 |\n| `hair_color` | 十六进制色值 |\n| `color.hair_color_name` | Auburn、Black、Blonde、Brown、Grey/White、Red |\n\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n> **警告：** 脸部宽度需大于图片宽度的 60%。\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 面部色调分析器 | 长边 <= 4096，仅支持单人。任一维度超过 1080 像素的图片会自动缩放后进行分析。 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_below_min_image_size | 原图尺寸不得低于 320 像素。 |\n| error_face_position_invalid | 人脸须完整可见、正对镜头，并位于画面中央。 |\n| error_face_position_too_small | 检测到的人脸太小，无法分析。 |\n| error_face_position_out_of_boundary | 人脸超出了画面边界。 |\n| error_face_not_forward_facing | 人脸必须正对镜头。 |\n| error_face_angle_upward | 脸部过度朝上——请把头略微低一点。 |\n| error_face_angle_downward | 脸部过度朝下——请把头略微抬一点。 |\n| error_face_angle_leftward | 脸部过度朝左——请把头略微向右转。 |\n| error_face_angle_rightward | 脸部过度朝右——请把头略微向左转。 |\n| error_face_angle_left_tilt | 脸部向左侧倾斜过多——请把头轻轻向右扶正。 |\n| error_face_angle_right_tilt | 脸部向右侧倾斜过多——请把头轻轻向左扶正。 |\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 面部色调分析器 V1.0 | 20 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_face_analyzer.yaml","link":"/zh-cn/reference/ai_face_analyzer","routeSlug":"/zh-cn/reference/ai_face_analyzer","label":"面部属性与比例分析","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_face_analyzer/section/概览","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_face_analyzer/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_face_analyzer/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_face_analyzer/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_face_analyzer/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_face_analyzer/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_face_analyzer/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_face_analyzer/v1.0","routeSlug":"/zh-cn/reference/ai_face_analyzer/v1.0","items":[{"label":"执行 面部属性与比例分析 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","routeSlug":"/zh-cn/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post","metadata":{"seo":{"title":"执行 面部属性与比例分析 任务。","description":"本接口用于发起面部五官分析流程。您需要提供源文件（URL 或文件 ID），并指定要分析的项目。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/face-attr-analysis"},{"label":"查询 面部属性与比例分析 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1{task_id}/get","metadata":{"seo":{"title":"查询 面部属性与比例分析 任务的状态。","description":"查询 面部属性与比例分析 任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-attr-analysis/{task_id}"}]}],"metadata":{"type":"openapi","title":"面部属性与比例分析","version":"","description":"# 概览\nAI 面部属性与比例分析会检视脸部结构，识别脸型、眼型、眉型、唇型、鼻型、颧骨等特征，用来提供量身定制的建议。\n\n## 接入指南\n* AI 面部属性与比例分析怎么拍照\n\n* 正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发最好自然放下，整张脸都要露出来、不要有遮挡。把头发往后梳、露出额头，视线直视前方，拍出标准的正脸角度。\n  - 也可以用 JS Camera Kit 拍照。跟着自动脸部对齐、光线引导和脸部大小检测走，保证照片符合处理要求。\n\n* 如何用 AI 检测肌肤问题\n\n1. **调整源图尺寸**</br>\n  把图片缩放到支持的尺寸范围，详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n2. **用 File 接口上传文件**</br>\n  通过 ***/s2s/v2.0/file*** 接口上传目标用户图片。\n    - 图片要求\n      - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n3. **执行 AI 面部属性与比例分析任务**</br>\n  上传完成后，就可以用文件 ID 选择要分析的多项脸部特征，详见 **[输入与输出](#section/overview/Inputs-and-Outputs)**。</br>\n  随后用文件 ID 调用 POST 'task/face-attr-analysis' 执行任务，\n  并取得 ***task_id***。\n\n4. **轮询任务状态，直到成功或报错**</BR>\n用这个 ***task_id*** 轮询 GET 'task/face-attr-analysis' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n    **警告：** 请注意，**轮询**任务状态必须按任务保留期来执行，是强制要求。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样（您的点数照样会被消耗）。\n\n    > **警告：** 若去查询已超时任务的状态，会收到 ***InvalidTaskId*** 错误。因此，执行 AI 任务之后，必须在保留期内持续**轮询**，直到状态变为 *success* 或 *error*。\n\n5. **任务成功后取回结果**</BR>\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。</BR>\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n* 实际案例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg)\n\n## 输入与输出\n* 脸部特征：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg)\n\n| **类别**     | **子类别**   | **请求参数** | **结果参数** | **结果类型** |\n| --- | --- | --- |  --- | --- |\n| **脸型 FACE** | 脸型 | `faceShape` | `faceshape` | Triangle、Diamond、Heart、InvTriangle、Oblong、Oval、Round、Square、Unknown |\n| **年龄与性别 AGE & GENDER** | 年龄 | `age` | `agegender.age` | 整数 |\n| | 性别 | `gender` | `agegender.gender` | female、male、unknown |\n| **眼睛 EYES** | 眼型 | `eyeShape` | `eyelid.left_shape`、`eyelid.right_shape` | Narrow、Round、Almond |\n| | 眼睛大小 | `eyeSize` | `eyelid.size` | Big、Small、Average |\n| | 眼型角度 | `eyeAngle` | `eyelid.left_angle`、`eyelid.right_angle` | Downturned、Upturned、Average |\n| | 眼距 | `eyeDistance` | `eyelid.setting` | Close-set、Wide-Set、Average |\n| | 眼皮 | `eyelid` | `eyelid.left_eyelid`、`eyelid.right_eyelid` | Hooded-lid、Single-lid、Double-lid、Deep-Set |\n| **眉毛 BROWS** | 眉型 | `eyebrowShape` | `eyebrow.left_shape`、`eyebrow.right_shape` | Hard Angled、Soft Angled、Straight、Rounded、Obscured |\n| | 眉毛粗细 | `eyebrowThickness` | `eyebrow.left_body_thickness`、`eyebrow.right_body_thickness` | Dense、Sparse、Average、Unknown |\n| | 眉距 | `eyebrowDistance` | `eyebrow.gap` | Far-Apart、Close、Average |\n| | 眉毛长短 | `eyebrowShortness` | `eyebrow.left_shortness`、`eyebrow.right_shortness` | Short、Normal |\n| **嘴唇 LIPS** | 唇型 | `lipShape` | `lipshape[]` | Bow、Downturned、Full、Heavy Lower Lip、Heavy Upper Lip、Narrow、Round、Thin、Wide、Average |\n| **鼻子 NOSE** | 鼻子宽窄 | `noseWidth` | `nose.width` | Narrow、Broad、Average |\n| | 鼻子长短 | `noseLength` | `nose.length` | Long、Short、Average |\n| **颧骨 CHEEKBONES**   | 颧骨 | `cheekbones` | `cheekbone.left`、`cheekbone.right`、`cheekbone.overall` | Flat Cheekbone、High Cheekbone、Low Cheekbone、Round Cheeks |\n\n\n---\n\n* 脸部比例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg)\n\n| **子类别** | **请求参数** | **结果参数** | **结果类型** | **说明** |\n| --- | --- | --- | --- | --- |\n| 横向三分比例 | `horizontalThird` | `horizontal_third` | 三段百分比；判读：Short / Balanced / Long；黄金比例：33% : 33% : 33% | 脸部横向比例把脸分成均等的三段：发际线到眉毛下缘、眉毛下缘到鼻底、鼻底到下巴尖。三段的理想比例（黄金比例）为 1:1:1。|\n| 纵向五等分比例 | `verticalFifth` | `vertical_fifth` | 五段百分比；判读（眼距与眼宽）：Narrow / Balanced / Wide；黄金比例：20% : 20% : 20% : 20% : 20% | 脸部纵向比例把脸分成五段：一只眼睛的宽度、两眼之间的距离，以及眼外角到脸部两侧边缘的间距。这五段的黄金比例为 1:1:1:1:1。 |\n| 脸部长宽比 | `faceAspectRatio` | `face_aspect_ratio` | `[1, r]`；判读：Short / Balanced / Long；黄金比例：1 : 1.46 | 脸部长宽比是脸部宽度与高度的关系，理想值为黄金比例 1:1.46，观感均衡好看。 |\n| 眼睛长宽比 | `eyeAspectRatio` | `left_eye_aspect_ratio` `right_eye_aspect_ratio` | `[1, r]`；判读：Round / Balanced / Flat；黄金比例：1 : 3 | 眼睛长宽比是眼睛高度与宽度的关系，理想值为黄金比例 1:3，视觉上最协调。\n |\n| 眉弓比例 | `eyebrowArch` | `left_eyebrow_arch_to_eyebrow_width` `right_eyebrow_arch_to_eyebrow_width` | `[1, r]`；判读：Short Arch / Balanced / Long Arch；黄金比例：1 : 1.618 | 理想眉弓比例取决于眉毛本身的形状，最高点（眉弓）落在黄金比例上，看起来最协调。 |\n| 眼高与眉距 | `eyeHeightToEyebrowDistance` | `left_eye_height_to_eyebrow_distance` `right_eye_height_to_eyebrow_distance` `overall_eye_height_to_eyebrow_distance` | `[1, r]`；判读：Short / Balanced / Long；黄金比例：1 : 1.618 | 眼与眉的距离指上眼皮最高点到眉毛最高点的垂直距离。理想状态下，它与眼高的比为黄金比例 1.618:1，眼与眉的呼应最协调。 |\n| 鼻子长宽比 | `noseAspectRatio` | `nose_aspect_ratio` | `[1, r]`；判读：Wide / Balanced / Narrow；黄金比例：1 : 1.618 | 鼻子长宽比是鼻子宽度与高度的关系，理想值为黄金比例 1:1.618。 |\n| 鼻宽与嘴宽 | `noseWidthToMouthWidth` | `nose_width_to_mouth_width` | `[1, r]`；判读：Small / Balanced / Large；黄金比例：1 : 1.618 | 鼻宽与嘴宽的比例是鼻子宽度与嘴巴宽度的关系，理想值为黄金比例 1:1.618，观感均衡好看。 |\n| 鼻、唇、下巴 | `noseToLipToChin` | `nose_to_lip_to_chin` | `[1, r]`；判读：Short / Balanced / Long（下脸长度）；黄金比例：1 : 1.618 | 鼻唇下巴比例指鼻底到唇中心的距离为 1，唇中心到下巴的理想距离为 1.618。这个黄金比例让下半张脸均衡协调，符合脸部对称的原则。 |\n| 上唇与下唇 | `upperLipToLowerLip` | `upper_lip_to_lower_lip` | `[1, r]`；判读：Full Upper / Balanced / Full Lower；黄金比例：1 : 1.618 | 上唇与下唇的黄金比例建议下唇厚度为上唇的 1.618 倍。这个比例观感均衡好看，下唇比上唇略丰润。 |\n\n----\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png)\n\n> **警告：** 脸部宽度需大于图片宽度的 60%。\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 面部属性与比例分析|长边 <= 4096，仅支持单人。任一维度超过 1080 像素的图片会自动缩放后进行分析。|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_below_min_image_size | 原图尺寸不得低于 320 像素。 |\n| error_face_position_invalid | 人脸须完整可见、正对镜头，并位于画面中央。 |\n| error_face_position_too_small | 检测到的人脸太小，无法分析。 |\n| error_face_position_out_of_boundary | 人脸超出了画面边界。 |\n| error_face_not_forward_facing | 人脸必须正对镜头。 |\n| error_face_angle_upward | 脸部过度朝上——请把头略微低一点。 |\n| error_face_angle_downward | 脸部过度朝下——请把头略微抬一点。 |\n| error_face_angle_leftward | 脸部过度朝左——请把头略微向右转。 |\n| error_face_angle_rightward | 脸部过度朝右——请把头略微向左转。 |\n| error_face_angle_left_tilt | 脸部向左侧倾斜过多——请把头轻轻向右扶正。 |\n| error_face_angle_right_tilt | 脸部向右侧倾斜过多——请把头轻轻向左扶正。 |\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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* 面部属性与比例分析\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| 1~5 项脸部结构特征 | 10 |\n| 6~14 项脸部结构特征 | 20 |\n| 15~28 项脸部结构特征 | 30 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_aging_simulation.yaml","link":"/zh-cn/reference/ai_aging_simulation","routeSlug":"/zh-cn/reference/ai_aging_simulation","label":"AI 年龄模拟器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_aging_simulation/section/概览","routeSlug":"/zh-cn/reference/ai_aging_simulation/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_aging_simulation/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_aging_simulation/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_aging_simulation/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_aging_simulation/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_aging_simulation/v1.0","routeSlug":"/zh-cn/reference/ai_aging_simulation/v1.0","items":[{"label":"执行 AI 年龄模拟器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","routeSlug":"/zh-cn/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging/post","metadata":{"seo":{"title":"执行 AI 年龄模拟器 任务。","description":"本接口用于发起 AI 年龄模拟器流程。您需要提供源文件（URL 或文件 ID）。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/aging"},{"label":"查询 AI 年龄模拟器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_aging_simulation/v1.0/paths/~1s2s~1v2.0~1task~1aging~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 年龄模拟器 任务的状态。","description":"查询 AI 年龄模拟器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/aging/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 年龄模拟器","version":"","description":"# 概览\nAI 年龄模拟生成基于生成式 AI 模型，用一张自拍就能生成从年轻到年长的一整组照片。在 AI 的帮助下，它既能估出您现在的年龄，还能让您看到未来的自己、过去的自己。\n\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/f42f1504_79e3_461c_a3f1_a254623d113b_b068736afb.jpg \"AI Aging Generator\")\n\nAI 年龄模拟生成只需一张自拍作为输入，即可生成一整组照片。下面这组示例可帮您快速了解这项功能。\n![AI Aging Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/U_2024_04_17_cr_12112b83e2.png \"AI Aging Generator\")\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 年龄模拟器 | 长边 <= 4096，仅支持单人。脸部姿态要求：偏航角 ±30° 以内，翻滚角 ±20° 以内，俯仰角 ±20° 以内。 | < 10MB | jpg/jpeg |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_below_min_image_size | 原图尺寸不得低于 320 像素。 |\n| error_face_position_invalid | 人脸须完整可见、正对镜头，并位于画面中央。 |\n| error_face_position_too_small | 检测到的人脸太小，无法分析。 |\n| error_face_position_out_of_boundary | 人脸超出了画面边界。 |\n| error_face_not_forward_facing | 人脸必须正对镜头。 |\n| error_face_angle_upward | 脸部过度朝上——请把头略微低一点。 |\n| error_face_angle_downward | 脸部过度朝下——请把头略微抬一点。 |\n| error_face_angle_leftward | 脸部过度朝左——请把头略微向右转。 |\n| error_face_angle_rightward | 脸部过度朝右——请把头略微向左转。 |\n| error_face_angle_left_tilt | 脸部向左侧倾斜过多——请把头轻轻向右扶正。 |\n| error_face_angle_right_tilt | 脸部向右侧倾斜过多——请把头轻轻向左扶正。 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 年龄模拟器 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_face_reshape.yaml","link":"/zh-cn/reference/ai_face_reshape","routeSlug":"/zh-cn/reference/ai_face_reshape","label":"AI 面部塑形","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_face_reshape/section/概览","routeSlug":"/zh-cn/reference/ai_face_reshape/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_face_reshape/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_face_reshape/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_face_reshape/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_face_reshape/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_face_reshape/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_face_reshape/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_face_reshape/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_face_reshape/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_face_reshape/v1.0","routeSlug":"/zh-cn/reference/ai_face_reshape/v1.0","items":[{"label":"执行 AI 面部塑形 检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","routeSlug":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post","metadata":{"seo":{"title":"执行 AI 面部塑形 检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process"},{"label":"查询 AI 面部塑形 检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 面部塑形 检测任务的状态。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/face-reshape/pre-process/{task_id}"},{"label":"执行 AI 面部塑形 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","routeSlug":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post","metadata":{"seo":{"title":"执行 AI 面部塑形 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/face-reshape"},{"label":"查询 AI 面部塑形 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 面部塑形 任务的状态。","description":"查询 AI 面部塑形 任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 面部塑形","version":"","description":"# 概览\nAI 面部塑形接口可以用程序调整五官——眼睛、鼻子、嘴唇、下颌线，乃至整张脸——控制精准到像素。用它生成隆鼻、下巴填充、丰唇、提眉等各类医美疗程的调整前后对比。\n\n* 隆鼻\n我们的线上隆鼻模拟提供医疗级精度的调整。它和普通修图软件不一样，能对鼻梁、翘度、鼻翼等细节做完整模拟。以假乱真的预览效果，让来访者在咨询之前就把理想比例看清楚、试明白。\n\n* 下巴填充\n通过线上模拟，您可以预览下巴填充后的理想比例。微调下巴长度与下巴形状，看看后缩或偏短的下巴能改善到什么程度。在做任何皮肤填充疗程之前，先找出让您侧脸比例最协调的方案。\n\n* 嘴唇填充\n用户可以尝试不同的填充剂量与唇形，模拟出更丰润的唇部外观，在疗程之前就把想要的效果定下来。\n\n* 提眉手术\n这个功能让用户预览提眉的效果——把眉毛上提并重塑形状，做出更年轻、更有精神的面貌。\n\n\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 面部塑形接口的流程：\n\n**接口地址：** `/s2s/v2.0/file`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n    - 准备好要上传的自拍照。\n    - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n    - 用提供的上传 URL 把自拍照上传上去。\n\n2. **多张人脸时的可选预处理：**\n    - 图中有多于一张人脸时，请先对自拍照做预处理。\n\n3. **设置 AI 面部塑形特效：**\n   - 先选好眼部、脸部、唇部或鼻部的合适塑形参数。\n\n4. **发起 AI 任务并取得 Task ID：**\n   - 把 `file_id` 连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/face-reshape`。\n   - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n5. **轮询任务状态（持续检查）：**\n   - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/face-reshape/${task_id}`）。\n   - 持续留意：\n     - `Task_status = \"success\"`（处理完成）。\n     - `Task_status = \"error\"`（视情况排查或重试）。\n   - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/)\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\n1. 上传图片\n\n    您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n    * 上传接口\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n2. 准备特效模板\n\n   * 预处理\n        输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建 AI 面部塑形 AI 任务。\n        ```\n        {\n            \"timed\": number,\n            \"result\": [\n                {\n                    \"left\": number,\n                    \"top\": number,\n                    \"width\": number,\n                    \"height\": number\n                }\n            ]\n        }\n        ```\n\n        * 特效模板 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"index\": 0,\n            \"features\": {},\n            \"global\": {\n            \"skin_smooth_strength\": 50,\n            \"skin_smooth_color_intensity\": 50,\n            },\n        }\n        ```\n        index：预处理检测到的人脸下标。选填，默认 0。\n        features：至少需要 1 项非零的 AI 面部塑形参数，不能全为 0。\n        skin_smooth_strength：0~100\n        skin_smooth_color_intensity：0~100\n\n        * 特效格式\n        - 脸部\n        默认范围：-100~100\n        颧骨与下颌的范围：0~100\n        所有特征值不得同时为 0，至少要有一项特征值非 0\n        ```\n        {\n            \"cheekbones\": 0,\n            \"jaw\": 0,\n            \"face_reshape_left\": 0,\n            \"face_reshape_right\": 0,\n            \"face_width\": 0,\n            \"chin_reshape_left\": 0,\n            \"chin_reshape_right\": 0,\n            \"chin_length\": 0,\n        }\n        ```\n\n        - 眼部\n        默认范围：-100~100\n        所有特征值不得同时为 0，至少要有一项特征值非 0\n        ```\n        {\n            \"eye_size_left\": 0,\n            \"eye_size_right\": 0,\n            \"eye_distance\": 0,\n            \"eye_angle\": 0,\n            \"eye_height\": 0,\n            \"eye_width\": 0,\n        }\n        ```\n\n        - 鼻部\n        默认范围：-100~100\n        所有特征值不得同时为 0，至少要有一项特征值非 0\n        ```\n        {\n            \"nose_bridge_width\": 0,\n            \"nose_lift\": 0,\n            \"nose_size\": 0,\n            \"nose_tip\": 0,\n            \"nose_tip_width\": 0,\n            \"nose_wing\": 0\n        }\n        ```\n\n        - 唇部\n        默认范围：-100~100\n        所有特征值不得同时为 0，至少要有一项特征值非 0\n        ```\n        {\n            \"lip_size\": 0,\n            \"lip_width\": 0,\n            \"lip_peak\": 0,\n            \"lip_height_top\": 0,\n            \"lip_height_bottom\": 0,\n        }\n        ```\n\n        * 请求示例（可直接发送）\n        ```\n        {\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg\",\n        \"version\": \"1.0\",\n        \"source\": \"yco\",\n        \"features\": {\n            \"eye_size_left\": 80,\n            \"eye_size_right\": 80,\n            \"eye_width\": 0,\n            \"eye_height\": 0,\n            \"eye_distance\": 0,\n            \"eye_angle\": 0,\n            \"face_reshape_left\": 0,\n            \"face_reshape_right\": 0,\n            \"chin_reshape_left\": 20,\n            \"chin_reshape_right\": 20,\n            \"chin_length\": 0,\n            \"face_width\": -30,\n            \"cheekbones\": 0,\n            \"jaw\": 0,\n            \"lip_size\": 10,\n            \"lip_width\": 40,\n            \"lip_height_top\": 10,\n            \"lip_height_bottom\": 10,\n            \"lip_peak\": -10,\n            \"nose_size\": 30,\n            \"nose_lift\": -20,\n            \"nose_bridge_width\": 10,\n            \"nose_tip\": -10,\n            \"nose_wing\": 30,\n            \"nose_tip_width\": 30\n        },\n        \"global\": {\n            \"skin_smooth_strength\": 50,\n            \"skin_smooth_color_intensity\": 50\n        }\n        }\n        ```\n\n\n3. 创建 AI 面部塑形 AI 任务并轮询结果\n\n    图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n        ```\n        POST /s2s/v2.0/task/face-reshape\n        ```\n\n   * 轮询接口\n\n        ```\n        GET /s2s/v2.0/task/face-reshape/{task_id}\n        ```\n\n---\n\n## 文件规格与错误码\n\n* AI 面部塑形规格\n\n**支持的自拍视角**\n自拍照中脸部宽高需大于图片宽高的 1/20。\n俯仰角、偏航角、翻滚角均须小于 30 度。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n\n**五官自定义参数说明**\n\n| 类别 | 参数        | 作用                             | 最小（-100 / 0） | 最大（100）    |\n| -------- | ---------------- | ------------------------------------ | -------------- | ------------ |\n| 眼睛     | Size（左/右）       | 缩放每只眼睛的整体大小      | 小          | 大        |\n| 眼睛     | Width            | 调整水平跨度              | 窄         | 宽         |\n| 眼睛     | Height           | 调整垂直跨度                | 窄 / 扁  | 圆 / 高 |\n| 眼睛     | Distance         | 调整两眼间距         | 近距      | 宽距     |\n| 眼睛     | Angle            | 调整旋转倾斜              | 内倾    | 外倾 |\n| 脸部     | Size（左/右）       | 缩放脸部每一侧的大小 | 小          | 大        |\n| 脸部     | Chin Shape（左/右） | 调整下巴轮廓宽度           | 窄         | 宽         |\n| 脸部     | Chin Length      | 调整下巴的垂直长度         | 短          | 长         |\n| 脸部     | Width            | 调整整体脸部宽度         | 窄         | 宽         |\n| 脸部     | Cheekbone        | 调整颧骨突出程度         | 原样（0）   | 收进去    |\n| 脸部     | Jaw              | 调整下颌线突出程度           | 原样（0）   | 收进去    |\n| 嘴唇     | Size             | 缩放唇部整体体积            | 小          | 大        |\n| 嘴唇     | Width            | 调整水平跨度              | 窄         | 宽         |\n| 嘴唇     | Upper Height     | 调整上唇厚度            | 薄           | 丰         |\n| 嘴唇     | Lower Height     | 调整下唇厚度         | 薄           | 丰         |\n| 嘴唇     | Peak             | 调整唇峰锐度        | 平滑         | 明显      |\n| 鼻子     | Size             | 缩放鼻子整体大小             | 小          | 大        |\n| 鼻子     | Lift             | 调整垂直位置            | 低            | 高         |\n| 鼻子     | Bridge           | 调整鼻梁宽度                 | 窄         | 宽         |\n| 鼻子     | Tip              | 调整鼻头的垂直角度    | 上             | 下         |\n| 鼻子     | Wing             | 调整鼻翼宽度                | 窄         | 宽         |\n| 鼻子     | Width            | 调整鼻头宽度        | 窄         | 宽         |\n\n**说明：** *“左”与“右”以人物自身视角为准，不是观看者屏幕的左右侧。*\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 面部塑形|长边 <= 4096|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n| 错误码 | 说明 |\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户图片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 对象图片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户图片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 面部塑形 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_body_reshape.yaml","link":"/zh-cn/reference/ai_body_reshape","routeSlug":"/zh-cn/reference/ai_body_reshape","label":"AI 身形塑形","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_body_reshape/section/概览","routeSlug":"/zh-cn/reference/ai_body_reshape/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_body_reshape/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_body_reshape/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_body_reshape/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_body_reshape/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_body_reshape/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_body_reshape/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_body_reshape/v1.0","routeSlug":"/zh-cn/reference/ai_body_reshape/v1.0","items":[{"label":"执行 AI 身形塑形 检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","routeSlug":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post","metadata":{"seo":{"title":"执行 AI 身形塑形 检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process"},{"label":"查询 AI 身形塑形 检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 身形塑形 检测任务的状态。","description":"查询 AI 身形塑形 检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/body-reshape/pre-process/{task_id}"},{"label":"执行 AI 身形塑形 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","routeSlug":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post","metadata":{"seo":{"title":"执行 AI 身形塑形 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/body-reshape"},{"label":"查询 AI 身形塑形 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 身形塑形 任务的状态。","description":"查询 AI 身形塑形 任务的状态。"}},"httpPath":"/s2s/v2.0/task/body-reshape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 身形塑形","version":"","description":"# 概览\nAI 身形塑形接口：塑形与瘦身\n用 AI 身体编辑，照片里更有底气！把身材瘦下去、塑形、优化，比例自然又亮眼。腰、手臂、大腿、胸，任何部位都能轻松调整；点一下就是自然出彩的效果。\n\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 身形塑形接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/body-reshape`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n    - 准备好要上传的自拍照。\n    - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n    - 用提供的上传 URL 把自拍照上传上去。\n\n2. **多人合照的可选预处理：**\n    - 图中有多于一人时，请先对自拍照做预处理。\n\n3. **设置 AI 身形塑形特效：**\n    - 先选好合适的 AI 身形塑形参数。\n\n4. **发起 AI 任务并取得 Task ID：**\n    - 把 `file_id` 连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/body-reshape`。\n    - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n5. **轮询任务状态（持续检查）：**\n    - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/body-reshape/${task_id}`）。\n    - 持续留意：\n    - `Task_status = \"success\"`（处理完成）。\n    - `Task_status = \"error\"`（视情况排查或重试）。\n    - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n* 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 2. 准备特效模板\n\n* 预处理\n输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建 AI 身形塑形任务。\n```\n{\n\"timed\": number,\n\"result\": [\n{\n \"left\": number,\n \"top\": number,\n \"width\": number,\n \"height\": number\n}\n]\n}\n```\n\n* 特效模板 JSON Schema\n```\n{\n\"version\": \"1.0\",\n\"index\": 0,\n\"features\": {\n\"arm\": 0, // -100~100\n\"breast_left\": 0, // -100~100\n\"breast_right\": 0, // -100~100\n\"hip\": 0, // -100~100\n\"hip_lift\": 0, // -100~100\n\"leg\": 0, // -100~100\n\"neck_left\": 0, // 0~100\n\"neck_right\": 0, // 0~100\n\"shoulder_left\": 0, // -100~100\n\"shoulder_right\": 0, // -100~100\n\"squared_shoulder_left\": 0, // -100~100\n\"squared_shoulder_right\": 0, // -100~100\n\"slim\": 0, // -100~100\n\"taller\": 0, // 0~100\n\"waist\": 0, // -100~100\n\"belly\": 0 // -100~100\n}\n}\n```\nindex：预处理检测到的身体对象下标。选填，默认 0。\nfeatures：至少需要 1 项非零的 AI 身形塑形参数，不能全为 0。\n\n\n* 请求示例（可直接发送）\n```\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/body_reshape_02_7777218379.jpg\",\n \"version\": \"1.0\",\n \"index\": 0,\n \"features\": {\n\"arm\": 0,\n\"waist\": -20,\n\"taller\": 80,\n\"squared_shoulder_left\": 10,\n\"squared_shoulder_right\": 10,\n\"neck_left\": 0,\n\"neck_right\": 0,\n\"hip\": 10,\n\"breast_left\": 30,\n\"breast_right\": 30,\n\"slim\": -70,\n\"shoulder_left\": 30,\n\"shoulder_right\": 30,\n\"leg\": -30,\n\"hip_lift\": 0,\n\"belly\": -50\n }\n}\n```\n\n\n* 3. 创建 AI 身形塑形任务并轮询结果\n\n图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n* 创建任务接口\n\n```\nPOST /s2s/v2.0/task/body-reshape\n```\n\n* 轮询接口\n\n```\nGET /s2s/v2.0/task/body-reshape/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 身形塑形规格\n\n**支持的自拍视角**\n全身照，面部表情与身体姿态都要清楚可见。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg)\n\n**可见性与姿态要求**\n\n| **部位** | **源图必须满足的条件** |\n|------------|---------------------------------------------------|\n| **颈部** | 源图中颈部必须可见。 |\n| **手臂** | 双臂——上臂、前臂与手——都要完整呈现。 |\n| **腿部** | 整条腿都要在画面内。 |\n| **臀部** | 臀部需要在画面内。 |\n| **提臀** | 臀部需要在画面内。 |\n| **肩部** | • 肩部必须可见。<br>• 不允许举手。<br>• 不允许 90° 侧身姿态。 |\n| **腹部** | 腹部必须可见。 |\n| **腰部** | 腰部必须可见。 |\n| **胸部** | • 胸部区域需在画面内。<br>• 拍摄范围应包含臀部（即不能是\"不含臀部的半身照\"）。<br>• 胸部中间位置必须呈现。 |\n| **显瘦** | 肩部需要在画面内。 |\n| **增高** | • 臀部必须呈现。<br>• 半身照应包含腿部（即腿部可见）。 |\n\n\n\n**AI 身形塑形自定义参数说明**\n\n| 类别 | 参数 | 作用 | 最小值（-100 / 0） | 最大值（100） |\n| -------- | --------- | -------- | -------------------- | --------------- |\n| 手臂| Intensity | 调整手臂粗细 | 细 | 粗 |\n| 腹部| Intensity | 调整腹部凸起 | 平坦 | 凸出 |\n| 胸部| Intensity（左 / 右） | 分别调整两侧胸部体积 | 平坦 | 饱满 |\n| 提臀 | Intensity | 调整臀部曲线与上提（起到提臀效果） | 紧致（上提收紧） | 圆润（上提且更饱满） |\n| 臀宽 | Intensity | 调整臀部整体宽度 | 窄 | 宽 |\n| 腿部| Intensity | 调整腿部粗细 | 细 | 粗|\n| 颈部| Intensity（左 / 右） | 分别调整两侧颈部轮廓与收紧 | 原样（0）| 收进去 |\n| 肩宽 | Intensity（左 / 右） | 分别调整两侧肩部跨度 | 窄 | 宽 |\n| 肩型 | Intensity（左 / 右） | 分别调整两侧肩部角度与斜度 | 溜肩 | 平肩 |\n| 显瘦| Intensity | 调整整体身体曲线 | 纤瘦 | 曲线明显 |\n| 增高| Intensity | 调整整体人物身高 | 原样（0） | 更高 |\n| 腰部| Intensity | 调整腰线的宽窄 | 窄 | 宽 |\n\n**说明：** *“左”与“右”以人物自身视角为准，不是观看者屏幕的左右侧。*\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 身形塑形|长边 <= 2048，短边 >= 320|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---- | ---- |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户图片无法正确处理，例如未检测到手 |\n| PHOTO_CHECK_INVALID | 用户图片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58 (modern TLS/HTTP support)</br>- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 身形塑形 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_breast_augmentation.yaml","link":"/zh-cn/reference/ai_breast_augmentation","routeSlug":"/zh-cn/reference/ai_breast_augmentation","label":"AI 隆胸模拟器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_breast_augmentation/section/概览","routeSlug":"/zh-cn/reference/ai_breast_augmentation/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_breast_augmentation/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_breast_augmentation/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_breast_augmentation/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_breast_augmentation/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_breast_augmentation/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_breast_augmentation/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_breast_augmentation/v1.0","routeSlug":"/zh-cn/reference/ai_breast_augmentation/v1.0","items":[{"label":"执行 AI 隆胸模拟器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","routeSlug":"/zh-cn/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape/post","metadata":{"seo":{"title":"执行 AI 隆胸模拟器 任务。","description":"本接口用于发起 AI 隆胸模拟器流程。您需要提供源文件（URL 或文件 ID），并指定强度等级。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/breast-shape"},{"label":"查询 AI 隆胸模拟器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_breast_augmentation/v1.0/paths/~1s2s~1v2.0~1task~1breast-shape~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 隆胸模拟器 任务的状态。","description":"查询 AI 隆胸模拟器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/breast-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 隆胸模拟器","version":"","description":"# 概览\nAI 隆胸模拟器提供一套强有力的非侵入式身体塑形方案：不用手术，也不用恢复期。借助先进 AI 技术，您可以即刻看到、试出自己的理想外形，预览调整前后的对比，轻轻松松做出专业级的改善。\n\n自然地改善照片：修饰身形轮廓，校正透视问题。想要更均衡、更协调的上半身观感，AI 隆胸模拟器能做强化的胸部轮廓增强。该功能用智能算法在您希望的位置适度增加立体感与体积，做出含蓄真实的改善，同时保住您原有的特征与比例。最终效果是自信、精致的样子，毫无假感变形。\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/e41b8942-22e1-4846-8f81-f41171b74558.jpg)\n\n传统滤镜常做出夸张、失真的效果，这款工具不一样：它给出干净真实的修改，贴合您个人的身体条件。不论是为社交媒体、个人使用还是创作项目准备图片，改善效果都保持真实，同时把您最好的一面凸现出来。\n\n想开始体验虚拟身形修饰，只要创建一个 AI 隆胸模拟器任务，把强度一点点调到您满意的样子。随后还能调整增强强度等参数，贴合您的审美偏好；整套接口好用易上手，新手老手都合适。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-06-18/733cedfd-2e8e-4cfc-8758-6854d923664b.jpg)\n\n---\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 隆胸模拟器接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/breast-shape`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n   - 第一步是准备一张上半身自拍照。\n\n2. **AI 隆胸模拟器设置**\n    AI 隆胸模拟器用强度档位控制变化程度，范围从 1（细微）到 3（明显）。建议从低档位开始逐步调高，做出符合您审美的自然效果。一点点调，结果更真实、比例更协调。\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您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 调整 AI 隆胸模拟器强度\n**AI 隆胸模拟器设置**\n\nAI 隆胸模拟器的修改程度由强度档位控制，范围 **1 到 3**：\n- **1 档** 是含蓄自然的微调，适合小修小补。\n- **2 档** 为中等增强，真实感与明显改善之间取得平衡。\n- **3 档** 效果最明显，适合大幅度塑形，同时仍符合人体合理性。\n\n按您的审美目标与想要的样子，选择合适的强度档位。\n\n---\n\n* 创建 AI 隆胸模拟器任务并轮询结果\n\n上传图片、选好强度档位后，就可以启动增强任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/breast-shape\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/breast-shape/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 隆胸模拟器规格\n**图片要求与建议，帮您拿到最佳效果**\n\n- **分辨率要求**：\n  输入图片最长边不得超过 4096 像素。为获得最佳表现，请确保上半身区域——从头顶到胸口（含胸口）——的分辨率不低于 1024 × 768 像素。\n\n- **人物要求**：\n  - 图片中至少要有一位可完整检测的人物，两侧肩膀都要在画面内清楚可见。\n  - 胸部区域必须可见。穿衣、不穿衣都可以，前提是人物基本正对镜头（即偏航角在 −90° 到 +90° 之间）。强烈建议采用正脸视角，不要斜侧或侧面。\n\n- **提升效果的建议做法**：\n  - 构图以上半身为主：图片最好专注上半身；若收录全身，上半身应占据画面相当大的比例，最长边超过 1024 像素。\n  - 只用正面姿态；避免侧身或明显转体，这些姿态会降低检测准确率与成品质量。\n  - 想让胸部轮廓增强得最自然，请选胸前露一些皮肤的服装——例如泳装、低领上衣、V 领服饰。这类款式能让 AI 更好地推断底层结构，做出含蓄真实的乳沟效果。\n  - 系统只支持单人图片。画面中有多人时，处理会自动锁定肩部可见跨度最大的那位（即离镜头最近、或最居中的人）。\n  - 避免胸前区域有遮挡。包、背包带、围巾、项链等配饰可能被误移除，或在编辑过程中产生瑕疵。\n  - 服装外观可能与原图不同。改变程度取决于强度档位：档位越高，变化越明显，胸前衣物的形状、版型与垂坠都可能出现可见改变。\n\n遵循以上要求，可保证输入质量最佳，让 AI 生成的增强效果最大程度还原真实、保持一致。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-1_2dfe3418c2.jpg)\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_02-2_a88356deeb.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 隆胸模拟器|最小：512x384 <BR>最大：长边 < 4096|< 10MB|jpg/jpeg/png/heic |\n\n* 错误码\n\n| 错误码                      | 说明 |\n|----------------------------------|-------------|\n| `invalid_parameter`             | 参数无效——具体是必填字段（`src_keys`、`dst_keys` 或 `acts`）中有一个或多个缺失、格式有误，或包含不支持的取值。 |\n| `exceed_max_filesize`           | 输入图片超出允许的文件大小上限（10 MB）。请先压缩或缩放图片再提交。 |\n| `error_download_image`          | 系统下载源图片失败，通常是网络问题、URL 无效，或资源权限不可访问。 |\n| `error_decode_image`            | 下载下来的图片无法解码——可能是文件损坏、格式不受支持，或二进制数据有误。 |\n| `error_nsfw_content_detected`   | 在源图或生成的输出图中检测到疑似不适宜内容（NSFW）。出于合规与安全考虑，处理已中止。 |\n| `error_pose`                    | 人体姿态估计失败：无法可靠检测出全身或上半身骨架，后续的形体分析因此无法进行。 |\n| `error_breast_region_detection` | 系统已依据姿态与分割线索尝试检测胸部区域，但未能找到有效、可辨识的胸部区域（例如因遮挡、角度过于偏斜，或可见度不足）。 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 隆胸模拟器 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_face_lift.yaml","link":"/zh-cn/reference/ai_face_lift","routeSlug":"/zh-cn/reference/ai_face_lift","label":"AI 面部提升","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_face_lift/section/概览","routeSlug":"/zh-cn/reference/ai_face_lift/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_face_lift/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_face_lift/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_face_lift/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_face_lift/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_face_lift/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_face_lift/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_face_lift/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_face_lift/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_face_lift/v1.0","routeSlug":"/zh-cn/reference/ai_face_lift/v1.0","items":[{"label":"执行 面部提升 检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","routeSlug":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process/post","metadata":{"seo":{"title":"执行 面部提升 检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process"},{"label":"查询 面部提升 检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 面部提升 检测任务的状态。","description":"查询 面部提升 检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-lift/pre-process/{task_id}"},{"label":"执行 面部提升 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","routeSlug":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift/post","metadata":{"seo":{"title":"执行 面部提升 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/face-lift"},{"label":"查询 面部提升 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_lift/v1.0/paths/~1s2s~1v2.0~1task~1face-lift~1{task_id}/get","metadata":{"seo":{"title":"查询 面部提升 任务的状态。","description":"查询 面部提升 任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-lift/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 面部提升","version":"","description":"# 概览\nAI 面部提升是一套生成式 AI 的脸部增强功能，靠可调参数做精准、自然的脸部修饰。它不套滤镜，而是智能分析脸部结构、皮肤质感与比例，再据此重建图像，做出真实的改善，同时保住个人原本的样貌特征。\n\n用户可以用 0 到 100 的数值控制眼袋、脸颊、额头、整体脸型、嘴部等具体部位。每个参数逐档提升增强程度，依使用者偏好，既可以轻轻修饰，也可以做得更精致。所有调整都以自然、协调为准则，避免夸张或假感的结果。\n\nAI 面部提升提供灵活的功能级控制，帮您做出清爽、自信、专业的形象，适合用在社交媒体、头像照、创作内容或商务用途。\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_6c0d97eb51.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_8c428a25dc.jpg)\n\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 面部提升接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/face-lift`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n  - 准备好要上传的自拍照。\n  - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n  - 用提供的上传 URL 把自拍照上传上去。\n\n2. **多张人脸时的可选预处理：**\n    - 图中有多于一张人脸时，请先对自拍照做预处理。\n\n3. **设置面部提升特效：**\n   - 先选好合适的面部提升参数。\n\n4. **发起 AI 任务并取得 Task ID：**\n   - 把 `file_id` 连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/face-lift`。\n   - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n5. **轮询任务状态（持续检查）：**\n   - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/face-lift${task_id}`）。\n   - 持续留意：\n     - `Task_status = \"success\"`（处理完成）。\n     - `Task_status = \"error\"`（视情况排查或重试）。\n   - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n\n---\n\n1.  鉴权\n    - 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n        ```\n        Authorization: Bearer YOUR_API_KEY\n        ```\n    API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n2.  上传图片\n\n    您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n    * 上传接口\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n3. 用预处理选定要增强的目标人脸\n\n   * 调用预处理接口\n    输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建面部提升 AI 任务。\n        ```\n        POST /s2s/v2.0/task/face-lift/pre-process\n        ```\n\n        ```\n        {\n            \"timed\": number,\n            \"result\": [\n                {\n                    \"left\": number,\n                    \"top\": number,\n                    \"width\": number,\n                    \"height\": number\n                }\n            ]\n        }\n        ```\n\n4. 创建面部提升 AI 任务并轮询结果\n\n    图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n        ```\n        POST /s2s/v2.0/task/face-lift\n        ```\n\n   * 轮询接口\n\n        ```\n        GET /s2s/v2.0/task/face-lift/{task_id}\n        ```\n\n---\n\n## 文件规格与错误码\n\n* AI 面部提升规格\n\n**支持的自拍视角**\n图片不得超过 1920 x 1920；长边为 640 时，图中人脸须清楚可见且尺寸大于 32 x 32 像素；拍摄时翻滚角须在正负 75 度以内、偏航角在正负 90 度以内，以确保人脸检测稳定可靠。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 面部提升 | 长边 <= 1920 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n| 错误码 | 说明 |\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户图片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 对象图片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户图片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 面部提升 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_smile.yaml","link":"/zh-cn/reference/ai_smile","routeSlug":"/zh-cn/reference/ai_smile","label":"AI 微笑救星","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_smile/section/概览","routeSlug":"/zh-cn/reference/ai_smile/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_smile/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_smile/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_smile/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_smile/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_smile/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_smile/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_smile/v1.0","routeSlug":"/zh-cn/reference/ai_smile/v1.0","items":[{"label":"执行 AI 微笑救星 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","routeSlug":"/zh-cn/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile/post","metadata":{"seo":{"title":"执行 AI 微笑救星 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/ai-smile"},{"label":"查询 AI 微笑救星 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_smile/v1.0/paths/~1s2s~1v2.0~1task~1ai-smile~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 微笑救星 任务的状态。","description":"查询 AI 微笑救星 任务的状态。"}},"httpPath":"/s2s/v2.0/task/ai-smile/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 微笑救星","version":"","description":"# 概览\n生成式 AI 微笑救星接口登场，让苦瓜脸笑开颜变得轻而易举。这个好用的 AI 微笑救星生成器，把难过或毫无表情的脸转成开心、自然的微笑，前后不过是片刻功夫。背后是先进的生成式 AI，流程简单不费事，随手一张照片都能添上暖意与朝气。上传图片，让 AI 大显身手，悲伤的面孔立刻变成灿烂笑脸，分享到哪里，快乐就传到哪里。\n\nAI 微笑救星生成器支持两种截然不同的笑容风格，让使用者对最终表情有更多掌控。\n\n1.  **smile_with_teeth_visible**  \n     这个选项做出明亮欢快的笑容，牙齿自然露出。适合意气风发的人像照、社群媒体照片，以及想要温暖、外放气质的场合。\n\n2.  **closed_mouth_smile**  \n     这个选项做出含蓄温柔的笑容，双唇轻闭。适合专业形象照、正式的个人档案，或想要沉静、自然表情的时候。\n\n使用者可以轻松挑出最合这张照片、这份心情、这个用途的笑容类型，回回都能得到真实又讨喜的结果。\n\n不论您是在修图、做有趣的内容，还是只想添一点阳光气息，生成式 AI 微笑救星都能让您把快乐散播出去，一次一个微笑。\n\n上传一张脸部照片，按一下，笑容立刻到位。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-03-22/5f25b0f7-5d43-421b-ae50-5def0de69f2a.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-12-16/4f4397e0-9e87-429a-8e39-a9d399b6602b.jpg)\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 微笑救星接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/ai-smile`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n    - 准备好要上传的自拍照。\n    - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n    - 用提供的上传 URL 把自拍照上传上去。\n\n2. **发起 AI 任务并取得 Task ID：**\n    - 把 `file_id` 连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/ai-smile`。\n    - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n3. **轮询任务状态（持续检查）：**\n    - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/ai-smile/${task_id}`）。\n    - 持续留意：\n        - `Task_status = \"success\"`（处理完成）。\n        - `Task_status = \"error\"`（视情况排查或重试）。\n    - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n\n---\n\n1. 鉴权\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\n2. 上传图片\n\n    您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n3. 创建 AI 微笑救星任务并轮询结果\n\n    图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n    * 创建任务接口\n\n        ```\n        POST /s2s/v2.0/task/ai-smile\n        ```\n\n    * 轮询接口\n\n        ```\n        GET /s2s/v2.0/task/ai-smile/{task_id}\n        ```\n\n---\n\n## 文件规格与错误码\n\n* AI 微笑救星规格\n\n**支持的自拍视角**\n仅支持单人图片。画面中须有一张清楚可见、尺寸足够大的脸——以长边 640 计算，脸部需超过 32 x 32 像素；拍摄角度的翻滚角须在正负 75 度以内、偏航角须在正负 90 度以内，以免人脸检测失败。\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg)\n\n\n---\n\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 微笑救星 | 长边 <= 4096 | < 10MB | jpg/jpeg/png/heic |\n\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---------- | ----------- |\n| EXCEED_MAX_FILESIZE  | 输入文件超过大小上限。 |\n| INVALID_PARAMETER     | 一项或多项必填参数缺失、为空，或格式不当。  |\n| ERROR_DOWNLOAD_IMAGE | 源图无法下载。 |\n| ERROR_NO_FACE        | 提供的图片中未检测到人脸。 |\n| ERROR_INFERENCE       | 推理流程失败，可能是流程问题、执行错误、编码错误，或输出图片缺失。 |\n| UNKNOWN_INTERNAL_ERROR | 发生非预期的内部错误。 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 微笑救星 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_fitzpatrick_skin_type.yaml","link":"/zh-cn/reference/ai_fitzpatrick_skin_type","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type","label":"AI Fitzpatrick 皮肤类型分析","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0","items":[{"label":"执行 AI Fitzpatrick 皮肤类型分析 检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process/post","metadata":{"seo":{"title":"执行 AI Fitzpatrick 皮肤类型分析 检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process"},{"label":"查询 AI Fitzpatrick 皮肤类型分析 检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI Fitzpatrick 皮肤类型分析 检测任务的状态。","description":"查询 AI Fitzpatrick 皮肤类型分析 检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process/{task_id}"},{"label":"执行 AI Fitzpatrick 皮肤类型分析 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer/post","metadata":{"seo":{"title":"执行 AI Fitzpatrick 皮肤类型分析 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer"},{"label":"查询 AI Fitzpatrick 皮肤类型分析 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_fitzpatrick_skin_type/v1.0/paths/~1s2s~1v2.0~1task~1fitzpatrick-scale-analyzer~1{task_id}/get","metadata":{"seo":{"title":"查询 AI Fitzpatrick 皮肤类型分析 任务的状态。","description":"查询 AI Fitzpatrick 皮肤类型分析 任务的状态。"}},"httpPath":"/s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Fitzpatrick 皮肤类型分析","version":"","description":"# 概览\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-01-28/webp_a00e88ca-e20a-4082-89c2-9d486b03b8e8.webp)\n\n**AI Fitzpatrick 皮肤类型分析**\n\n把 AI 驱动的Fitzpatrick肤色检测接入您的应用，用相机画面准确判定肤色类型。这个接口可帮助开发者在电商与数字健康平台上搭建个性化的护肤、防晒与商品推荐流程。\n\n**肤色检测**\n\n接口用计算机视觉与机器学习模型分析皮肤特征，一次请求即可返回Fitzpatrick分级。它给出结构化、客观的数据，前端应用、推荐引擎、临床系统可直接取用。\n\nFitzpatrick肤色量表由 Thomas B. Fitzpatrick 医生提出，依据黑色素水平与紫外线反应把皮肤分为六种类型，便于系统预测晒伤与晒黑的倾向。\n\n**分级结果**\n\n接口基于紫外线反应建模，返回 I 型到 VI 型六种标准肤色之一。\n\n有了这个结果，开发者可以给出针对性的商品推荐、让护肤流程自动化，并在各种使用场景中强化个性化，同时保持一致性与可扩展性。\n\n| Fitzpatrick量表 | 肤色类型 | 皮肤对日晒的反应 |\n|  ----  | ----  | ---- |\n| Type I | 白 | 几乎总是晒伤，从不晒黑 |\n| Type II |  米白 | 通常会晒伤，晒黑很有限 |\n| Type III | 浅棕 | 偶尔晒伤，会逐渐晒黑 |\n| Type V | 中棕 | 很少晒伤，很容易晒黑 |\n| Type V | 深棕 | 极少晒伤 |\n| Type VI | 极深棕 | 几乎不会晒伤 |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/fitapatrick_skin_type_S_02_enu_5e4343e801.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-03-10/webp_b9ca4198-1a9e-44df-9551-ac3ad8b65d17.webp)\n\n---\n\n## 接入指南\n\n**1. 采集图片**\n在光线充足的环境下拍一张正脸照。脸部要清楚可见，并在画面中占足够大的比例。\n\n\n**2. 上传图片**\n通过以下接口取得上传 URL 与文件 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n用返回的 URL 把图片上传上去。\n也可以提供您自有存储上可公开访问的图片 URL。\n\n\n**3. 可选的预处理**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process\n```\n\n图片中有多张人脸，或需要显式指定目标时使用这一步。单人脸图片若默认下标够用，这一步可以跳过。\n\n\n**4. 取得预处理结果**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/pre-process\n```\n\n配置 [webhook](/develop/webhook.md) 或实现轮询来取得任务结果。用 Webhook 时，任务完成后应用会自动收到通知；用轮询时，系统反复调用任务接口，直到状态从 running 变为 success 或 error。\n\n**5. 执行分析任务**\n\n```\nPOST /s2s/v2.0/task/fitzpatrick-scale-analyzer\n```\n\n用文件 ID 或图片 URL 作为输入提交任务。响应会返回一个 task_id，用于追踪并取回结果。\n\n\n**6. 取回任务结果**\n\n```\nGET /s2s/v2.0/task/fitzpatrick-scale-analyzer/{task_id}\n```\n\n用任务 ID 追踪状态并取得结果。\n\n可配置 [Webhooks](/develop/webhook.md)，在任务完成（状态为 success 或 error）时接收异步通知。也支持轮询：反复调用任务接口，直到状态从 running 变为 success 或 error。\n\n只有任务成功完成才计费。\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI Fitzpatrick 皮肤类型分析 | 长边不超过 4096 像素，短边不小于 320 像素。 | < 10MB | jpg/jpeg |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_below_min_image_size | 原图尺寸不得低于 320 像素。 |\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI Fitzpatrick 皮肤类型分析 V1.0 | 10 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_abs_filter.yaml","link":"/zh-cn/reference/ai_abs_filter","routeSlug":"/zh-cn/reference/ai_abs_filter","label":"AI 腹肌滤镜","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_abs_filter/section/概览","routeSlug":"/zh-cn/reference/ai_abs_filter/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_abs_filter/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_abs_filter/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_abs_filter/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_abs_filter/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_abs_filter/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_abs_filter/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_abs_filter/v1.0","routeSlug":"/zh-cn/reference/ai_abs_filter/v1.0","items":[{"label":"执行 AI 腹肌滤镜 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","routeSlug":"/zh-cn/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape/post","metadata":{"seo":{"title":"执行 AI 腹肌滤镜 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/abs-shape"},{"label":"查询 AI 腹肌滤镜 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_abs_filter/v1.0/paths/~1s2s~1v2.0~1task~1abs-shape~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 腹肌滤镜 任务的状态。","description":"查询 AI 腹肌滤镜 任务的状态。"}},"httpPath":"/s2s/v2.0/task/abs-shape/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 腹肌滤镜","version":"","description":"# 概览\n\nAI 腹肌滤镜接口（**AI Abs Filter API**）让您在照片里加上逼真的腹部线条，几乎不费力气就做出运动感的塑形效果。上传全身照或上半身照，选好增强模式、设定强度，就能拿到编辑好的输出图片。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-09-27/daf70f5e-a350-46a3-8b6c-f63bd60c6cf0.jpg)\n\n支持的模式：\n\n- `Six-pack`：加上清晰可见的六块腹肌，躯干看起来更结实有力。\n- `Vest-line`：强化腹部中间的肌肉线条，做出精壮的运动感。\n\n---\n\n## 接入指南\n\n**输入要求与处理条件：**\n\n- 上传全身照或上半身照。\n- 选择增强模式：`Six-pack` 或 `Vest-line`。\n- 设定您想要的腹部增强强度档位。\n- 图片长边分辨率不得超过 **4096 px**。\n- 源文件大小须小于 **10 MB**。\n- 至少需要一位可检测的人物，且两侧肩膀可见。\n- 腹部必须可见，穿衣、不穿衣都可以。\n- 支持的姿态范围：`−45° < yaw < 45°`。\n- 支持单人处理。画面中有多人时，接口会自动选取肩部可见面积最大的那位。\n\n**流程：**\n\n1. 用 File 接口上传文件元数据。\n2. 从响应中取得签名的上传 URL。\n3. 把实际图片上传到该 URL。\n4. 创建腹肌增强的 AI 任务。\n5. 配置 Webhook，或轮询任务状态直到完成。\n6. 处理成功后下载生成的结果图片。\n\n---\n\n**第 1 步 — 用 File 接口上传文件元数据**\n\n用 `POST /s2s/v2.0/file` 建立文件记录，取得源图的上传信息。\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\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n**File 接口响应示例：**\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**第 2 步 — 取得 File 接口响应内容**\n\n响应包含：\n\n| 字段 | 说明 |\n| --- | --- |\n| `file_id` | 用于创建 AI 任务的标识。 |\n| `requests.url` | 上传实际图片文件的签名 URL。 |\n| `requests.method` | 上传方式，通常为 `PUT`。 |\n| `requests.headers` | 上传请求所需的请求头。 |\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 步 — 创建 AI 任务**\n\n用 `POST /s2s/v2.0/task/abs-shape` 创建腹部增强任务。\n\n| 参数 | 说明 | 示例 |\n| --- | --- | --- |\n| `src_file_id` | File 接口上传流程返回的文件 ID。走上传文件流程时必填。 | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | 源图的直接 URL。可作为 `src_file_id` 的替代方案。 | `\"https://example.com/selfie.jpg\"` |\n| `mode` | 增强模式。支持的取值为 `Six-pack` 与 `Vest-line`。 | `\"Six-pack\"` |\n| `intensity` | 腹部增强强度档位。 | `1` |\n\n**请求示例：**\n\n```javascript\nconst resp = await fetch(\n  'https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: 'Bearer <YOUR_TOKEN_HERE>'\n    },\n    body: JSON.stringify({\n      src_file_url: 'https://example.com/selfie.jpg',\n      mode: 'Six-pack',\n      intensity: 1\n    })\n  }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI 任务接口响应：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n---\n\n**第 5 步 — 配置 Webhook 或轮询任务结果**\n\n配置与验证细节见 [Webhook 接入指南](/develop/webhook.md)。\n\n若走轮询，请用返回的 `task_id` 查看任务状态。\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/abs-shape/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n**第 6 步 — 取回结果图片**\n\n处理成功时，响应会在 `data.results.url` 中给出下载 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\n**API 密钥无效的响应：**\n\n访问令牌无效时，接口返回 `401` 响应。\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n应用场景：\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/307f87b4-d31c-481c-86f1-478c93265a95.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-08-21/8ab8eca4-b825-4692-aef0-6ffd6176e272.jpg)\n\n---\n\n## 文件规格与错误码\n\n**文件规格：**\n\n| 规格项 | 要求 |\n| --- | --- |\n| 图片类型 | 全身照或上半身照。 |\n| 源图人物 | 一位可检测的人物，两侧肩膀可见、腹部可见。 |\n| 姿态要求 | 支持的姿态范围为 `−45° < yaw < 45°`。 |\n| 多人处理 | 检测到多人时，接口会自动选取肩部可见面积最大的那位。 |\n| 长边分辨率上限 | 长边不得超过 **4096 px**。 |\n| 文件大小上限 | 须小于 **10 MB**。 |\n| 支持格式 | `jpg`、`png`。 |\n\n**错误码：**\n\n| 错误码 | 说明 |\n| --- | --- |\n| `exceed_max_filesize` | 源图超出允许的尺寸或文件大小上限。长边不得超过 4096 px，文件大小须保持在 10 MB 以下。 |\n| `error_pose` | 姿态检测失败：可能是未检测到人、肩部可见度问题、腹部可见度问题、腰部区域检测失败、髋部关键点检测失败，或姿态范围不受支持。 |\n| `error_nsfw_content_detected` | 在源图或生成的结果图中检测到疑似不适宜内容（NSFW）。 |\n| `invalid_parameter` | 源键、目标键、动作、模式取值、强度档位或任务配置中提供了无效参数。 |\n| `error_download_image` | 源图片下载失败。 |\n| `error_decode_image` | 源图片解码失败。 |\n\n**运行环境与依赖：**\n\n| 工具 / 语言 | 建议运行时版本 |\n| --- | --- |\n| cURL | Bash ≥ 3.2；curl ≥ 7.58（支持现代 TLS/HTTP）；jq ≥ 1.6（稳健的 JSON 解析）。 |\n| Node.js | Node ≥ 18，以支持全局 `fetch`。 |\n| JavaScript 浏览器支持 | Chrome / Edge ≥ 80、Firefox ≥ 74、Safari ≥ 13.1。 |\n| PHP | PHP ≥ 7.4（兼容现代 TLS）；建议 ext-curl，或 `allow_url_fopen=On` 并具备 OpenSSL 与 JSON 支持。 |\n| Python | Python ≥ 3.10（支持 f-string）；requests ≥ 2.20.0。 |\n| Java | Java 11+（HttpClient）；Jackson Databind ≥ 2.12.0。 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 腹肌滤镜 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"美妆","labelTranslationKey":"sidebar.reference.separators.beauty"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_makeup_transfer.yaml","link":"/zh-cn/reference/ai_makeup_transfer","routeSlug":"/zh-cn/reference/ai_makeup_transfer","label":"AI 仿妆迁移","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_makeup_transfer/section/概览","routeSlug":"/zh-cn/reference/ai_makeup_transfer/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_makeup_transfer/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_makeup_transfer/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_makeup_transfer/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_makeup_transfer/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_makeup_transfer/v1.0","routeSlug":"/zh-cn/reference/ai_makeup_transfer/v1.0","items":[{"label":"执行 AI 仿妆迁移 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","routeSlug":"/zh-cn/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer/post","metadata":{"seo":{"title":"执行 AI 仿妆迁移 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/mu-transfer"},{"label":"查询 AI 仿妆迁移 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_makeup_transfer/v1.0/paths/~1s2s~1v2.0~1task~1mu-transfer~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 仿妆迁移 任务的状态。","description":"查询 AI 仿妆迁移 任务的状态。"}},"httpPath":"/s2s/v2.0/task/mu-transfer/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 仿妆迁移","version":"","description":"# 概览\n看到喜欢的造型，直接上传就行！AI 仿妆迁移让您轻松好玩地尝试各种造型：上传您中意的照片，一张张换着试。有想试的妆容？让 AI 仿妆迁移给您一个惊喜！\n\n首先，上传一张您本人的照片作为目标图，要求脸部与五官清楚可见。\n\n然后，上传一张您喜欢的妆容照片作为参考图。 \n\n就这么简单——一张 AI 仿妆迁移好的照片就有了。 \n\n示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Makeup_Transfer_s1_img_be53c5c345.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-06-24/fda62e5d-ba58-4ecf-838a-c7d5f804c77b.jpg)\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 仿妆迁移|1024x1024（长边 <= 1024），仅支持单人脸，需露出完整脸部|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_src_no_face\t|用户图中未检测到人脸\n|error_ref_no_face\t|参考图中未检测到人脸\n|error_src_face_too_small\t|用户图中的人脸过小\n|error_ref_face_too_small\t|参考图中的人脸过小\n|error_src_large_face_angle\t|用户图需为正脸\n|error_ref_large_face_angle\t|参考图需为正脸\n|error_src_eye_closed\t|用户图中有眼睛闭合\n|error_ref_eye_closed\t|参考图中有眼睛闭合\n|error_src_eye_occluded\t|用户图中眼睛被遮挡\n|error_ref_eye_occluded\t|参考图中眼睛被遮挡\n|error_src_lip_occluded\t|用户图中嘴唇被遮挡\n|error_ref_lip_occluded\t|参考图中嘴唇被遮挡\n|error_inappropriate_ref_case01\t|参考图中双眼周围头发过于贴近眼部，或眼尾旁侧的皮肤区域不够大\n|error_inappropriate_ref_case02\t|参考图中一只眼周围头发过于贴近眼部、或眼尾旁侧的皮肤区域不够大，另一只眼的朝向不够正\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 仿妆迁移 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/makeup_vto.yaml","link":"/zh-cn/reference/makeup_vto","routeSlug":"/zh-cn/reference/makeup_vto","label":"AI 美妆虚拟试妆","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/makeup_vto/section/概览","routeSlug":"/zh-cn/reference/makeup_vto/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/makeup_vto/section/概览/接入指南","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/makeup_vto/section/概览/输入与输出","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/输入与输出"},{"type":"link","label":"请求示例","link":"/zh-cn/reference/makeup_vto/section/概览/请求示例","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/请求示例"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/makeup_vto/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/makeup_vto/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/makeup_vto/section/概览/点数消耗","routeSlug":"/zh-cn/reference/makeup_vto/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/makeup_vto/v1.0","routeSlug":"/zh-cn/reference/makeup_vto/v1.0","items":[{"label":"执行 AI 美妆虚拟试妆 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","routeSlug":"/zh-cn/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto/post","metadata":{"seo":{"title":"执行 AI 美妆虚拟试妆 任务。","description":"本接口用于发起 AI 美妆虚拟试妆流程。您需要提供源文件（URL 或文件 ID），并按既定特效结构指定要应用的特效。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/makeup-vto"},{"label":"查询 AI 美妆虚拟试妆 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","routeSlug":"/zh-cn/reference/makeup_vto/v1.0/paths/~1s2s~1v2.0~1task~1makeup-vto~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 美妆虚拟试妆 任务的状态。","description":"查询 AI 美妆虚拟试妆 任务的状态。"}},"httpPath":"/s2s/v2.0/task/makeup-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 美妆虚拟试妆","version":"","description":"# 概览\nAI 妆效接口提供一套强大、逼真到位的虚拟化妆体验，背后是我们取得专利的脸部分析技术。这项服务能让您的应用把真实感十足的妆效套到用户提供的自拍照上，自定义程度前所未有。\n\n**主要特性：**\n*   **逼真到位的渲染：** 采用突破性的 3D 脸部 AI 技术，做出最真实的妆容变化。\n*   **专利技术：** 由不抖动、不卡顿的深度学习算法驱动，各种年龄、各种肤色都调优到位。\n*   **即时精准：** 超精准的脸部追踪，各种光线条件下都跟得上。\n*   **还原真实：** 准确还原现实商品的色彩、质地（从哑光到金属感）与妆效呈现。\n\n* 核心概念\n\n   * 色彩混合\n我们的 AI 用深度学习准确匹配现实彩妆商品的颜色。消费者看到的虚拟颜色就是他们打算购买的商品的真实颜色，这一点可以放心。\n\n   * 质地与妆效还原\n这项技术能模拟真实的质地与妆效，带来准确度极高的上妆体验。从哑光到金属感、从珠光到缎光，AI 依靠先进算法即时把这些效果流畅渲染出来。\n\n   * 光线平衡\n智能 3D AI 引擎会检测用户照片或视频画面中的光线条件，并对图像做校正，让上妆效果贴近真实；不论什么环境，结果都稳定、高质量。\n\n---\n\n## 接入指南\n\nAI 美妆虚拟试妆服务以异步任务的方式运行。您要先提供图片 URL 与要套用的特效清单，发起妆效处理任务；服务器会响应一个 `task_id`。之后定期轮询状态接口，取回最终结果或错误信息。\n\n*   **接口地址：** `/v2.0/task/makeup-vto`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer <TOKEN>`\n*   **流程：**\n    1.  **准备自拍照：** 上传一张脸部图片，或使用已有的文件 URL。\n    1.  **发起任务（`POST`）：** 提交您的图片 id/URL 与妆效配置。\n    1.  **取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n    ```\n    Authorization: Bearer <API Key>\n    ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n* 1. 上传自拍照\n  源图有两种提供方式：\n\n  - **使用已有的公开图片 URL**\n    不必上传，发起 AI 任务时直接提供一个可公开访问的图片 URL 也可以。\n\n  - **通过 File 接口上传**\n    接口地址：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    这会返回一个 `file_id`，供后续执行任务时使用。\n\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br></br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n\n* 2. 发起妆效任务\n\n`POST /s2s/v2.0/task/makeup-vto`\n\n在指定图片上发起一次新的虚拟上妆任务。该接口为异步接口，响应会返回一个 `task_id`。\n\n   * 请求头\n\n| 请求头 | 取值 |\n|--------|-------|\n| Content-Type | `application/json` |\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 请求体示例\n```json\n{\n  \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg\",\n  \"effects\": [\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors6\" },\n      \"palettes\": [\n        { \"color\": \"#FF0000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#F2A53E\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    },\n    {\n      \"category\": \"eye_liner\",\n      \"pattern\": { \"name\": \"3colors5\" },\n      \"palettes\": [\n        { \"color\": \"#000000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#BA0656\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n        { \"color\": \"#089085\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n      ]\n    }\n  ],\n  \"version\": \"1.0\"\n}\n```\n\n   * 请求体 Schema\n\n| 字段 | 类型 | 说明 |\n|-------|------|---------|\n| `src_file_url` | 字符串（URL） | 待处理自拍图片的可公开访问 URL。 |\n| `effects` | Effect 数组 | 要套用的妆效对象数组。详见 [妆效 Schema](#makeup-effect-schemas)。 |\n| `version` | 字符串 | 特效参数的接口版本，使用 `\"1.0\"`。 |\n\n   * 成功响应（`200 OK`）\n返回一个包含任务标识的 JSON 对象。\n\n**响应体 Schema：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"<string>\"\n  }\n}\n```\n\n**响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe\"\n  }\n}\n```\n\n   * 错误响应（`400 Bad Request`、`401 InvalidApiKey` 等）\n返回标准错误对象，并以 message 说明失败原因。\n\n**错误响应示例：**\n```json\n{\n  \"status\": 400,\n  \"error\": \"The operation could not be completed\",\n  \"error_code\": \"CreditInsufficiency\"\n}\n```\n\n---\n\n* 3. 取得任务状态与结果\n\n`GET /s2s/v2.0/task/makeup-vto/<task_id>`\n\n取得进行中或已完成任务的当前状态与结果。\n\n   * 请求头\n\n| 请求头 | 取值 |\n|--------|-------|\n| Authorization | `Bearer YOUR_API_KEY` |\n\n   * 路径参数\n\n| 参数 | 类型 | 说明 |\n|-----------|------|---------|\n| task_id | 字符串 | 发起任务接口返回的标识。 |\n\n   * 成功响应（`200 OK`）\n返回一个 JSON 对象，包含任务状态；若已完成，还包含结果。\n\n**响应体 Schema：**\n```json\n{\n  \"data\": {\n    \"task_status\": \"<string>\", // 'success', 'error', or a processing state (e.g., 'queued', 'processing')\n    \"results\": [ // present only when task_status is 'success'\n      {\n        \"download_url\": \"<string>\" // URL to download the processed image\n      }\n    ],\n    \"failure_reason\": \"<string>\" // present only when task_status is 'error'\n  }\n}\n```\n\n**成功响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"success\",\n    \"results\": {\n      \"url\": \"https://s3.storage.prod/processed/image_123.jpg?token=...\"\n    }\n  }\n}\n```\n\n**引擎错误响应示例：**\n接口查询已成功送达，但在执行 AI 任务的过程中发生错误。\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"error\",\n    \"error\": \"exceed_max_filesize\",\n    \"error_message\": \"string\",\n  }\n}\n```\n  > 请注意，无论查询错误还是引擎错误，只要发生错误就不消耗点数。\n\n**进行中响应示例：**\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_status\": \"running\"\n  }\n}\n```\n\n   * 错误响应\n*   `404 InvalidTaskId`：`task_id` 不存在或无效。\n*   `401 InvalidApiKey`：API 密钥无效或缺失。\n*   `500 TaskTimeout`：任务已成功完成或已失败，且超过保留期。\n\n**查询错误响应示例：**\n```json\n{\n  \"status\": 401,\n  \"error_code\": \"InvalidApiKey\"\n}\n```\n  > 请注意，无论查询错误还是引擎错误，只要发生错误就不消耗点数。\n\n---\n\n## 输入与输出\n* 妆效 Schema\n\n本节定义 AI 妆效任务请求体的完整结构与限制。每个特效都是顶层 `effects` 数组中的一个对象。\n\n* 特效容器（顶层）\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": []                    // array<Effect> — Contains makeup effect objects\n}\n```\n\n* 妆效类别\n\n   * `skin_smooth`\n```json\n{\n  \"category\": \"skin_smooth\",           // string, const \"skin_smooth\"\n  \"skinSmoothStrength\": 50,            // integer, range: 0..100\n  \"skinSmoothColorIntensity\": 50       // integer, range: 0..100\n}\n```\n  > **注意！** 请求中若未包含 ``skin_smooth`` 特效，AI 妆效引擎会自动套用默认的美肤强度 50。\n  希望只上妆、不做磨皮时，把所有 ``skinSmoothStrength`` 与 ``skinSmoothColorIntensity`` 参数设为 0。不过为了最佳效果与最高质量的混合，建议保留默认的美肤设置。\n\n   * `blush`\n```json\n{\n  \"category\": \"blush\",                 // string, const \"blush\"\n  \"pattern\": {                         // object\n    \"name\": \"\"                         // string — MUST equal a `label` from blush.json\n  },\n  \"palettes\": [                        // array<BlushPalette>, minItems: (see colorNum in pattern)\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\",\"shimmer\"]\n      \"glowStrength\": 50,              // integer, range: 0..100 — REQUIRED if texture=\"satin\"\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/blush.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 103, \"name\": \"Oblong\" }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg\",\n    \"tags\": [\n      { \"id\": 100, \"name\": \"Blush 3D\" },\n      { \"id\": 104, \"name\": \"Round\" }\n    ],\n    \"colorNum\": 3\n  }\n]\n```\n\n\n   * `bronzer`\n```json\n{\n  \"category\": \"bronzer\",               // string, const \"bronzer\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a `label` from bronzer.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Bronzer\",\n    \"label\": \"Bronzer1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg\",\n    \"tags\": [],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `concealer`\n```json\n{\n  \"category\": \"concealer\",             // string, const \"concealer\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"colorUnderEyeIntensity\": 50,    // integer, range: 0..100\n      \"coverageLevel\": 50              // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `contour`\n```json\n{\n  \"category\": \"contour\",               // string, const \"contour\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a `label` from contour.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/contour.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace6\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eyebrows`\n```json\n{\n  \"category\": \"eyebrows\",              // string, const \"eyebrows\"\n  \"pattern\": {\n    \"type\": \"shape\",                   // string, enum [\"shape\",\"color\"], default: \"shape\"\n    \"name\": \"\",                        // string, required when type=\"shape\" — label from eyebrows.json\n    \"curvature\": 0,                    // integer, range: -100..100 (shape only)\n    \"thickness\": 0,                    // integer, range: -100..100 (shape only)\n    \"definition\": 0                    // integer, range: 0..100 (shape only)\n  },\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n      \"shimmerDensity\": 50             // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Arrow\",\n    \"label\": \"Arrow1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Curved\",\n    \"label\": \"Curved1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Drama\",\n    \"label\": \"Drama2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"High Arch\",\n    \"label\": \"HighArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Original\",\n    \"label\": \"Original2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Soft Arch\",\n    \"label\": \"SoftArch1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Straight\",\n    \"label\": \"Straight1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Thin\",\n    \"label\": \"Thin1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upward\",\n    \"label\": \"Upward4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `eye_liner`\n```json\n{\n  \"category\": \"eye_liner\",             // string, const \"eye_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyeliner.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg\",\n    \"tags\": [\n      {\n        \"id\": 28,\n        \"name\": \"Drama\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"1 color\",\n    \"label\": \"Arabic3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg\",\n    \"tags\": [\n      {\n        \"id\": 26,\n        \"name\": \"Arabic\"\n      }\n    ],\n    \"colorNum\": 1\n  }\n]\n```\n\n   * `eye_shadow`\n```json\n{\n  \"category\": \"eye_shadow\",            // string, const \"eye_shadow\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyeshadow.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n      \"shimmerColor\": \"#fc288f\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n      \"metallicIntensity\": 50,         // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]                                    // minItems: (see colorNum in pattern)\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"1 color\",\n    \"label\": \"1color1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg\",\n    \"tags\": [\n      {\n        \"id\": 12,\n        \"name\": \"Artistic\"\n      },\n      {\n        \"id\": 14,\n        \"name\": \"Dream\"\n      },\n      {\n        \"id\": 15,\n        \"name\": \"Trend\"\n      }\n    ],\n    \"colorNum\": 1\n  },\n  {\n    \"category\": \"2 colors\",\n    \"label\": \"2colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 2\n  },\n  {\n    \"category\": \"3 colors\",\n    \"label\": \"3colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg\",\n    \"tags\": [\n      {\n        \"id\": 1,\n        \"name\": \"Fan shape\"\n      },\n      {\n        \"id\": 8,\n        \"name\": \"Only upper lid\"\n      }\n    ],\n    \"colorNum\": 3\n  },\n  {\n    \"category\": \"4 colors\",\n    \"label\": \"4colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 4\n  },\n  {\n    \"category\": \"5 colors\",\n    \"label\": \"5colors1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg\",\n    \"tags\": [\n      {\n        \"id\": 4,\n        \"name\": \"Closed banana\"\n      },\n      {\n        \"id\": 10,\n        \"name\": \"Whole eye\"\n      }\n    ],\n    \"colorNum\": 5\n  }\n]\n```\n\n   * `eyelashes`\n```json\n{\n  \"category\": \"eyelashes\",             // string, const \"eyelashes\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from eyelashes.json\n  \"palettes\": [\n    { \"color\": \"#ff0000\", \"colorIntensity\": 50 }  // hex color, int range: 0..100\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Artistic\",\n    \"label\": \"Artistic1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper&Lower\",\n    \"label\": \"Upper&Lower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Upper\",\n    \"label\": \"Upper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"UpperDense\",\n    \"label\": \"UpperDense1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Winged\",\n    \"label\": \"Winged1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wispies\",\n    \"label\": \"Wispies1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png\",\n    \"tags\": []\n  }\n]\n```\n\n   * `foundation`\n```json\n{\n  \"category\": \"foundation\",            // string, const \"foundation\"\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"coverageIntensity\": 50          // integer, range: 0..100\n    }\n  ]\n}\n```\n\n   * `highlighter`\n```json\n{\n  \"category\": \"highlighter\",           // string, const \"highlighter\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from highlighter.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"glowIntensity\": 50,             // integer, range: 0..100\n      \"shimmerIntensity\": 50,          // integer, range: 0..100\n      \"shimmerDensity\": 50,            // integer, range: 0..100\n      \"shimmerSize\": 50,               // integer, range: 0..100\n      \"colorIntensity\": 50             // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Heart face\",\n    \"label\": \"HeartFace4\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Invtriangle\",\n    \"label\": \"Invtriangle2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oblong\",\n    \"label\": \"Oblong11\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Oval face\",\n    \"label\": \"OvalFace2\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Round face\",\n    \"label\": \"RoundFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Square face\",\n    \"label\": \"SquareFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Triangle face\",\n    \"label\": \"TriangleFace3\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n   * `lip_color`\n```json\n{\n  \"category\": \"lip_color\",             // string, const \"lip_color\"\n  \"shape\": {                           // object — driven by lipshape.json\n    \"name\": \"original\"                 // string — MUST equal a `label` from lipshape.json\n  },\n  \"morphology\": {                      // optional object\n    \"fullness\": 50,                    // integer, range: 0..100 (default: 0)\n    \"wrinkless\": 50                    // integer, range: 0..100 (default: 0)\n  },\n  \"palettes\": [                        // minItems depends on style; often ≥1\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"gloss\",\"holographic\",\"metallic\",\"satin\",\"sheer\",\"shimmer\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"gloss\": 50,                     // int, range: 0..100 — REQUIRED if texture in [\"gloss\",\"holographic\",\"metallic\",\"sheer\",\"shimmer\"]\n      \"shimmerColor\": \"#ff0000\",       // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerIntensity\": 50,          // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerDensity\": 50,            // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"shimmerSize\": 50,               // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n      \"transparencyIntensity\": 50      // integer, range: 0..100 — REQUIRED if texture in [\"gloss\",\"sheer\",\"shimmer\"]\n    }\n  ],\n  \"style\": {\n    \"type\": \"full\",                    // string, enum [\"full\",\"ombre\",\"twoTone\"]\n    \"innerRatio\": 50,                  // int, range: 0..100 — REQUIRED if type=\"ombre\"\n    \"featherStrength\": 50              // int, range: 0..100 — REQUIRED if type=\"ombre\"\n  }\n}\n```\n\n**完整形状清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json\n\n**彩妆图案类别一览：**\n```json\n[{\n        \"category\": \"general\",\n        \"label\": \"original\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"heart-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"m-shaped\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"petal\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"plump\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"pouty\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"smile\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg\",\n        \"tags\": [\n        ]\n    }, {\n        \"category\": \"general\",\n        \"label\": \"vintage\",\n        \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg\",\n        \"tags\": [\n        ]\n    }\n]\n```\n\n   * `lip_liner`\n```json\n{\n  \"category\": \"lip_liner\",             // string, const \"lip_liner\"\n  \"pattern\": { \"name\": \"\" },           // object — name MUST equal a label from lipliner.json\n  \"palettes\": [\n    {\n      \"color\": \"#ff0000\",              // string, hex color \"#RRGGBB\"\n      \"texture\": \"matte\",              // string, enum [\"matte\",\"satin\"]\n      \"colorIntensity\": 50,            // integer, range: 0..100\n      \"thickness\": 50,                 // integer, range: 0..100\n      \"smoothness\": 50                 // integer, range: 0..100\n    }\n  ]\n}\n```\n\n**完整图案清单：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json\n\n**彩妆图案类别一览：**\n```json\n[\n  {\n    \"category\": \"Large & Full\",\n    \"label\": \"Large&Full1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Lower\",\n    \"label\": \"LargerLower1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Larger Upper\",\n    \"label\": \"LargerUpper1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Natural\",\n    \"label\": \"Natural1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Rosebud\",\n    \"label\": \"Rosebud1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Small\",\n    \"label\": \"Small1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg\",\n    \"tags\": []\n  },\n  {\n    \"category\": \"Wider\",\n    \"label\": \"Wider1\",\n    \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg\",\n    \"tags\": []\n  }\n]\n```\n\n---\n\n## 请求示例\n\n以下是一份完整、可用的 `effectJson` 参数，一次套用多项妆效。\n\n```json\n{\n  \"version\": \"1.0\",\n  \"effects\": [\n    {\n      \"category\": \"skin_smooth\",\n      \"skinSmoothStrength\": 55,\n      \"skinSmoothColorIntensity\": 45\n    },\n    {\n      \"category\": \"blush\",\n      \"pattern\": { \"name\": \"2colors1\" },\n      \"palettes\": [\n        {\n          \"color\": \"#e19f9f\",\n          \"texture\": \"matte\",\n          \"colorIntensity\": 60,\n          \"shimmerColor\": \"#d63252\",\n          \"shimmerDensity\": 50\n        },\n        {\n          \"color\": \"#c98a8a\",\n          \"texture\": \"satin\",\n          \"glowStrength\": 40,\n          \"colorIntensity\": 70\n        }\n      ]\n    },\n    {\n        \"category\": \"lip_color\",\n        \"shape\": { \"name\": \"plump\" },\n        \"morphology\": { \"fullness\": 30, \"wrinkless\": 25 },\n        \"style\": { \"type\": \"full\" },\n        \"palettes\": [\n            {\n                \"color\": \"#e11c43\",\n                \"texture\": \"gloss\",\n                \"colorIntensity\": 80,\n                \"gloss\": 75\n            }\n        ]\n    }\n  ]\n}\n```\n在这个示例中，`blush` 使用 `blush.json` 里的 `2colors1` 图案，该图案需要恰好两个色盘。`lip_color` 特效使用 `lipshape.json` 里的 `plump` 形状。\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 美妆虚拟试妆|长边 < 1920，脸部宽度 >= 100|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|源图尺寸小于下限（要求：宽 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|源图尺寸超过上限（要求：宽 < 1920px，高 < 1080px）\n|error_face_position_invalid |请确保整张脸在画面中完整可见|\n|error_face_position_too_small|检测到的人脸太小，请靠近相机|\n|error_face_position_out_of_boundary|人脸过大，或部分超出画面边界，请调整位置|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 美妆虚拟试妆 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_look_vto.yaml","link":"/zh-cn/reference/ai_look_vto","routeSlug":"/zh-cn/reference/ai_look_vto","label":"AI 妆容虚拟试妆","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_look_vto/section/概览","routeSlug":"/zh-cn/reference/ai_look_vto/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_look_vto/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_look_vto/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_look_vto/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_look_vto/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_look_vto/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_look_vto/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_look_vto/v1.0","routeSlug":"/zh-cn/reference/ai_look_vto/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","routeSlug":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/look-vto"},{"label":"执行 AI 妆容虚拟试妆 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","routeSlug":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post","metadata":{"seo":{"title":"执行 AI 妆容虚拟试妆 任务。","description":"本接口用模板与源图片发起 AI 妆容虚拟试妆流程。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/look-vto"},{"label":"查询 AI 妆容虚拟试妆 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 妆容虚拟试妆 任务的状态。","description":"查询 AI 妆容虚拟试妆 任务的状态。"}},"httpPath":"/s2s/v2.0/task/look-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 妆容虚拟试妆","version":"","description":"# 概览\nAI 造型虚拟试穿接口提供一套完整流程，把美妆专家设计的整组脸部造型套到用户照片上。每套造型都由美妆专家打造，通过接口即可即时套用。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/look-vto`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer <TOKEN>`\n*   **流程：**\n    1.  **准备自拍照：** 上传图片，或提供一个有效的图片 URL\n    1.  **列出造型模板：** 取得可用的 AI 造型模板清单\n    1.  **发起任务（`POST`）：** 提交您的图片 id/URL 与造型 ``template_id``。\n    1.  **取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n    ```\n    Authorization: Bearer <API Key>\n    ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 2. 列出可用造型风格\n\n取得所有可用于虚拟试穿的 AI 妆效造型模板。\n\n   * 接口地址\n\n```\nGET /s2s/v2.0/task/template/look-vto\n```\n\n   * 查询参数\n\n| 参数        | 说明                     |\n| ---------------- | ------------------------------- |\n| `page_size`      | 每页笔数        |\n| `starting_token` | 分页用的 token（选填） |\n\n   * JavaScript 请求示例\n\n```javascript\nconst data = null;\n\nconst xhr = new XMLHttpRequest();\nxhr.withCredentials = true;\n\nxhr.addEventListener('readystatechange', function () {\n    if (this.readyState === this.DONE) {\n        console.log(this.responseText);\n    }\n});\n\nxhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');\nxhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');\n\nxhr.send(data);\n```\n\n   * 成功响应示例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"templates\": [\n      {\n        \"id\": \"good_template_001\",\n        \"thumb\": \"thumbnail preview image URL\",\n        \"title\": \"Berry Smooth\",\n        \"category_name\": \"Daily\"\n      }\n    ],\n    \"next_token\": 73a3c9e69b89\n  }\n}\n```\n\n> **说明：** 创建造型 VTO 任务时，请使用 `id` 的值（即 `template_id`）。\n\n---\n\n* 3. 创建造型 VTO 任务并轮询结果\n\n图片和模板 ID 都备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/look-vto\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/look-vto/{task_id}\n```\n\n---\n\n   * JavaScript 实现示例\n\n```javascript\nconst BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';\nconst START_METHOD = 'POST';\nconst HEADERS = {\n  \"Content-Type\": \"application/json\",\n  \"Authorization\": \"Bearer YOUR_API_KEY\"\n};\n\nconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nasync function startTask() {\n  const init = {\n    method: START_METHOD,\n    headers: HEADERS,\n    body: JSON.stringify({\n      \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg\",\n      \"template_id\": \"all_rosy_chic\"\n    })\n  };\n\n  const res = await fetch(BASE_URL, init);\n  if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);\n\n  const payload = await res.json().catch(() => ({}));\n  const taskId = payload?.data?.task_id;\n  if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));\n\n  console.log('[startTask] Task started, id =', taskId);\n  return taskId;\n}\n\nasync function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    const pollUrl = `${BASE_URL}/${taskId}`;\n    const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });\n\n    if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);\n\n    const payload = await res.json().catch(() => ({}));\n    const status = payload?.data?.task_status;\n    console.log(`[pollTask] Attempt ${attempt} status = ${status}`);\n\n    if (status === 'success') {\n      console.log('[pollTask] Success results:', payload?.data?.results);\n      return payload;\n    }\n\n    if (status === 'error') {\n      throw new Error('Task failed: ' + JSON.stringify(payload));\n    }\n\n    await sleep(intervalMs);\n  }\n\n  throw new Error('Polling timeout: Max attempts exceeded');\n}\n\n(async () => {\n  try {\n    const taskId = await startTask();\n    const final = await pollTask(taskId);\n    console.log('[main] Final response:', final);\n  } catch (e) {\n    console.error('[main] Flow error:', e);\n  }\n})();\n```\n\n---\n\n   * 成功响应示例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n`results.url` 字段就是最终渲染完成的虚拟妆效图片。\n\n---\n\n* 流程小结\n\n| 步骤                       | 说明                              |\n| -------------------------- | ---------------------------------------- |\n| **1. 上传图片**        | 直接上传，或提供图片 URL。 |\n| **2. 列出造型模板** | 取得可用造型风格及其 ID。 |\n| **3. 创建 VTO 任务**     | 提交图片 URL + 模板 ID。          |\n| **4. 轮询至完成** | 取回最终结果图片的 URL。     |\n\n这套流程稳定可靠、对开发者友好，可支撑即时上线的虚拟妆效试穿体验。\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 造型虚拟试穿|长边 < 1920，脸部宽度 >= 100|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|源图尺寸小于下限（要求：宽 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|源图尺寸超过上限（要求：宽 < 1920px，高 < 1080px）\n|error_face_position_invalid |请确保整张脸在画面中完整可见|\n|error_face_position_too_small|检测到的人脸太小，请靠近相机|\n|error_face_position_out_of_boundary|人脸过大，或部分超出画面边界，请调整位置|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 造型虚拟试穿 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_nail_transfer.yaml","link":"/zh-cn/reference/ai_nail_transfer","routeSlug":"/zh-cn/reference/ai_nail_transfer","label":"AI Nail Transfer","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_nail_transfer/section/概览","routeSlug":"/zh-cn/reference/ai_nail_transfer/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_nail_transfer/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_nail_transfer/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_nail_transfer/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_nail_transfer/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_nail_transfer/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_nail_transfer/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_nail_transfer/v1.0","routeSlug":"/zh-cn/reference/ai_nail_transfer/v1.0","items":[{"label":"执行 AI Nail Transfer 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail/post","routeSlug":"/zh-cn/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail/post","metadata":{"seo":{"title":"执行 AI Nail Transfer 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/ai-nail"},{"label":"查询 AI Nail Transfer 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail~1{task_id}/get","metadata":{"seo":{"title":"查询 AI Nail Transfer 任务的状态。","description":"查询 AI Nail Transfer 任务的状态。"}},"httpPath":"/s2s/v2.0/task/ai-nail/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Nail Transfer","version":"","description":"# 概览\nAI Nail Transfer接口是一套强大的生成式 AI 方案，专做虚拟试甲。依托 YouCam API 的先进 AI 模型与图像变换技术，用户可以把参考图上的任意美甲样式，逼真、精准地迁移到自己的手上。\n\n从甲油胶、美甲彩绘、纯色甲面，到亮片、贝壳装饰、金属质感等繁复点缀，AI 都能把各式美甲风格以自然的高清虚拟预览还原出来。消费者下单前先试先看，心里有数。\n\n对美妆品牌、美容院和美甲师来说，AI Nail Transfer接口是展示美甲作品的快招：客人看得过瘾、参与感强，满意度更高，沉浸式的虚拟体验还能把成交率拉上去。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI Nail Transfer接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/ai-nail`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n- 先用 File 接口把手部图片准备好，接口为 `/s2s/v2.0/file`。\n\n2. **上传参考图：**\n- 用 File 接口（`/s2s/v2.0/file`）上传一张带有您心仪美甲样式的参考图。想要效果最好，请确保十根手指的指甲都清楚可见。\n\n1. **发起 AI 任务并取得 Task ID：**\n- 用 HTTP POST 请求把上传好的图片送到 `/s2s/v2.0/task/ai-nail`。\n- 响应会返回一个唯一的 `task_id`，用于标识本次调用。\n\n1. **轮询任务状态（持续检查）：**\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```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n* 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 2. 上传参考图\n\n您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。请确保十根手指的指甲都清楚可见，虚拟试戴效果才最准。\n\n* 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n---\n\n* 3. 创建 AI Nail Transfer任务并轮询结果\n\n图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n* 创建任务接口\n\n```\nPOST /s2s/v2.0/task/ai-nail\n```\n\n* 轮询接口\n\n```\nGET /s2s/v2.0/task/ai-nail/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI Nail Transfer规格\n\n    **支持的手部图视角**\n\n    单张图片最多支持两只手，多出的手会被忽略。为了达到最佳检测效果，每只手至少占图片面积的 0.5%（FHD 约 102×102 px，2K 约 139×139 px，4K 约 204×204 px）。\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png)\n\n\n    **支持的参考图**\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png)\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n| AI Nail Transfer | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---- | ---- |\n| exceed_max_filesize | 图片文件过大 |\n| invalid_parameter | 输入参数缺失或格式有误 |\n| error_download_image | 文件未上传完成，或图片 URL 无效 |\n| error_inference | 推理失败，请检查输入图与参考图是否在支持范围内 |\n| no_hand_detected | 源图中未检测到手 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58 (modern TLS/HTTP support)</br>- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- Safarin b\\ |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn b\\_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| AI 功能 | 消耗点数 |\n|---|---|\n| AI Nail Transfer V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_nail_vto.yaml","link":"/zh-cn/reference/ai_nail_vto","routeSlug":"/zh-cn/reference/ai_nail_vto","label":"AI 美甲虚拟试用","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_nail_vto/section/概览","routeSlug":"/zh-cn/reference/ai_nail_vto/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_nail_vto/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_nail_vto/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_nail_vto/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_nail_vto/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_nail_vto/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_nail_vto/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_nail_vto/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_nail_vto/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_nail_vto/v1.0","routeSlug":"/zh-cn/reference/ai_nail_vto/v1.0","items":[{"label":"执行 AI 美甲虚拟试用 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","routeSlug":"/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post","metadata":{"seo":{"title":"执行 AI 美甲虚拟试用 任务。","description":"本接口用于发起 AI 美甲虚拟试用流程。您需要提供源文件与参考图（URL 或文件 ID），以及具体的美甲特效配置。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/nail-vto"},{"label":"查询 AI 美甲虚拟试用 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 美甲虚拟试用 任务的状态。","description":"查询 AI 美甲虚拟试用 任务的状态。"}},"httpPath":"/s2s/v2.0/task/nail-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 美甲虚拟试用","version":"","description":"# 概览\nAI 美甲虚拟试用接口为关注美甲的顾客带来一种全新的线上体验。购物者可以在网上试看各种美甲风格，从假指甲、亚克力指甲，到穿戴甲与甲油胶设计都涵盖。颜色与纹理不设上限，真甲、假甲都能轻松尝试不同造型。平台支持个性化试戴，风格随您切换，调整前后的对比一目了然。这套顺畅的接入方式让商品更容易被发现，靠精准、互动的预览效果，让顾客买得更有信心。\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI 美甲虚拟试用接口的流程：\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n    - 第一步是准备一张手背照片。\n    - 调用 File 接口 `/s2s/v2.0/file` 取得上传 URL 与对应的 `file_id`。\n    - 用提供的上传 URL 把带指甲的手背照片上传上去。\n\n2. **美甲样式设置方式：**\n    - 先选一个合适的指甲颜色，也可以按您的喜好自定义甲形。\n\n3. **发起 AI 任务并取得 Task ID：**\n    - 把上传好的图片连同选好的特效配置，通过 HTTP POST 请求送到 `/s2s/v2.0/task/nail-vto`。\n    - 响应会返回一个唯一的任务 ID，用于标识本次调用。\n\n4. **轮询任务状态（持续检查）：**\n    - 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}`）。\n    - 持续留意：\n        - `Task_status = \"success\"`（处理完成）。\n        - `Task_status = \"error\"`（视情况排查或重试）。\n    - 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/)\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\n1. 上传图片\n\n    您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n    * 上传接口\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n2. 准备特效模板\n\n    * 共有四种设置模式可选：\n        1. 自定义颜色，并与您现有的指甲造型对齐\n        2. 使用预设设计搭配指定甲形，做出您想要的效果\n        3. 加上穿戴甲，并与您原本指甲图片贴合\n        4. 提供相符穿戴甲商品的图片链接\n\n    * 特效模板 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"effect_type\": \"nail_polish\", // valid values: ['nail_polish', 'press_on_nails']\n            \"effects\": [],\n            \"ref_file_ids\": []\n        }\n        ```\n\n        * 特效格式\n            - 甲油胶 - 颜色\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100, for textures except metallic\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100, for texture pearl\n                \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n                \"textured_size\": 0, // 0-100, for texture textured\n            }\n            ```\n\n            - 甲油胶 - 设计\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n                \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100, only for textures except metallic\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100, for texture pearl\n                \"shimmer_size\": 0, // 0-100, for texture shimmer_coarse and shimmer_fine\n                \"textured_size\": 0, // 0-100, for texture textured\n            }\n\n            ```\n\n            - 穿戴甲 - 颜色\n            * 最新可用的甲形取值见：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"shape\": \"square_oval\", // Please check the nails.json. valid values: ['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval],\n                \"length\": 1.0, // 0.8-2.15, for shapes except original\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values for other shapes: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0 // 0-100\n            }\n            ```\n\n            - 穿戴甲 - 设计\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // Optional; Either ref_file_id or ref_file_url must be filled, but only one can be selected.\n                \"ref_file_index\": 0, // This field is optional unless uploading is selected. Index corresponding to ref_file_ids under the root node\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n            }\n\n            ```\n\n   * 特效模板的设计逻辑\n\n        1. **判断特效类型**（`press_on_nails` 与 `nail_polish`）。\n        2. **逐一处理 `effects` 中的每一项：**\n\n        *若 `sub_type === \"color\"`* → 直接映射各字段，缺失的纹理相关键用默认值补齐。\n        *若 `sub_type === \"design\"`* →\n        - 用户提供 `ref_file_url` 时保留该 URL，并**省略** `ref_file_index`。\n        - 用户提供下标（`ref_file_index`）时，确认 `ref_file_ids` 存在且下标有效，然后设为 `\"ref_file_id\": ref_file_ids[index]`（选填——部分后端期望的是原始下标，而非 id）。\n\n        1. **规整数值范围** – 超出范围的值收敛到 0‑100 或长度上限。\n        2. **补齐缺失的选填键** 并填入默认值，让 Schema 校验通过。\n        3. **序列化** 最终对象为 JSON（紧凑格式，或便于排错的缩进格式）。\n\n   * 请求示例（可直接发送）\n        ```\n        {\n        \"version\": \"1.0\",\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg\",\n        \"effect_type\": \"press_on_nails\",\n        \"ref_file_ids\": [\n            \"Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud\",\n            \"+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud\"\n        ],\n        \"effects\": [\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"thumb\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 0\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"index\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 1\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"middle\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"pinky\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"ring\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png\"\n            }\n        ]\n        }\n        ```\n\n\n3. 创建美甲 VTO 任务并轮询结果\n\n    图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n    * 创建任务接口\n\n        ```\n        POST /s2s/v2.0/task/nail-vto\n        ```\n\n    * 轮询接口\n\n        ```\n        GET /s2s/v2.0/task/nail-vto/{task_id}\n        ```\n\n---\n\n## 文件规格与错误码\n\n* AI 美甲虚拟试用规格\n\n**支持的指甲视角**\n单张指甲图片，正面视角清楚、无遮挡。\n\n| 项目 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| --- | --- | --- | --- |\n| 美甲设计图 - 甲油胶 | *   271 px ≤ 宽 ≤ 542 px<br>*   522 px ≤ 高 ≤ 1044 px<br>*   至少 72ppi<br>图片会从中央开始套用，虚拟试戴效果会随用户指甲长度而变化。 | ≤ 1MB | png |\n| 美甲设计图 - 穿戴甲 | *   271 px ≤ 宽 ≤ 542 px<br>*   522 px ≤ 高 ≤ 1044 px<br>*   0.5 ≤ 图片宽高比（高/宽）≤ 3.5<br>*   至少 72ppi<br>图片的内容、甲形与长度设置都会用于生成虚拟试戴效果。<br>系统会检测用户指甲宽度以确保图片缩放恰当，建议为每根指甲分别制作符合正确宽高比的图片。<br>请下载穿戴甲设计图示例，并参照图片规范了解更多细节。下载：[Nail_Design_Image_Guidelines.pdf](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/You_Cam_API_AI_Nail_Virtual_Try_On_Press_on_Nail_Design_Image_Guidelines_a229b51750.pdf) | ≤ 1MB​ | png（透明背景） |\n\n穿戴甲设计图示例：\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png)\n\n[<img src=\"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png\" width=\"60\"/>](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png)\n\n---\n\n**支持的手部视角**\n\n| 项目 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| --- | --- | --- | --- |\n| 用户照片 | *   长边 ≤ 2048<br>*   短边 ≥ 256 | ≤ 10MB | jpg/jpeg/png |\n* 输入图片中只支持一只手\n* 手掌面积最好至少占输入图片的一半\n* 输入图片的宽高比最好是 1:1、3:4、4:3\n* 手指甲不得被遮挡\n* 指甲上最好没有甲片与甲油\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg)\n\n---\n\n* 错误码\n\n| 错误码 | 说明 |\n|  ----  | ----  |\n| error_nail_too_small | 指甲区域太小。 |\n| error_no_nail\t| 源图中未检测到指甲。 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 美甲虚拟试用 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_eye_color_lens.yaml","link":"/zh-cn/reference/ai_eye_color_lens","routeSlug":"/zh-cn/reference/ai_eye_color_lens","label":"AI 美瞳虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_eye_color_lens/section/概览","routeSlug":"/zh-cn/reference/ai_eye_color_lens/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_eye_color_lens/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_eye_color_lens/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_eye_color_lens/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_eye_color_lens/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_eye_color_lens/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_eye_color_lens/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_eye_color_lens/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_eye_color_lens/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_eye_color_lens/v1.0","routeSlug":"/zh-cn/reference/ai_eye_color_lens/v1.0","items":[{"label":"执行 AI 美瞳虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","routeSlug":"/zh-cn/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto/post","metadata":{"seo":{"title":"执行 AI 美瞳虚拟试戴 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/eye-color-vto"},{"label":"查询 AI 美瞳虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_eye_color_lens/v1.0/paths/~1s2s~1v2.0~1task~1eye-color-vto~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 美瞳虚拟试戴 任务的状态。","description":"查询 AI 美瞳虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/eye-color-vto/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 美瞳虚拟试戴","version":"","description":"# 概览\nAI 美瞳虚拟试戴带来即时、逼真到位的隐形眼镜试戴体验：精准定位虹膜，保留自然反光，对各种瞳色都能准确模拟镜片的透光度与融合效果；从淡淡修饰到惊艳的蓝色系，一个专业级 AI 接口全搞定。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-01-25/2a348e5b-6a2b-4f08-bc54-1d16a0777e87.jpg)\n\n**隐形眼镜虚拟试戴**\n\n用我们这套 AI 虚拟试戴工具，眼珠颜色瞬间就换。AI 美瞳虚拟试戴靠精准定位虹膜、套用自然逼真的色彩变化，做出以假乱真的效果；顾客不用拿到实物样品，也能试遍新风格。\n\n**逼真到位的输出**  \n系统保留眼睛的自然反光，画面真实，每一次换色都看着像真的一样。\n\n**先进的镜片滤镜模拟**  \n美瞳滤镜能针对不同底色虹膜准确还原透光度与融合效果，顾客可以虚拟试戴整条产品线，颜色层次与深浅都真实。\n\n**不只是个“换瞳色”工具**  \n这项技术超出普通滤镜，给的是专业级的虚拟美瞳体验，顾客买得更有底气，转化也更好。\n\n---\n\n## 接入指南\n\n* 拍一张自拍\n\n    *   正对镜头，光线充足。\n    *   也可以用 JS Camera Kit 拍照。\n\n* 准备您的美瞳样式图\n\n*   请提供**一张清晰的美瞳样式图**：\n\n    *   格式：**PNG**（建议已去背景）\n    *   尺寸：**200 × 200 ≤ W × H ≤ 600 × 600**\n    *   文件大小：**< 10 MB**\n\n    **示例：**\n\n    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/01.00ccf3ac.png)\n    ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/02.c8beb3fc.png)\n\n* 通过 ***/s2s/v2.0/file*** 接口取得上传 URL 与文件 ID\n\n    用 File 接口响应中返回的上传 URL 上传以下文件：\n    *   您的自拍照片\n    *   美瞳样式图\n\n* 执行 AI 任务 ***/s2s/v2.0/task/eye-color-vto***\n\n    用文件 ID 或图片 URL 作为输入源执行 AI 任务，特效参数按需要设置。\n\n* 轮询任务状态\n\n    用返回的 **task\\_id** 监控任务进度。  \n    轮询 **GET /task/eye-color-vto** 查看引擎状态。  \n    任务完成之前会一直处于 **“running”** 状态，这一阶段不消耗点数。\n\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_9535461b-69fc-4432-b56b-2d7c4cd0bf3b_b1ef78e813.jpg)\n\n\n\n* **应用示例**\n\n    AI 美瞳虚拟试戴改变了顾客选购彩色隐形眼镜的方式。流程直白、有参与感，顾客几乎不用费什么力。\n\n    - Step1：挑您喜欢的颜色\n    顾客进站浏览您的商品后，可以挑出想试的颜色。无论是低调的棕褐、鲜亮的绿色，还是清冷的冰蓝，各种颜色都能试。\n\n    - Step 2：开启虚拟试戴相机\n    一点即开，不用复杂的设置说明，也不用额外下载。\n\n    - Step 3：用实时相机或上传照片\n    用户可以走实时相机体验，也可以上传一张照片来虚拟试戴彩色隐形眼镜。效果还原真实，准头让人信服，让顾客看清每种颜色在自然光线下是什么样。\n\n    ![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-28/2732a9f0-9cae-4639-b765-15866550b109.jpg)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 美瞳虚拟试戴|自拍图片：<br>    *   长边 ≤ 1920 px <br>    *   短边 ≥ 320 px <br><br>美瞳样式图：<br>    *   文件格式：PNG <br>    *   分辨率：200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png|\n\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|图片宽或高小于 320 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 美瞳虚拟试戴 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_teeth_whitening.yaml","link":"/zh-cn/reference/ai_teeth_whitening","routeSlug":"/zh-cn/reference/ai_teeth_whitening","label":"AI 牙齿美白","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_teeth_whitening/section/概览","routeSlug":"/zh-cn/reference/ai_teeth_whitening/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_teeth_whitening/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_teeth_whitening/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_teeth_whitening/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_teeth_whitening/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_teeth_whitening/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_teeth_whitening/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_teeth_whitening/v1.0","routeSlug":"/zh-cn/reference/ai_teeth_whitening/v1.0","items":[{"label":"执行 AI 牙齿美白 检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","routeSlug":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process/post","metadata":{"seo":{"title":"执行 AI 牙齿美白 检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process"},{"label":"查询 AI 牙齿美白 检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 牙齿美白 检测任务的状态。","description":"查询 AI 牙齿美白 检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/pre-process/{task_id}"},{"label":"执行 AI 牙齿美白 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","routeSlug":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten/post","metadata":{"seo":{"title":"执行 AI 牙齿美白 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten"},{"label":"查询 AI 牙齿美白 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_teeth_whitening/v1.0/paths/~1s2s~1v2.0~1task~1teeth-whiten~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 牙齿美白 任务的状态。","description":"查询 AI 牙齿美白 任务的状态。"}},"httpPath":"/s2s/v2.0/task/teeth-whiten/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 牙齿美白","version":"","description":"# 概览\n**AI 牙齿美白接口**\n\nAI 牙齿美白接口提供先进的自动化方案，把照片里的笑容打理得更出彩。它用智能图像处理，把牙齿自然、准确地提亮，几秒钟就出精致专业的效果。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-07-28/f05fda4d-8ca8-4661-b4b5-135067280a10.jpg)\n\n\n\n\n**它是怎么去掉照片里发黄牙齿的**\n\n**智能美白**  \n接口会自动检测牙齿，套用看着自然的白牙效果，画面不会假。\n\n**强度可调**  \n内置调节功能，美白程度由您掌握：从微微提亮，到上镜级的明显白皙。\n\n\n\n**主要特性**\n\n**又快又省事**  \n几秒钟就能让笑容明显更亮。\n\n**AI 检测精准**  \n先进的检测只改动牙齿，整体观感真实、协调。\n\n**美白强度可调**  \n按您喜欢的效果微调美白力度。\n\n**先进算法，效果自然**\n\nAI 牙齿美白接口采用精密算法，准确识别牙齿，套用出来的美白效果贴近真实。您可以微调强度，做出含蓄自然的改善，让最终效果看着真实、顺眼。\n\n---\n\n## 接入指南\n\n* 拍一张自拍\n\n    *   正对镜头，光线充足。\n    *   也可以用 JS Camera Kit 拍照。\n\n* 通过 ***/s2s/v2.0/file*** 接口取得上传 URL 与文件 ID\n\n    用 File 接口响应中返回的上传 URL 上传以下文件：\n    *   您的自拍照片\n\n* 执行 AI 任务 ***/s2s/v2.0/task/teeth-whiten***\n\n    用文件 ID 或图片 URL 作为输入源执行 AI 任务，特效参数按需要设置。\n\n* 轮询任务状态\n\n    用返回的 **task\\_id** 监控任务进度。  \n    轮询 **GET /s2s/v2.0/task/teeth-whiten/{task_id}** 查看引擎状态。  \n    任务完成之前会一直处于 **“running”** 状态，这一阶段不消耗点数。\n\n\n\n* **用法演示**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-05-13/26c04462-d183-4392-937b-f6173ff9e814.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-01/webp_a4cd3779-2966-4b8f-888e-032dffc003c0.webp)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-11-13/webp_5824c85f-813e-4c14-b036-38cba206ee0b.webp)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 牙齿美白|自拍图片：<br>    *   长边 ≤ 1920 px <br>    *   短边 ≥ 320 px |< 10MB|jpg/png|\n\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_exceed_max_image_size | 图片长边超过 1920 像素 |\n|error_below_min_image_size|图片宽或高小于 320 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 牙齿美白 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"头发与胡子","labelTranslationKey":"sidebar.reference.separators.hairBeard"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hairstyle.yaml","link":"/zh-cn/reference/ai_hairstyle","routeSlug":"/zh-cn/reference/ai_hairstyle","label":"AI 发型虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hairstyle/section/概览","routeSlug":"/zh-cn/reference/ai_hairstyle/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hairstyle/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hairstyle/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hairstyle/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hairstyle/section/概览/文件规格与错误码"},{"type":"link","label":"常见问题","link":"/zh-cn/reference/ai_hairstyle/section/概览/常见问题","routeSlug":"/zh-cn/reference/ai_hairstyle/section/概览/常见问题"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hairstyle/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hairstyle/section/概览/点数消耗"}]},{"type":"group","label":"V2.1","link":"/zh-cn/reference/ai_hairstyle/v2.1","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.1","items":[{"label":"列出预置模板（v2.1）。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1template~1hair-transfer/get","metadata":{"seo":{"title":"列出预置模板（v2.1）。","description":"列出预置模板（v2.1）。"}},"httpPath":"/s2s/v2.1/task/template/hair-transfer"},{"label":"执行 AI 发型虚拟试戴（v2.1） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer/post","metadata":{"seo":{"title":"执行 AI 发型虚拟试戴（v2.1） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.1/task/hair-transfer"},{"label":"查询 AI 发型虚拟试戴（v2.1） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.1/paths/~1s2s~1v2.1~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型虚拟试戴（v2.1） 任务的状态。","description":"查询 AI 发型虚拟试戴（v2.1） 任务的状态。"}},"httpPath":"/s2s/v2.1/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_hairstyle/v2.0","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.0","items":[{"label":"执行 AI 发型虚拟试戴 任务（带参考图）。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer/post","metadata":{"seo":{"title":"执行 AI 发型虚拟试戴 任务（带参考图）。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/hair-transfer"},{"label":"查询 AI 发型虚拟试戴（带参考图）任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hairstyle/v2.0/paths/~1s2s~1v2.0~1task~1hair-transfer~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型虚拟试戴（带参考图）任务的状态。","description":"查询 AI 发型虚拟试戴（带参考图）任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-transfer/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hairstyle/v1.0","routeSlug":"/zh-cn/reference/ai_hairstyle/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","routeSlug":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-style/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/hair-style"},{"label":"执行 AI 发型虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","routeSlug":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style/post","metadata":{"seo":{"title":"执行 AI 发型虚拟试戴 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/hair-style"},{"label":"查询 AI 发型虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hairstyle/v1.0/paths/~1s2s~1v2.0~1task~1hair-style~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型虚拟试戴 任务的状态。","description":"查询 AI 发型虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-style/{task_id}"}]}],"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<https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/>\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 接口上传；<BR>参考图若已托管在网上，用 `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/<YOUR_TASK_ID> \\\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</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 点 <br> 自定义模式 2 点 |\n| AI 发型虚拟试戴 V2.1 | 预设模式 2 点 <br> 自定义模式 2 点 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_color.yaml","link":"/zh-cn/reference/ai_hair_color","routeSlug":"/zh-cn/reference/ai_hair_color","label":"AI 发色虚拟试染","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_color/section/概览","routeSlug":"/zh-cn/reference/ai_hair_color/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_color/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_color/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_color/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_color/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_color/v1.0","routeSlug":"/zh-cn/reference/ai_hair_color/v1.0","items":[{"label":"执行 AI 发色虚拟试染 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","routeSlug":"/zh-cn/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color/post","metadata":{"seo":{"title":"执行 AI 发色虚拟试染 任务。","description":"本接口用于发起 AI 发色虚拟试染流程。您需要提供源文件（URL 或文件 ID），并指定上色方式（预设 preset、图案 pattern 或色板 palettes）。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/hair-color"},{"label":"查询 AI 发色虚拟试染 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_color/v1.0/paths/~1s2s~1v2.0~1task~1hair-color~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发色虚拟试染 任务的状态。","description":"查询 AI 发色虚拟试染 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-color/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 发色虚拟试染","version":"","description":"# 概览\n用 AI 发色虚拟试染玩遍各种发色！一直想试的发色尽管试，没试过的新鲜色号也能玩。拉一拉滑杆就能调整所选颜色的浓淡，做出专属您的效果。\n\n   * 上传图片\n\n上传您要改发色的照片。\n\n   * 选预设色，或按图案与配色自行调配\n\n从预设色里挑，也能微调渐变（ombre）的覆盖范围与融合度，玩法无穷！\n\n> **警告：** 若同时指定了预设色与图案 + 配色，以预设色优先。\n\n> **警告：** 源图必须包含您要染的头发区域，套用前请再确认一次。源图里没带上想染的头发区域，后果需由您自行承担。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_color_s2_poster_dt_v2_49198cabc0.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_1_1_8365c3b503.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/01_2_1_abfcdb7eba.jpg)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发色虚拟试染|长边 < 1920，脸宽 >= 100|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|源图尺寸小于下限（要求：宽 >= 320px，高 >= 320px）\n|error_exceed_max_image_size|源图尺寸超过上限（要求：宽 < 1920px，高 < 1080px）\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 发色虚拟试染虚拟试戴 V1.0 | 全头模式 1 点数 <br> 渐变模式 1 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_extension.yaml","link":"/zh-cn/reference/ai_hair_extension","routeSlug":"/zh-cn/reference/ai_hair_extension","label":"AI 接发虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_extension/section/概览","routeSlug":"/zh-cn/reference/ai_hair_extension/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_extension/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_extension/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_extension/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_extension/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_extension/v1.0","routeSlug":"/zh-cn/reference/ai_hair_extension/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","routeSlug":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-ext/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/hair-ext"},{"label":"执行 AI 接发虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","routeSlug":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext/post","metadata":{"seo":{"title":"执行 AI 接发虚拟试戴 任务。","description":"本接口用模板与源图片发起接发生成流程。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/hair-ext"},{"label":"查询 AI 接发虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_extension/v1.0/paths/~1s2s~1v2.0~1task~1hair-ext~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 接发虚拟试戴 任务的状态。","description":"查询 AI 接发虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-ext/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 接发虚拟试戴","version":"","description":"# 概览\n用 AI 找到最合心意的接发效果​\n在设备上就能试遍各种长度——从长发到超长——以及各式发型、发色与刘海。不用凭感觉猜，先进的生成式 AI 让您看清每种接发效果戴在您头上的样子，决定换造型之前心里有数。​\n先进的接发试戴能与您的现有发长自然衔接，正是尝试超长发型的好时机。\n\n使用场景：\n![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S2_img_07_098b6e08c4.jpg \"AI Hair Extension\")\n\n![AI Hair Extension](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Extension_Filter_S1_img_01_eab88fe3e2.jpg \"AI Hair Extension\")\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n---\n\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|error_bald_image\t|输入的发型为光头\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 接发虚拟试戴 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_bangs.yaml","link":"/zh-cn/reference/ai_bangs","routeSlug":"/zh-cn/reference/ai_bangs","label":"AI 刘海滤镜虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_bangs/section/概览","routeSlug":"/zh-cn/reference/ai_bangs/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_bangs/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_bangs/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_bangs/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_bangs/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_bangs/v1.0","routeSlug":"/zh-cn/reference/ai_bangs/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","routeSlug":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-bang/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/hair-bang"},{"label":"执行 AI 刘海滤镜虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","routeSlug":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang/post","metadata":{"seo":{"title":"执行 AI 刘海滤镜虚拟试戴 任务。","description":"本接口用模板与源图片发起刘海生成流程。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/hair-bang"},{"label":"查询 AI 刘海滤镜虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_bangs/v1.0/paths/~1s2s~1v2.0~1task~1hair-bang~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 刘海滤镜虚拟试戴 任务的状态。","description":"查询 AI 刘海滤镜虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-bang/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 刘海滤镜虚拟试戴","version":"","description":"# 概览\n用 AI 试出最适合您的刘海\n效果真实：试戴逼真的刘海，找出最衬您脸型的样式。​\n样式丰富：各式刘海任您挑，各种性格、各种场合都顾得到。​\n上手轻松：界面友好，试新刘海轻松好玩​。\n\n想看更多刘海样式？请参见 https://yce.makeupar.com/bangs-filter。\n\n使用场景：\n\n![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_1_259f619dfd.png \"AI Hair Bang Generator\")\n\n![AI Hair Bang Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_1200x674px_2_7146754733.png \"AI Hair Bang Generator\")\n\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 刘海滤镜虚拟试戴生成|长边 <= 1024，脸宽 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，需露出完整脸部|< 10MB|jpg/jpeg/png|\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|error_bald_image\t|输入的发型为光头\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 刘海滤镜虚拟试戴 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_volume.yaml","link":"/zh-cn/reference/ai_hair_volume","routeSlug":"/zh-cn/reference/ai_hair_volume","label":"AI 丰发虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_volume/section/概览","routeSlug":"/zh-cn/reference/ai_hair_volume/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_volume/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_volume/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_volume/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_volume/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_volume/v1.0","routeSlug":"/zh-cn/reference/ai_hair_volume/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","routeSlug":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-vol/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/hair-vol"},{"label":"执行 AI 丰发虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","routeSlug":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol/post","metadata":{"seo":{"title":"执行 AI 丰发虚拟试戴 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/hair-vol"},{"label":"查询 AI 丰发虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_volume/v1.0/paths/~1s2s~1v2.0~1task~1hair-vol~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 丰发虚拟试戴 任务的状态。","description":"查询 AI 丰发虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-vol/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 丰发虚拟试戴","version":"","description":"# 概览\n即刻拥有蓬松丰盈的发量，整体形象更出彩！​\n发量少、发质稀疏？加上自然蓬松感。用 AI 无缝补齐空缺、增发发量。直发、卷发、细软发都适用，相亲资料、简历等场合都能派上用场。\n我们的 AI 工具能让您的每张照片都拥有恰到好处的发量与发密度，私人照、职业照、社交照都合适。告别照片里的塌发时刻，张张都是清爽蓬松的好发质。\n\n使用场景：\n![AI Hair Volume Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_Hair_Volume_Filter_S4_img_01_836436ca00.jpg \"AI Hair Volume Generator\")\n\n![AI Hair Volume Generator](https://plugins-media.makeupar.com/smb/blog/post/2024-08-26/51eadc51-aaa7-4ebc-ac78-e389be5e16b0.jpg \"AI Hair Volume Generator\")\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发量增强|长边 <= 1024，脸宽 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，需露出完整脸部|< 10MB|jpg/jpeg/png|\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|error_bald_image\t|输入的发型为光头\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 发量虚拟试戴 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_wavy_hair.yaml","link":"/zh-cn/reference/ai_wavy_hair","routeSlug":"/zh-cn/reference/ai_wavy_hair","label":"AI 波浪卷发虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_wavy_hair/section/概览","routeSlug":"/zh-cn/reference/ai_wavy_hair/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_wavy_hair/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_wavy_hair/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_wavy_hair/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_wavy_hair/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_wavy_hair/v1.0","routeSlug":"/zh-cn/reference/ai_wavy_hair/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","routeSlug":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1template~1hair-curl/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/hair-curl"},{"label":"执行 AI 波浪卷发虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","routeSlug":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl/post","metadata":{"seo":{"title":"执行 AI 波浪卷发虚拟试戴 任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/hair-curl"},{"label":"查询 AI 波浪卷发虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_wavy_hair/v1.0/paths/~1s2s~1v2.0~1task~1hair-curl~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 波浪卷发虚拟试戴 任务的状态。","description":"查询 AI 波浪卷发虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-curl/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 波浪卷发虚拟试戴","version":"","description":"# 概览\n不管是想要蓬松的卷圈、松散的大波浪，还是张扬的卷发造型，YouCam API 的卷发特效都能让您几秒钟就试到耳目一新的好发型——足不出户就能玩。\n\n从柔和波浪到爆炸头，YouCam 的精准度和真实感都有口皆碑。下次去理发店之前，先用它大胆试新发型，心里更有底。\n\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-04-01/webp_03963789-fb1e-4ad8-be4d-48932e247376.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-03-20/b25b228a-259b-4efb-a7c1-31d200b62e8c.jpg)\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 卷发|长边 <= 1024，脸宽 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，需露出完整脸部|< 10MB|jpg/jpeg/png|\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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 卷发虚拟试戴 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_beard_style.yaml","link":"/zh-cn/reference/ai_beard_style","routeSlug":"/zh-cn/reference/ai_beard_style","label":"AI 胡型生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_beard_style/section/概览","routeSlug":"/zh-cn/reference/ai_beard_style/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_beard_style/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_beard_style/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_beard_style/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_beard_style/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_beard_style/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_beard_style/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_beard_style/v1.0","routeSlug":"/zh-cn/reference/ai_beard_style/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","routeSlug":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/beard-style"},{"label":"执行 AI 胡型生成器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","routeSlug":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post","metadata":{"seo":{"title":"执行 AI 胡型生成器 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/beard-style"},{"label":"查询 AI 胡型生成器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 胡型生成器 任务的状态。","description":"查询 AI 胡型生成器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/beard-style/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 胡型生成器","version":"","description":"# 概览\nAI 男士胡须造型模拟\n\nAI 算法也照顾到男士：凭借精细的胡须模拟技术，络腮胡、短须、全须、圈须、八字胡、山羊胡等各式胡型都能自由虚拟试戴。\n\n消费者还能直接看到剃前剃后的对比，不用真拿剃刀往皮肤上招呼。\n胡须滤镜包含八字胡、短方胡、鸭尾胡、圈胡等十余种。\n\n## 接入指南\n\n1. **上传自拍**\n  源图有两种提供方式：\n\n  - **使用已有的公开图片 URL**\n    不必上传，发起 AI 任务时直接给一个可公开访问的图片 URL 即可。\n\n  - **通过 File 接口上传**\n    接口地址：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    这会返回一个 `file_id`，供后续执行任务时使用。\n\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br></br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n2.  **获取预设风格列表**\n    *   调用 /s2s/v2.0/task/template/beard-style 取得预设模板列表，挑一个 ``template_id`` 用于执行 AI 任务。\n\n3.  **执行 AI 任务并取得 Task ID**\n    用 /s2s/v2.0/task/beard-style 执行 AI 任务。目标用户图请提供 ``src_file_url`` 或 ``src_file_id``，再给出要套用的风格 ``template_id``，即可取得 ``task_id``。\n\n4.  **轮询任务状态，直到成功或失败**\n    用 ``task_id`` 轮询 GET /s2s/v2.0/task/beard-style 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 running，这一阶段不消耗点数。\n    您也可以实现 Webhook，在 AI 任务成功或失败时收到通知。细节见 **[Webhook](../../../develop/webhook)** 一节。\n\n    > **警告：** 在任务保留期内轮询任务状态是必须做的。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样，而您的点数照样会被消耗。\n\n    > **警告：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，执行 AI 任务之后，必须在保留期内持续轮询，直到状态变为 success 或 error。\n\n5.  **任务成功后取回结果**\n    引擎处理完您的输入文件、生成出图后，任务状态会变为 success，您会收到一张处理后图片的 URL。\n\n---\n\n## 文件规格与错误码\n   * 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 胡须造型生成|分辨率：长边 < 1024 <br>脸宽 > 256 <br>脸部姿态：-30 < yaw < 30，<br>仅支持单人脸，<br>需露出完整脸部|< 10MB|jpg/jpeg|\n\n   * 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_no_face\t|源图中看不到脸\n|error_src_face_too_small\t|人脸过小\n|error_inference\t|胡须去除失败或胡须生成失败\n|error_face_pose\t|源图的脸部姿态不受支持\n\n   * 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 胡须造型生成 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_type_detection.yaml","link":"/zh-cn/reference/ai_hair_type_detection","routeSlug":"/zh-cn/reference/ai_hair_type_detection","label":"AI 发型发质类型检测","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_type_detection/section/概览","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hair_type_detection/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览/接入指南"},{"type":"link","label":"发质分级","link":"/zh-cn/reference/ai_hair_type_detection/section/概览/发质分级","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览/发质分级"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_type_detection/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_hair_type_detection/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_type_detection/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_type_detection/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_type_detection/v1.0","routeSlug":"/zh-cn/reference/ai_hair_type_detection/v1.0","items":[{"label":"执行 AI 发型发质类型检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","routeSlug":"/zh-cn/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection/post","metadata":{"seo":{"title":"执行 AI 发型发质类型检测任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/hair-type-detection"},{"label":"查询 AI 发型发质类型检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_type_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-type-detection~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型发质类型检测任务的状态。","description":"查询 AI 发型发质类型检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-type-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 发型发质类型检测","version":"","description":"# 概览\n想象口袋里装着一位 AI 头发专家。我们的技术会深入研究您头发的质地、粗细与卷曲形态，从十种独特的卷形中判别，归入九大类型，从直发一直到极卷。您能得到一份完整的头发档案，品牌方可据此为您精准推荐产品与护理建议。\n\n## 接入指南\n* AI 发型发质类型检测怎么拍照\n* 从左、正脸到右，拍三张。\n  - 连拍三张自拍就行：一张正对镜头，一张向左转约 45 度，一张向右转 45 度。目的是把头发各侧面的样子都拍到。每张照片里，整张脸和头发的上缘都要清楚可见。脸部宽度约占图片宽度的 50% 到 80%，别太小也别太近，这样分析起来才够清楚。拍侧面照时，头左右转动，就像摇头说“不”一样（这就是 yaw 旋转）。头部保持水平，不要抬头、低头或侧倾。不要拍仰角或俯角，那些角度我们用不上。\n  - 也可以用 JS Camera Kit 拍照。头发不要扎起来，让它垂在胸前。头向右转稳住，再向左转，凑齐三张供分析。\n\n* 如何用 AI 检测发质\n* 请用 ***/s2s/v2.0/file*** 接口上传以下素材：\n  - 正面、右侧、左侧三张照片。\n\n* 执行 AI 任务 ***/s2s/v2.0/task/hair-type-detection*** </br>\n送三张图来执行 AI 发型发质类型检测任务：一张正面、一张右侧、一张左侧。把它们的文件 ID 作为 AI 的输入源。\n\n* 轮询任务状态，直到成功或报错</br>\n用这个 ***task_id*** 轮询 GET 'task/hair-type-detection' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n## 发质分级\n|类型|缩略图|发质分级|说明|\n|  ----  | ----  | ----  | ----  |\n|1|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t1.b19d4657.jpg)|直发| 发丝自然不带卷，从发根一路垂到发梢|\n|2A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2A.351ef0a6.jpg)|微波浪| 波浪细微柔和，质感顺而略蓬，但发根处不够蓬松|\n|2B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2B.daac62f4.jpg)|中波浪| 呈自然的 S 形波浪，多从头发表面中段开始起卷，贴着头部垂落，层次含蓄而精致|\n|2C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t2C.10ef2132.jpg)|粗波浪| 波浪质感偏粗，呈“S”形，自发起卷一路延伸到发梢，容易毛躁|\n|3A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3A.073b6767.jpg)|大卷| 卷度大而舒展、蓬松有弹性，从发根到发梢都有明显光泽|\n|3B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3B.06bf109b.jpg)|中卷| 发丝偏粗、卷圈有弹性，容易毛躁|\n|3C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t3C.9091ea1e.jpg)|小卷| 卷形紧密成螺丝状，密度高，蓬松感足|\n|4A|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4A.cf742771.jpg)|软小卷| 呈紧密排列、有弹性的 S 形卷|\n|4B|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4B.4a6300fe.jpg)|极卷| 卷圈密集，折成锐利的锯齿状|\n|4C|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_t4C.4ed5a7f8.jpg)|超极卷| 卷度紧而蓬松，更容易断裂|\n\n* 结果参数\n* mapping: result 是一个字符串，表示检测出的发质类型代号。所有可能的结果字符串列在下面的数组中：\n  ```json\n  [\"1 to 2a\", \"2a to 2b\", \"2b to 2c\", \"2c to 3a\", \"3a to 3b\", \"3b to 3c\", \"3c to 4a\", \"4a to 4b\", \"4b to 4c\"]\n  ```\n* term: 发质类型代号与分级名称之间的一一对应字符串。所有可能的结果字符串列在下面的数组中：\n  ```json\n  [\"Straight to Slight Wavy\", \"Slight to Medium Wavy\", \"Medium to Thick Wavy\", \"Thick Wavy to Loose Curls\", \"Loose to Medium Curls\", \"Medium to Tight Curls\", \"Tight Curls to Kinky Soft\", \"Kinky Soft to Coily\", \"Coily to Extremely Coily\"]\n  ```\n\n* 拍摄建议\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Type%20Detection_how%20to%20shoot.png \"Suggestions for How to Shoot\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发型发质类型检测|图片宽高至少 320 像素，任一维度不超过 4096 像素。若某一边超过 1080 像素，会自动缩放到该上限以内进行分析。|< 10MB|jpg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_mismatch_image_size|请确保正脸、左侧、右侧三张人脸照片尺寸一致|\n|error_below_min_image_size|图片宽或高小于 320 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 发型发质类型检测 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_length_detection.yaml","link":"/zh-cn/reference/ai_hair_length_detection","routeSlug":"/zh-cn/reference/ai_hair_length_detection","label":"AI 发型发长检测","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_length_detection/section/概览","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hair_length_detection/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览/接入指南"},{"type":"link","label":"发长分级","link":"/zh-cn/reference/ai_hair_length_detection/section/概览/发长分级","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览/发长分级"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_length_detection/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_hair_length_detection/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_length_detection/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_length_detection/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_length_detection/v1.0","routeSlug":"/zh-cn/reference/ai_hair_length_detection/v1.0","items":[{"label":"执行 AI 发型发长检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","routeSlug":"/zh-cn/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection/post","metadata":{"seo":{"title":"执行 AI 发型发长检测任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/hair-length-detection"},{"label":"查询 AI 发型发长检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_length_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-length-detection~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型发长检测任务的状态。","description":"查询 AI 发型发长检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-length-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 发型发长检测","version":"","description":"# 概览\nAI 发长测量为护发品牌与理发店提供快速方案，分析并测量头发长度，便于据此做出个性化产品与服务的决策。\n我们的 AI 在海量、多样的图片数据集上精心训练，确保 AI 发型发长检测精准可靠。它分析数千张各种发质与发型的图片，能准确识别并归入五种发长，从耳上到背部中段，准确度出众。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg)\n\n## 接入指南\n* AI 发型发长检测怎么拍照\n* 正脸自拍一张\n  - 拍一张清楚的照片即可，正对镜头。头发散下放下来、垂到胸前，视线直视前方，做出正对镜头的角度。\n  - 也可以用 JS Camera Kit 拍照。同样把头发散下放下来、垂到胸前，不要扎起来。\n\n* 如何用 AI 检测发长\n* 请用 ***/s2s/v2.0/file*** 接口上传以下素材：\n  - 您的自拍照片。\n\n* 执行 AI 任务 ***/s2s/v2.0/task/hair-length-detection*** </br>\n送一张正脸自拍图片来执行 AI 发型发长检测任务，把它的文件 ID 作为 AI 的输入源。\n\n* 轮询任务状态，直到成功或报错</br>\n用这个 ***task_id*** 轮询 GET 'task/hair-length-detection' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n## 发长分级\n|缩略图|发长分级|说明|\n| ----  | ----  | ----  |\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_the_ears.b41525da.png)|耳上长度|头发刚好垂在耳朵上方，利落时髦，把脸型衬得很好看。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_ear_length.0740b805.png)|齐耳长度|头发垂到耳垂，俏皮百搭，打理起来省心。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_short_hair.d7f24ddb.png)|短发|头发剪在肩膀以上，清爽现代，既个性又好打理。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_chest.1b624c17.png)|中长发|头发垂到锁骨附近，长度恰到好处，盘发、披发都合适。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_longer_hair.7fbcc9d0.png)|长发|长发尽显优雅，气质经典，造型选择多。|\n\n* 结果参数\n* term: result 是一个字符串，表示检测出的发长类型。所有可能的结果字符串列在下面的数组中：\n  ```json\n  [\"above the ears\", \"ear length\", \"ear length or longer\", \"short hair\", \"short hair or longer\", \"above chest\", \"above chest or longer\", \"long hair\"]\n  ```\n\n* 拍摄建议\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Length%20Detection_how%20to%20shoot.png \"Suggestions for How to Shoot\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发型发长检测|图片宽高至少 320 像素，任一维度不超过 4096 像素。若某一边超过 1080 像素，会自动缩放到该上限以内进行分析。|< 10MB|jpg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|图片宽或高小于 320 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 发型发长检测 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_frizziness_detection.yaml","link":"/zh-cn/reference/ai_hair_frizziness_detection","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection","label":"AI 发型毛躁度检测","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0","items":[{"label":"执行 AI 发型毛躁度检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post","metadata":{"seo":{"title":"执行 AI 发型毛躁度检测任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection"},{"label":"查询 AI 发型毛躁度检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型毛躁度检测任务的状态。","description":"查询 AI 发型毛躁度检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-frizziness-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 发型毛躁度检测","version":"","description":"# 概览\n三张照片，180° 全景看头发毛躁\n\nAI 毛躁分析只需上传三张照片——头发的正面、左侧、右侧视角——几秒钟就能给出精准的毛躁程度分析。\n\n这套流程效率很高，几秒钟就出结果，商家可依据头发毛躁等级提供针对性护发方案与抗毛躁产品，不必花时间去线下咨询，不用做复杂的头发问卷，也不需要装专业设备。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg)\n\n## 接入指南\n\n1. **上传自拍**\n  源图有两种提供方式：\n\n  - **使用已有的公开图片 URL**\n    不必上传，发起 AI 任务时直接给一个可公开访问的图片 URL 即可。\n\n  - **通过 File 接口上传**\n    接口地址：\n    ```\n    POST /s2s/v2.0/file\n    ```\n    这会返回一个 `file_id`，供后续执行任务时使用。\n\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。\n\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n\n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n2.  **执行 AI 任务并取得 Task ID**\n    用 /s2s/v2.0/task/hair-frizziness-detection 执行 AI 任务。目标用户图请提供 ``src_file_url`` 或 ``src_file_id``，再给出要套用的风格 ``template_id``，即可取得 ``task_id``。\n\n3.  **轮询任务状态，直到成功或失败**\n    用 ``task_id`` 轮询 GET /s2s/v2.0/task/hair-frizziness-detection 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 running，这一阶段不消耗点数。\n    您也可以实现 Webhook，在 AI 任务成功或失败时收到通知。细节见 **[Webhook](../../../../develop/webhook)** 一节。\n\n    > **警告：** 在任务保留期内轮询任务状态是必须做的。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样，而您的点数照样会被消耗。\n\n    > **警告：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，执行 AI 任务之后，必须在保留期内持续轮询，直到状态变为 success 或 error。\n\n4.  **任务成功后取回结果**\n    引擎处理完您的输入文件、生成出图后，任务状态会变为 success，您会收到一张处理后图片的 URL。\n\n## 输入与输出\n* 输入格式\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png)\n上传三张照片——头发的正面、左侧、右侧视角。\n您也可以用 JS Camera Kit 实现一个网页相机模块，拍出三张合格的图片。\n\n\n* 输出格式\nAI 毛躁分析会评估发质类型，并识别出四档毛躁程度——从顺滑头发到极度毛躁，把头发毛躁状况讲得明明白白。\n\n| **Mapping（0–3）** | **Term**            | **说明**                                           |\n| ----------------- | ------------------- | --------------------------------------------------------- |\n| 0             | 不毛躁      | 头发看起来顺滑，几乎看不到毛躁。     |\n| 1            | 轻微毛躁 | 可见轻度毛躁；表面质感略有毛糙。 |\n| 2             | 毛躁         | 整体可见毛躁；质感明显紊乱。   |\n| 3             | 极度毛躁  | 毛躁明显且范围大；头发质感高度紊乱。  |\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg)\n\n* 输出示例\n```json\n{\n  \"mapping\": 1, // number; the key to map of result, alternatives: [0, 1, 2, 3]\n  \"term\": \"Slightly Frizzy\" // string; 1-1 map to the \"mapping\", alternatives: [\"Not Frizzy\", \"Slightly Frizzy\", \"Frizzy\", \"Extreme Frizzy\"]\n}\n```\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发型毛躁度检测|图片宽高至少 320 像素，任一维度不超过 4096 像素。若某一边超过 1080 像素，会自动缩放到该上限以内进行分析。|< 10MB|jpg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_mismatch_image_size|请确保正脸、左侧、右侧三张人脸照片尺寸一致|\n|error_below_min_image_size|图片宽或高小于 320 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 发型毛躁度检测 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hair_density_detection.yaml","link":"/zh-cn/reference/ai_hair_density_detection","routeSlug":"/zh-cn/reference/ai_hair_density_detection","label":"AI 发型发量密度检测","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hair_density_detection/section/概览","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hair_density_detection/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览/接入指南"},{"type":"link","label":"发密度分级","link":"/zh-cn/reference/ai_hair_density_detection/section/概览/发密度分级","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览/发密度分级"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hair_density_detection/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_hair_density_detection/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hair_density_detection/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hair_density_detection/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_hair_density_detection/v1.0","routeSlug":"/zh-cn/reference/ai_hair_density_detection/v1.0","items":[{"label":"执行 AI 发型发量密度检测 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","routeSlug":"/zh-cn/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection/post","metadata":{"seo":{"title":"执行 AI 发型发量密度检测 任务。","description":"需要轮询才能查到任务状态，细节请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/hair-density-detection"},{"label":"查询 AI 发型发量密度检测 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hair_density_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-density-detection~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 发型发量密度检测 任务的状态。","description":"查询 AI 发型发量密度检测 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hair-density-detection/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 发型发量密度检测","version":"","description":"# 概览\nAI 发密度检测用照片就能快速做出专业评估：通过观察头皮显露程度与头发分布形态，把发密度分成四档，给出近似毛发镜检查的洞察，不必借助任何实体工具。商家上传一张图即可规模化地提供专家级的个性化服务。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S3_02_b34f2db2ce.jpg)\n\n## 接入指南\n* AI 发密度检测怎么拍照\n* 拍一张自拍\n  - 请正对镜头、光线充足，然后把头低到 45 度。头发不要扎起来，整条发际线要清楚可见。\n\n  ![](https://d3ss46vukfdtpo.cloudfront.net/static/media/img_popup_step_animated_02.aadf7a34.png)\n\n  - 也可以用 JS Camera Kit 拍照。\n\n* 如何用 AI 检测发密度\n* 请用 ***/s2s/v2.0/file*** 接口上传以下素材：\n  - 您的自拍照片。\n\n* 执行 AI 任务 ***/s2s/v2.0/task/hair-density-detection*** </br>\n送一张正脸、低头 45 度的自拍图片来执行检测任务，把它的文件 ID 作为 AI 的输入源。\n\n* 轮询任务状态，直到成功或报错</br>\n用这个 ***task_id*** 轮询 GET 'task/hair-density-detection' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n\n## 发密度分级\n\n|缩略图|发密度分级|说明|\n| ----  | ----  | ----  |\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV01.5097a6c2.png)|第 1 级<br>极低密度|头发明显稀疏，大面积可见头皮。发丝细，覆盖度很低。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV02.7966983d.png)|第 2 级<br>低密度|稀疏可见，头顶与分缝处头皮尤其明显。头发缺少蓬松感与厚度。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV03.c49dbfb7.png)|第 3 级<br>中等密度|强光下可部分看到头皮，但头发仍有一定蓬松度与覆盖度。发丝偏细，整体还算健康。|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/dt_classification_LV04.e467f2aa.png)|第 4 级<br>高密度|头发饱满浓密，几乎看不到头皮。发丝排列紧密，蓬松充足、覆盖自然。|\n\n\n* 拍摄建议\n\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/icon_S2_step1_20d0a161da.png \"Suggestions for How to Shoot\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_hair_density_S1_02_f60369b14d.jpg)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 发密度检测|图片宽高至少 100 像素，任一维度不超过 4096 像素。若某一边超过 1080 像素，会自动缩放到该上限以内进行分析。|< 10MB|jpg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|图片宽或高小于 100 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 发密度检测 V1.0 | 1 |\n\n---\n"}},{"type":"separator","label":"服饰","labelTranslationKey":"sidebar.reference.separators.fashion"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_clothes.yaml","link":"/zh-cn/reference/ai_clothes","routeSlug":"/zh-cn/reference/ai_clothes","label":"AI 时装虚拟试穿","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_clothes/section/概览","routeSlug":"/zh-cn/reference/ai_clothes/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_clothes/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_clothes/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_clothes/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_clothes/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_clothes/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_clothes/section/概览/点数消耗"}]},{"type":"group","label":"V4.0","link":"/zh-cn/reference/ai_clothes/v4.0","routeSlug":"/zh-cn/reference/ai_clothes/v4.0","items":[{"label":"执行 AI 时装虚拟试穿 V4（V4） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","routeSlug":"/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4/post","metadata":{"seo":{"title":"执行 AI 时装虚拟试穿 V4（V4） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/cloth-v4"},{"label":"查询 AI 时装虚拟试穿 V4（V4） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_clothes/v4.0/paths/~1s2s~1v2.0~1task~1cloth-v4~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 时装虚拟试穿 V4（V4） 任务的状态。","description":"查询 AI 时装虚拟试穿 V4（V4） 任务的状态。"}},"httpPath":"/s2s/v2.0/task/cloth-v4/{task_id}"}]},{"type":"group","label":"V3.0","link":"/zh-cn/reference/ai_clothes/v3.0","routeSlug":"/zh-cn/reference/ai_clothes/v3.0","items":[{"label":"执行 AI 时装虚拟试穿 V3（V3） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","routeSlug":"/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3/post","metadata":{"seo":{"title":"执行 AI 时装虚拟试穿 V3（V3） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/cloth-v3"},{"label":"查询 AI 时装虚拟试穿 V3（V3） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_clothes/v3.0/paths/~1s2s~1v2.0~1task~1cloth-v3~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 时装虚拟试穿 V3（V3） 任务的状态。","description":"查询 AI 时装虚拟试穿 V3（V3） 任务的状态。"}},"httpPath":"/s2s/v2.0/task/cloth-v3/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_clothes/v2.0","routeSlug":"/zh-cn/reference/ai_clothes/v2.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","routeSlug":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1template~1cloth/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/cloth"},{"label":"执行 AI 时装虚拟试穿 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","routeSlug":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth/post","metadata":{"seo":{"title":"执行 AI 时装虚拟试穿 任务。","description":"本接口用于发起 AI 时装虚拟试穿流程。您可以使用模板 ID，或提供参考图（源文件与参考文件）。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/cloth"},{"label":"查询 AI 时装虚拟试穿 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_clothes/v2.0/paths/~1s2s~1v2.0~1task~1cloth~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 时装虚拟试穿 任务的状态。","description":"查询 AI 时装虚拟试穿 任务的状态。"}},"httpPath":"/s2s/v2.0/task/cloth/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 时装虚拟试穿","version":"","description":"# 概览\nAI 时装虚拟试穿是一间虚拟试衣间，不用真穿就能试遍各种衣服。它借助 AI 与图片编辑技术，把服装叠合到您的照片上，让您看清不同风格、不同版型穿在自己身形上的样子。网购、找穿搭灵感，或纯粹玩一玩时尚点子，都很合适。用 AI 时装虚拟试穿体验虚拟试穿。上传任意服装参考图，与您的照片互换穿搭，瞬间换一整套行头。\n\n---\n\n## 接入指南\n\n* API Playground\n您可以用 API Playground 测试 AI 时装虚拟试穿的虚拟试穿功能，边试边熟悉试穿流程，理解会更透彻。\n\nAPI Playground 地址：\n<https://yce.makeupar.com/api-console/en/api-playground/ai-clothes/>\n\n---\n\n* AI 时装虚拟试穿接口使用指引\n\n本指引说明如何上传图片、准备参考服装，以及创建虚拟试穿任务。\n\n***\n\n   * 第 1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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\": \"full_body_photo_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您可以：\n\n*   用 File 接口（`/s2s/v2.0/file`）上传服装图片，或\n*   提供一个有效的图片 URL。\n\n**支持的服装图片：**\n\n*   服装的商品图。\n*   真人全身照，作为穿搭参考。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 第 5 步：创建 AI 任务\n\n用 **AI 任务接口**（`/s2s/v2.0/task/cloth-v4`）创建虚拟试穿任务。\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.0/task/cloth-v4 \\\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/clothes_03_cccd5d4803.jpeg\",\n    \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/clothes_reference_full_body_01_5a000d999f.png\",\n    \"garment_category\": \"full_body\"\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.0/task/cloth-v4/<YOUR_TASK_ID> \\\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![](https://plugins-media.makeupar.com/smb/blog/post/2025-05-08/b80f4ae1-c905-4ec0-b491-e42c15e65575.gif)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/01%20ai%20clothes%20changer.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-12-01/45f451aa-4b4f-466d-9da7-4538573c92af.jpg)\n\n拍摄建议：\n![拍摄建议](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png \"Suggestions for How to Shoot\")\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ---- | ---- | ---- | ---- |\n|目标用户图片|建议 1024×768，最小 512×384，最长边 4096 px。</br></br> - 仅支持单人。</br> - 为达到最佳效果，人物应占据画面至少 80%。</br> - 图片只需包含上半身，从胸部往上即可。腹部不必露出，但肩膀须可见。</br> - 脸部必须完整可见，不得被遮挡。</br> - 身体须正对镜头、站姿（不要坐着或蹲着）。 |< 10MB|jpg/png|\n|服装参考图片 |建议 1024×768，最小 512×384，最长边 4096 px。</br></br> - 使用真人服装照作为参考时</br>&nbsp;&nbsp;&nbsp;- 只能有一位人物。</br>&nbsp;&nbsp;&nbsp;- 可见的服装区域必须完整覆盖要试穿的部位。</br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 举例：全身试穿时，不能拿半身服装图来用。</br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 举例：下半身试穿时，不能只用裤子的一部分。</br>&nbsp;&nbsp;&nbsp;- 服装不得被严重遮挡（例如被长发或手臂盖住）。</br>&nbsp;&nbsp;&nbsp;- 脸部必须完整可见，不得被遮挡。</br>&nbsp;&nbsp;&nbsp;- 身体须正对镜头、站姿（不要坐着或蹲着）。 </br></br> - 使用商品图作为参考时</br>&nbsp;&nbsp;&nbsp;- 必须是单件服装的正面商品图。</br>&nbsp;&nbsp;&nbsp;- 不要使用合成图（例如一张图里同时有上衣和下装）。</br>&nbsp;&nbsp;&nbsp;- 下半身只支持实际穿着的服装，不支持单件商品图。|< 10MB|jpg/png|\n\n* 错误码\n\n* 错误码（预处理）\n\n| 错误码 | 说明 |\n| ---------- | ----------- |\n| exceed_max_filesize | 源图或参考图过大。长边不得超过 4096 像素。 |\n| error_below_min_image_size | 源图或参考图过小。长边不得小于 128 像素。 |\n| error_pose | 无法从上传的人物源图中检测出姿态。 |\n| error_invalid_ref | 参考图无效，例如图片为空，或主体未完整呈现。 |\n| error_apply_region_mismatch | 源图中的套用区域与参考图不匹配，无法套用任何修改。 |\n| error_invalid_src | 源图只有下半身或只有脚部时。 |\n\n* 错误码（引擎）\n\n| 错误码 | 说明 |\n| ---------- | ----------- |\n| invalid_parameter | - 服装类别无效。 <br> - Style_id 不在 inference_style_list 中。 <br> - src_keys、dst_keys 或 acts 无效。 <br> - ref_keys 或 template_ref_image 无效。 <br> - 上述参数必须且只能提供一个。 |\n| error_download_image | 源图或参考图下载失败。 |\n| exceed_max_filesize | 源图或参考图过大。文件大小不得超过 10 MB。 |\n| error_nsfw_content_detected | 在结果图中检测到疑似不适宜内容（NSFW）。 |\n| error_editing_failed | 编辑失败：结果图与原图过于相似。 |\n| unknown_internal_error | - 模型加载失败。 <br> - 调度算法类型无效。 <br> - 未加载引擎。 <br> - 文件不在上传结果中。 |\n| error_multi_person | 在\"normal\"或\"strict\"多人过滤设置下，系统在源图或参考图中检测到多人。 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 时装虚拟试穿 V2.0 | 2 |\n| AI 时装虚拟试穿 V3.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_hat.yaml","link":"/zh-cn/reference/ai_hat","routeSlug":"/zh-cn/reference/ai_hat","label":"AI 帽子虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_hat/section/概览","routeSlug":"/zh-cn/reference/ai_hat/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_hat/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_hat/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_hat/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_hat/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_hat/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_hat/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_hat/v2.0","routeSlug":"/zh-cn/reference/ai_hat/v2.0","items":[{"label":"执行 AI 帽子虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat/post","routeSlug":"/zh-cn/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat/post","metadata":{"seo":{"title":"执行 AI 帽子虚拟试戴 任务。","description":"本接口用于发起 AI 帽子虚拟试戴流程。您需要提供源文件、参考文件（URL 或 ID），并指定性别与风格参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/hat"},{"label":"查询 AI 帽子虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_hat/v2.0/paths/~1s2s~1v2.0~1task~1hat~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 帽子虚拟试戴 任务的状态。","description":"查询 AI 帽子虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/hat/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 帽子虚拟试戴","version":"","description":"# 概览\n用我们的头部饰品超写实 AR 试戴，一步踏进时尚新未来；这套方案由前沿 AI 技术驱动。这项创新做法把网购变成沉浸式体验，顾客虚拟试戴帽子的精准度与真实感前所未有。\n从即时发现风格，到真如眼前的呈现，我们的 AR 技术让每顶帽子、每条发带都看着真、戴着像。帮顾客在下单前找到最合头型与风格的款式。互动更高、信心更足，顾客与您商品的互动方式就此改写。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/hat`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试戴的目标。\n    1.  **准备帽子图片：** 上传帽子商品图，或一位佩戴帽子的人物照片。\n    1.  **选择风格与性别：** 挑选您偏好的风格，以及您想呈现的性别。\n    1.  **发起 AI 任务并取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n---\n\n* AI 帽子接口使用指引\n\n本指引说明如何上传图片、准备参考帽子，以及创建虚拟试戴任务。\n\n***\n\n   * 第 1 步：准备自拍照\n\n您可以：\n*   用 File 接口（`/s2s/v2.0/file`）上传自拍照，或\n*   提供一个有效的图片 URL。\n\n     * 第 1.1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 第 1.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\": \"selfie_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     * 第 1.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 @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 第 2 步：准备参考帽子图片\n\n您可以：\n\n*   用 File 接口（`/s2s/v2.0/file`）上传帽子图片，或\n*   提供一个有效的图片 URL。\n\n**支持的帽子图片：**\n\n*   帽子商品图。\n*   一位佩戴帽子的人物照片。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 第 3 步：创建 AI 任务\n\n挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/hat`）创建虚拟试戴任务。\n\n**参数：**\n\n*   用户图片：`src_file_id` 或 `src_file_url`。\n*   帽子图片：`ref_file_id` 或 `ref_file_url`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\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   * 第 4 步：轮询任务结果\n\n用任务 ID 查看状态：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/hat/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 第 5 步：取回结果\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* AI 帽子虚拟试戴规格\n\n   * 图片要求\n\n| 类型   | 最低分辨率 | 说明 |\n| ------ | ------------------ | ----- |\n| 自拍照 | 512 × 512 | 脸部可见，建议拍到头到胸 |\n| 帽子  | 512 × 512（商品图）<br>800 × 800（实拍照） | 帽子画面清楚、无遮挡 |\n\n**支持的帽子图片**\n\n* 商品图要求\n    * 最低分辨率：512 × 512 像素\n    * 每张图片只放一件商品\n    * 商品应占图片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/026_thumb_dca334af3c.jpg)\n\n* 实拍照要求\n    * 最低分辨率：800 × 800 像素\n    * 单件要求：模特只能穿戴一件商品，不允许多件或加配饰。\n    * 占比要求：所穿戴商品须占整张图片高度的 20% 以上，确保它在画面中清楚、突出。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/010_thumb_51490eebeb.jpg)\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 建议脸部占比：超过图片高度的 15%。\n* 单一主体要求：图片只能有一位真人主体，不允许出现其他人物或局部人体。\n* 脸部可见：主体的脸部必须完整可见、无遮挡。头发、配饰或物体不得盖住关键面部特征。\n* 构图：画面至少包含头像照，收录从头顶到胸口的区域；半身照（头到腰）更佳，分析效果最好。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**试戴风格**\n\n* 生成虚拟试戴结果有五种预设风格：\"style_sporty_casual\" \"style_urban_fashion\" \"style_vacation_casual\" \"style_warm_cozy\" 与 \"style_bohemian\"。创建 AI 任务时可指定该风格参数；不指定时，系统默认随机挑选。\n\n![style_vacation_casual](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/5f42385b_6aef_44cd_b576_2ec10e31305d_824cc2019b.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n|  ----  | ----  | ----  | ----  |\n| AI 帽子虚拟试戴 | 输入：长边 <= 4096 <br>输出：896 x 1152 | < 10MB | jpg/jpeg/png/heic |\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 源图或参考图下载失败 |\n| error\\_inference               | 推理流程出错                     |\n| error\\_no\\_face                | 源图中未检测到人脸             |\n| error\\_nsfw\\_content\\_detected | 在结果中检测到不适宜内容（NSFW） |\n| exceed\\_max\\_filesize          | 文件大小超过 10 MB                      |\n| invalid\\_parameter             | 性别或风格取值无效                |\n| unknown\\_internal\\_error       | 其他内部错误                        |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jquery >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 帽子虚拟试戴 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_scarf.yaml","link":"/zh-cn/reference/ai_scarf","routeSlug":"/zh-cn/reference/ai_scarf","label":"AI 围巾虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_scarf/section/概览","routeSlug":"/zh-cn/reference/ai_scarf/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_scarf/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_scarf/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_scarf/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_scarf/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_scarf/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_scarf/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_scarf/v2.0","routeSlug":"/zh-cn/reference/ai_scarf/v2.0","items":[{"label":"执行 AI 围巾虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","routeSlug":"/zh-cn/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf/post","metadata":{"seo":{"title":"执行 AI 围巾虚拟试戴 任务。","description":"本接口用于发起 AI 围巾虚拟试戴流程。您需要提供源文件、参考文件（URL 或 ID），并指定性别与风格参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/scarf"},{"label":"查询 AI 围巾虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_scarf/v2.0/paths/~1s2s~1v2.0~1task~1scarf~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 围巾虚拟试戴 任务的状态。","description":"查询 AI 围巾虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/scarf/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 围巾虚拟试戴","version":"","description":"# 概览\n用线上 AR AI 围巾虚拟试戴，把时尚体验再往上抬一档。顾客可以瞬间把围巾搭到身上的穿搭里，看花纹在真实画面里怎么垂坠流动。\n这套互动式虚拟围巾功能让顾客在线试遍各种风格与颜色，把到店体验搬到线上。依托高保真的 AR 模拟，用户随时随地都能享受细腻到位的围巾呈现。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/scarf`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试戴的目标。\n    1.  **准备围巾图片：** 上传围巾商品图，或提供一位佩戴围巾、清楚可见且无遮挡的人物图片的有效 URL。\n    1.  **选择风格与性别：** 挑选您偏好的风格，以及您想呈现的性别。\n    1.  **发起 AI 任务并取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n---\n\n* AI 围巾接口使用指引\n\n本指引说明如何上传图片、准备参考围巾，以及创建虚拟试戴任务。\n\n***\n\n   * 第 1 步：准备自拍照\n\n您可以：\n*   用 File 接口（`/s2s/v2.0/file`）上传自拍照，或\n*   提供一个有效的图片 URL。\n\n     * 第 1.1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 第 1.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\": \"selfie_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     * 第 1.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 @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 第 2 步：准备参考围巾图片\n\n您可以：\n\n*   用 File 接口（`/s2s/v2.0/file`）上传围巾图片，或\n*   提供一个有效的图片 URL。\n\n**支持的围巾图片：**\n\n*   围巾的商品图。\n*   一位无遮挡佩戴围巾的人物图片，作为围巾参考。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 第 3 步：创建 AI 任务\n\n挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/scarf`）创建虚拟试戴任务。\n\n**参数：**\n\n*   用户图片：`src_file_id` 或 `src_file_url`。\n*   围巾图片：`ref_file_id` 或 `ref_file_url`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\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   * 第 4 步：轮询任务结果\n\n用任务 ID 查看状态：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/scarf/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 第 5 步：取回结果\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* AI 围巾虚拟试戴规格\n\n   * 图片要求\n\n| 类型   | 最低分辨率 | 说明 |\n| ------ | ------------------ | ----- |\n| 自拍照 | 512 × 512 | 脸部可见，建议拍到头到胸 |\n| 围巾  | 512 × 512（商品图）<br>800 × 800（实拍照） | 围巾画面清楚、无遮挡 |\n\n**支持的围巾图片**\n\n* 商品图要求\n    * 最低分辨率：512 × 512 像素\n    * 每张图片只放一件商品\n    * 商品应占图片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/021_thumb_e356d121b3.jpg)\n\n* 实拍照要求\n    * 最低分辨率：800 × 800 像素\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/008_thumb_5dd8b1be93.jpg)\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 建议脸部占比：超过图片高度的 15%。\n* 图片必须清楚呈现单一真人主体，脸部完整可见，画面至少包含从头顶到胸口的头像照，半身照更佳。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**试戴风格**\n\n* 生成虚拟试戴结果有五种预设风格：\"style_french_elegance\"、\"style_light_luxury\"、\"style_cottagecore\"、\"style_modern_chic\" 与 \"style_bohemian\"。创建 AI 任务时可指定该风格参数；不指定时，系统默认随机挑选。\n\n![style_french_elegance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/3d88ad75_41ca_4bf8_b81d_f52adf5db263_4a06b3e174.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 围巾虚拟试戴|输入：长边 <= 4096 <br>输出：896 x 1152 |< 10MB|jpg/jpeg/png/heic|\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 源图或参考图下载失败 |\n| error\\_inference               | 推理流程出错                     |\n| error\\_no\\_face                | 源图中未检测到人脸             |\n| error\\_nsfw\\_content\\_detected | 在结果中检测到不适宜内容（NSFW） |\n| exceed\\_max\\_filesize          | 文件大小超过 10 MB                      |\n| invalid\\_parameter             | 性别或风格取值无效                |\n| unknown\\_internal\\_error       | 其他内部错误                        |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jquery >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 围巾虚拟试戴 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_bag.yaml","link":"/zh-cn/reference/ai_bag","routeSlug":"/zh-cn/reference/ai_bag","label":"AI 包虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_bag/section/概览","routeSlug":"/zh-cn/reference/ai_bag/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_bag/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_bag/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_bag/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_bag/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_bag/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_bag/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_bag/v2.0","routeSlug":"/zh-cn/reference/ai_bag/v2.0","items":[{"label":"执行 AI 包虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","routeSlug":"/zh-cn/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag/post","metadata":{"seo":{"title":"执行 AI 包虚拟试戴 任务。","description":"本接口用于发起 AI 包虚拟试戴流程。您需要提供源文件、参考文件（URL 或 ID），并指定性别与风格参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/bag"},{"label":"查询 AI 包虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_bag/v2.0/paths/~1s2s~1v2.0~1task~1bag~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 包虚拟试戴 任务的状态。","description":"查询 AI 包虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/bag/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 包虚拟试戴","version":"","description":"# 概览\nAR 让精品包的选购变得实实在在！AR 技术让品牌以极致的真实感呈现手袋：从肩带长度到包款搭配，顾客通过相机就能即刻看到上身效果。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/bag`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试背的目标。\n    1.  **准备包图片：** 上传包商品图，或提供一位无遮挡的拎包人物图片的有效 URL。\n    1.  **选择风格与性别：** 挑选您偏好的风格，以及您想呈现的性别。\n    1.  **发起 AI 任务并取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n---\n\n* AI 包接口使用指引\n\n本指引说明如何上传图片、准备参考包，以及创建虚拟试背任务。\n\n***\n\n   * 第 1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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_photo_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\": \"selfie_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 @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 第 4 步：准备参考包图片\n\n您可以：\n\n*   用 File 接口（`/s2s/v2.0/file`）上传包图片，或\n*   提供一个有效的图片 URL。\n\n**支持的包图片：**\n\n*   包的商品图。\n*   一位无遮挡的拎包人物图片，作为包参考。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 第 5 步：创建 AI 任务\n\n挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/bag`）创建虚拟试背任务。\n\n**参数：**\n\n*   用户图片：`src_file_id` 或 `src_file_url`。\n*   包图片：`ref_file_id` 或 `ref_file_url`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\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.0/task/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\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* AI 包虚拟试戴规格\n\n**支持的包图片**\n\n* 商品图要求\n    * 最低分辨率：512 × 512 像素\n    * 每张图片只放一件商品\n    * 商品应占图片高度的 25% 以上\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/040_thumb_c5f4d2af8e.jpg)\n\n* 实拍照要求\n    * 最低分辨率：800 × 800 像素\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/003_thumb_c73b207cae.jpg)\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 建议脸部占比：超过图片高度的 15%。\n* 图片必须清楚呈现单一真人主体，脸部完整可见，画面至少包含从头顶到胸口的头像照，半身照更佳。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/lashana_lynch_thumb_7a900b811e.jpg)\n\n**试背风格**\n\n* 生成虚拟试背结果有四种预设风格：\"style_parisian_chic\"、\"style_urban_chic\"、\"style_mediterranean_chic\" 与 \"style_art_deco_style\"。创建 AI 任务时可指定该风格参数；不指定时，系统默认随机挑选。\n\n![style_parisian_chic](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/fca6a904_b13a_4c90_bc52_d9200a473c70_4d994afa3e.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 包虚拟试戴|输入：长边 <= 4096 <br>输出：1104 x 1472 |< 10MB|jpg/jpeg/png/heic|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_image | 下载 srcKeys/refKeys 出错 |\n| error_inference            | 推理流程出错 |\n| error_no_face              | 源图中未检测到人脸 |\n| error_nsfw_content_detected| 在结果图中检测到不适宜内容（NSFW） |\n| exceed_max_filesize        | 输入文件大小超出上限（10 MB） |\n| invalid_parameter          | 性别选项取值无效 <br>风格选项取值无效 |\n| unknown_internal_error     | 其他 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 包虚拟试戴 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_shoes.yaml","link":"/zh-cn/reference/ai_shoes","routeSlug":"/zh-cn/reference/ai_shoes","label":"AI 鞋子虚拟试穿","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_shoes/section/概览","routeSlug":"/zh-cn/reference/ai_shoes/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_shoes/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_shoes/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_shoes/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_shoes/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_shoes/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_shoes/section/概览/点数消耗"}]},{"type":"group","label":"V3.0","link":"/zh-cn/reference/ai_shoes/v3.0","routeSlug":"/zh-cn/reference/ai_shoes/v3.0","items":[{"label":"执行 AI 鞋子虚拟试穿（V3.0） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer/post","routeSlug":"/zh-cn/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer/post","metadata":{"seo":{"title":"执行 AI 鞋子虚拟试穿（V3.0） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/shoes-transfer"},{"label":"查询 AI 鞋子虚拟试穿（V3.0） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_shoes/v3.0/paths/~1s2s~1v2.0~1task~1shoes-transfer~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 鞋子虚拟试穿（V3.0） 任务的状态。","description":"查询 AI 鞋子虚拟试穿（V3.0） 任务的状态。"}},"httpPath":"/s2s/v2.0/task/shoes-transfer/{task_id}"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_shoes/v2.0","routeSlug":"/zh-cn/reference/ai_shoes/v2.0","items":[{"label":"执行 AI 鞋子虚拟试穿 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","routeSlug":"/zh-cn/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes/post","metadata":{"seo":{"title":"执行 AI 鞋子虚拟试穿 任务。","description":"本接口用于发起 AI 鞋子虚拟试穿流程。您需要提供源文件、参考文件（URL 或 ID），并指定性别与风格参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/shoes"},{"label":"查询 AI 鞋子虚拟试穿 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_shoes/v2.0/paths/~1s2s~1v2.0~1task~1shoes~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 鞋子虚拟试穿 任务的状态。","description":"查询 AI 鞋子虚拟试穿 任务的状态。"}},"httpPath":"/s2s/v2.0/task/shoes/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 鞋子虚拟试穿","version":"","description":"# 概览\n用我们的 AI 鞋子虚拟试穿，一步踏进购物新未来。在屏幕上立刻看到您钟意的款式上身是什么样子、合不合脚。这套体验由前沿 AI 技术驱动，视觉贴合度精准到位，帮您买得有底气、退货更少。\n足不出户，试遍无穷款式与颜色。高保真的 AR 模拟把每个细节演活，让您随时随地享受到店挑鞋的那份爽感。现在就试，找到那双最衬您风格的鞋。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/shoes-transfer`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍照：** 上传您自己的图片或提供有效图片 URL，作为虚拟试穿的目标。\n    1.  **准备鞋子图片：** 上传鞋子商品图，或一位穿着鞋子的人物照片。\n    1.  **选择风格与性别：** 挑选您偏好的风格，以及您想呈现的性别。\n    1.  **发起 AI 任务并取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n---\n\n* AI 鞋子接口使用指引\n\n本指引说明如何上传图片、准备参考鞋子，以及创建虚拟试穿任务。\n\n***\n\n   * 第 1 步：准备自拍照\n\n您可以：\n*   用 File 接口（`/s2s/v2.0/file`）上传自拍照，或\n*   提供一个有效的图片 URL。\n\n     * 第 1.1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n***\n\n     * 第 1.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\": \"selfie_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     * 第 1.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 @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n   * 第 2 步：准备参考鞋子图片\n\n您可以：\n\n*   用 File 接口（`/s2s/v2.0/file`）上传鞋子图片，或\n*   提供一个有效的图片 URL。\n\n**支持的鞋子图片：**\n\n*   鞋子商品图。\n*   一位穿着鞋子的人物照片。\n\n详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n   * 第 3 步：创建 AI 任务\n\n挑选您偏好的风格与想呈现的性别。\n用 **AI 任务接口**（`/s2s/v2.0/task/shoes-transfer`）创建虚拟试穿任务。\n\n**参数：**\n\n*   用户图片：`src_file_id` 或 `src_file_url`。\n*   鞋子图片：`ref_file_id` 或 `ref_file_url`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes-transfer \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"src_file_url\": \"https://example.com/selfie.jpg\",\n    \"ref_file_url\": \"https://example.com/accessory.jpg\",\n    \"gender\": \"female\",\n    \"style\": \"random\"\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   * 第 4 步：轮询任务结果\n\n用任务 ID 查看状态：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/shoes-transfer/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 第 5 步：取回结果\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* AI 鞋子虚拟试穿规格\n\n   * 图片要求\n\n| 类型   | 最低分辨率 | 说明 |\n| ------ | ------------------ | ----- |\n| 自拍照 | 512 × 512 | 脚部可见，建议全身照 |\n| 鞋子  | 512 × 512（商品图）<br>800 × 800（实拍照） | 鞋子画面清楚、无遮挡 |\n\n**支持的鞋子图片**\n\n* 商品图要求\n    * 最低分辨率：512 × 512 像素\n    * 每张图片只放一件商品\n    * 商品应占图片高度的 25% 以上\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_3_428e8dddb1.jpg)\n\n* 实拍照要求\n    * 最低分辨率：800 × 800 像素\n    * 单件要求：模特只能穿一件商品，不允许多件或加配饰。\n    * 占比要求：所穿商品须占整张图片高度的 20% 以上，确保它在画面中清楚、突出。\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_2_ec3578c5c2.jpg)\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_Shoes_9_52a61e0935.jpg)\n\n\n**支持的自拍视角**\n\n* 建议图片分辨率：至少 512 × 512 像素。\n* 单一主体要求：图片只能有一位真人主体，不允许出现其他人物或局部人体。\n* 脚部可见：主体的脚部必须完整可见、无遮挡。\n\n![](https://plugins-media.makeupar.com/strapi/assets/small_clothes_04_441e848298.png)\n\n---\n\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n|  ----  | ----  | ----  | ----  |\n| AI 鞋子虚拟试穿 | 输入：长边 <= 4096 <br>输出：1008 x 1344 | < 10MB | jpg/jpeg/png/heic |\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------------------ | -------------------------------------------- |\n| error\\_download\\_image         | 源图或参考图下载失败 |\n| error\\_inference               | 推理流程出错                     |\n| error\\_no\\_face                | 源图中未检测到人脸             |\n| error\\_nsfw\\_content\\_detected | 在结果中检测到不适宜内容（NSFW） |\n| exceed\\_max\\_filesize          | 文件大小超过 10 MB                      |\n| invalid\\_parameter             | 性别或风格取值无效                |\n| unknown\\_internal\\_error       | 其他内部错误                        |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jquery >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 鞋子虚拟试穿 V2.0 | 2 |\n| AI 鞋子虚拟试穿 V3.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_fabric.yaml","link":"/zh-cn/reference/ai_fabric","routeSlug":"/zh-cn/reference/ai_fabric","label":"AI 面料虚拟试穿","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_fabric/section/概览","routeSlug":"/zh-cn/reference/ai_fabric/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_fabric/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_fabric/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_fabric/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_fabric/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_fabric/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_fabric/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_fabric/v1.0","routeSlug":"/zh-cn/reference/ai_fabric/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","routeSlug":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1template~1fabric/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/fabric"},{"label":"执行 AI 面料虚拟试穿 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","routeSlug":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric/post","metadata":{"seo":{"title":"执行 AI 面料虚拟试穿 任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/fabric"},{"label":"查询 AI 面料虚拟试穿 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_fabric/v1.0/paths/~1s2s~1v2.0~1task~1fabric~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 面料虚拟试穿 任务的状态。","description":"查询 AI 面料虚拟试穿 任务的状态。"}},"httpPath":"/s2s/v2.0/task/fabric/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 面料虚拟试穿","version":"","description":"# 概览\n逼真效果，换一身造型！用图片模式试遍各种独特的面料风格——无论是丝滑质感的高雅，还是大胆花色的鲜亮，AI 面料接口都能把材质演活。开发者可以打造出沉浸式的体验，让用户以前所未有的方式看到、感受到面料。而且，新面料还会持续上新！\n\n---\n\n## 接入指南\n\n* AI 面料接口使用指引\n\n本指引说明如何上传图片、取得预设面料样式，以及用 AI 面料接口创建虚拟试穿任务。\n\n***\n\n   * 第 1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。\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\": \"full_body_photo_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用 **模板接口**（`/s2s/v2.0/task/template/fabric`）取得预设面料模板列表：\n\n```bash\ncurl --request GET \\\n    --url 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/fabric?page_size=20&starting_token=73a3c9e69b89' \\\n    --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n***\n\n   * 第 5 步：创建 AI 任务\n\n用 **AI 任务接口**（`/s2s/v2.0/task/fabric`）创建虚拟试穿任务。\n\n**参数：**\n\n*   用户图片：`src_file_id` 或 `src_file_url`。\n*   面料样式：`template_id`。\n\n**请求示例：**\n\n```bash\ncurl --request POST \\\n    --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric \\\n    --header 'Authorization: Bearer YOUR_API_KEY' \\\n    --header 'content-type: application/json' \\\n    --data '{\n    \"template_id\":\"good_template_001\",\n    \"src_file_url\":\"https://example.com/selfie.jpg\"\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.0/task/fabric/<YOUR_TASK_ID> \\\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/strapi/assets/AI%20Fabric.png)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-05-07/b103976d-1b0e-4bed-aab4-9307308b84d7.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/03%20ai%20clothes%20changer.jpg)\n\n拍摄建议：\n![拍摄建议](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png \"Suggestions for How to Shoot\")\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 面料|长边 <= 4096，仅支持单人。腹部、脸部、肩部都须可见，脸部不得被遮挡。身体应保持站立直立、正对镜头，不要坐着、蹲着等非常规姿态。|< 10MB|jpg/jpeg|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_apply_region_not_detected|服装区域太小，或在输入图中未被检测到\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 面料虚拟试穿 V1.0 | 2 |\n\n---\n"}},{"type":"separator","label":"珠宝与腕表","labelTranslationKey":"sidebar.reference.separators.jewelryWatches"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ring_vto.yaml","link":"/zh-cn/reference/ring_vto","routeSlug":"/zh-cn/reference/ring_vto","label":"AI 戒指虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ring_vto/section/概览","routeSlug":"/zh-cn/reference/ring_vto/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ring_vto/section/概览/接入指南","routeSlug":"/zh-cn/reference/ring_vto/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ring_vto/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ring_vto/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ring_vto/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ring_vto/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ring_vto/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ring_vto/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ring_vto/v1.0","routeSlug":"/zh-cn/reference/ring_vto/v1.0","items":[{"label":"创建新文件。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","routeSlug":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post","metadata":{"seo":{"title":"创建新文件。","description":"上传新文件要先调用 File API。它会给您一个 URL， 用这个 URL 把文件传上去。上传完成后，就可以用同一次响应里的 file_id 开始使用我们的 AI 功能。"}},"httpPath":"/s2s/v2.0/file/2d-vto/ring"},{"label":"执行 AI 戒指虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","routeSlug":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post","metadata":{"seo":{"title":"执行 AI 戒指虚拟试戴 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/2d-vto/ring"},{"label":"查询 AI 戒指虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","routeSlug":"/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 戒指虚拟试戴 任务的状态。","description":"查询 AI 戒指虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/ring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 戒指虚拟试戴","version":"","description":"# 概览\nAR 戒指、求婚钻戒试戴，轻松做。您只要上传图片就行。采用 2D 图片即可轻松获得高质量的虚拟试戴体验，几乎不费力气。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/2d-vto/ring`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备手部图片：** 上传一张手部图片，或提供有效的手部图片 URL\n    1.  **准备戒指图片：** 上传一张戒指商品图片，或提供有效的商品图片 URL\n    1.  **发起 AI 任务并获取 Task ID：** 从响应中取到 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查询任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方在线调试台交互式地体验与测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-virtual-try-on/)\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* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。\n\n您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张戒指商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。\n\nAI 引擎支持自动去除戒指商品图的背景。您也可以为手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或戒指商品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮挡蒙版图，用于微调分割效果。\n\n---\n\n* 2. 创建 AI 戒指虚拟试戴任务并轮询结果\n\n图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/2d-vto/ring\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/2d-vto/ring/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 戒指虚拟试戴规格\n\n**支持的戒指图视角**\n戒指图需采用斜前方视角（约 45 度）。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg)\n\n**支持的手部图视角**\n手背需完整可见，五根手指清晰可辨，且无任何遮挡。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg)\n\n**ring\\_wearing\\_finger: integer（0–4）**\n指定戒指戴在哪根手指上：\n0 = 拇指\n1 = 食指\n2 = 中指\n3 = 无名指\n4 = 小指\n\n**ring\\_wearing\\_location: float（0.0–1.0）**\n表示沿手指的佩戴位置：\n0.0 = 靠近 MCP 关节（大指节）\n1.0 = 靠近 PIP 关节（中指节）\n\n![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg)\n\n**ring\\_shadow\\_intensity: float（0.0–1.0）**\n控制阴影强度：\n0.0 = 无阴影\n1.0 = 最大阴影\n默认值：0.15\n\n**ring\\_ambient\\_light\\_intensity: float（0.0–1.0）**\n定义光线在多大程度上参考目标手部图：\n0.0 = 忽略手部图的光线\n1.0 = 完全匹配手部图的光线与阴影渲染\n默认值：1.0\n\n**ring\\_anchor\\_point: 像素坐标下由两个点组成的数组（可选）**\n标出戒指内缘与手指接触处的左右两个点。戒圈较宽或较厚时尤其好用。\n不提供该参数时，AI 引擎会自动检测锚点。\n\n![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg)\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 戒指虚拟试戴|长边 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 戒指虚拟试戴 V1.0 | 单件佩戴 1 点数 <br> 叠戴 2 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_bracelet.yaml","link":"/zh-cn/reference/ai_bracelet","routeSlug":"/zh-cn/reference/ai_bracelet","label":"AI 手链虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_bracelet/section/概览","routeSlug":"/zh-cn/reference/ai_bracelet/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_bracelet/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_bracelet/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_bracelet/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_bracelet/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_bracelet/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_bracelet/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_bracelet/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_bracelet/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_bracelet/v1.0","routeSlug":"/zh-cn/reference/ai_bracelet/v1.0","items":[{"label":"执行 AI 手链虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","routeSlug":"/zh-cn/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet/post","metadata":{"seo":{"title":"执行 AI 手链虚拟试戴 任务。","description":"本接口用于发起 AI 手链虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐与阴影的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet"},{"label":"查询 AI 手链虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_bracelet/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1bracelet~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 手链虚拟试戴 任务的状态。","description":"查询 AI 手链虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/bracelet/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 手链虚拟试戴","version":"","description":"# 概览\nAI 手链虚拟试戴，行业顶级方案\n用 AI 方案帮顾客在线买得准、买得满意，每一次都合适。只需一张 2D 图片。\n\n用逼真到位的 AI 手链虚拟试戴打造有吸引力的购物流程，各种规模的珠宝品牌都能用。采用 2D 图片即可轻松获得高质量的虚拟试戴体验，几乎不费力气。这项独特能力让我们在电商领域独树一帜，让体验您的商品变得前所未有地简单。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/2d-vto/bracelet`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备手腕图片：** 上传一张手腕图片，或提供有效的手腕图片 URL\n    1.  **准备手链图片：** 上传一张手链商品图片，或提供有效的商品图片 URL\n    1.  **发起 AI 任务并获取 Task ID：** 从响应中取到 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查询任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方在线调试台交互式地体验与测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-bracelet-virtual-try-on/)\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* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。\n\n您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张手链商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。\n\nAI 引擎支持自动去除手链商品图的背景。您也可以为手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或手链商品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮挡蒙版图，用于微调分割效果。\n\n---\n\n* 2. 创建 AI 手链虚拟试戴任务并轮询结果\n\n图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/2d-vto/bracelet\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/2d-vto/bracelet/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 手链虚拟试戴规格\n\n**支持的手链图视角**\n手链图需采用斜前方视角（约 45 度）。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_product_09_2cb9721d77_2f8d90ab9f.jpg)\n\n**支持的手腕图视角**\n手腕背面需完整可见，五根手指清晰可辨，且无任何遮挡。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**bracelet\\_wearing\\_location: float（−0.3 到 1.0）**\n表示沿手腕的佩戴位置：\n−0.3 表示靠近手腕主关节\n1.0 表示远离手腕主关节\n默认值：null（使用引擎默认值）\n\n![bracelet_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**bracelet\\_shadow\\_intensity: float（0.0 到 1.0）**\n控制阴影强度：\n0.0 表示无阴影\n1.0 表示最大阴影\n默认值：0.15\n\n**bracelet\\_ambient\\_light\\_intensity: float（0.0 到 1.0）**\n定义光线在多大程度上参考目标手部图：\n0.0 忽略手部图的光线\n1.0 完全匹配手部图的光线与阴影渲染\n默认值：1.0\n\n**手链锚点：像素坐标下的 2 个点组成的数组（可选）**\n标出手链内缘与手腕接触处的左右两个点。\n不提供该参数时，AI 引擎会自动检测锚点。\n![bracelet_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_anchor_point_c353245edc.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 手链虚拟试戴|长边 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 手链虚拟试戴 V1.0 | 单件佩戴 1 点数 <br> 叠戴 2 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_watch.yaml","link":"/zh-cn/reference/ai_watch","routeSlug":"/zh-cn/reference/ai_watch","label":"AI 手表虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_watch/section/概览","routeSlug":"/zh-cn/reference/ai_watch/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_watch/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_watch/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_watch/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_watch/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_watch/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_watch/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_watch/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_watch/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_watch/v1.0","routeSlug":"/zh-cn/reference/ai_watch/v1.0","items":[{"label":"执行 AI 手表虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","routeSlug":"/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch/post","metadata":{"seo":{"title":"执行 AI 手表虚拟试戴 任务。","description":"本接口用于发起 AI 手表虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐、阴影与佩戴位置的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/watch"},{"label":"查询 AI 手表虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_watch/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1watch~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 手表虚拟试戴 任务的状态。","description":"查询 AI 手表虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/watch/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 手表虚拟试戴","version":"","description":"# 概览\nAR 腕表虚拟试戴，轻松上手！只需一张 2D 图片。\n\n用户只要上传一张 2D 图片，就能通过我们创新的 AR 腕表应用即刻虚拟试戴高端腕表。这项独特能力让我们在电商领域独树一帜，让体验您的商品变得前所未有地简单。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/2d-vto/watch`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备手腕图片：** 上传一张手腕图片，或提供有效的手腕图片 URL\n    1.  **准备手表图片：** 上传一张手表商品图片，或提供有效的商品图片 URL\n    1.  **发起 AI 任务并获取 Task ID：** 从响应中取到 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查询任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方在线调试台交互式地体验与测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/)\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* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。\n\n您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张手表商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。\n\nAI 引擎支持自动去除手表商品图的背景。您也可以为手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或手表商品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮挡蒙版图，用于微调分割效果。\n\n---\n\n* 2. 创建 AI 手表虚拟试戴任务并轮询结果\n\n图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/2d-vto/watch\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/2d-vto/watch/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 手表虚拟试戴规格\n\n**支持的手表图视角**\n\n手表图需为正面清晰视角，表盘无遮挡；表带请裁剪到接近真实佩戴时的长度。\n    * 手表必须立着、正对镜头——平放（水平放置）会得到错误结果。\n    * 图中不得出现表带背面（例如表扣），只能看到正面的表带。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg)\n\n***\n\n**支持的手腕图视角**\n\n手腕背面需完整可见，五根手指清晰可辨，且无任何遮挡。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\n**watch\\_wearing\\_location: float（−0.3 到 1.0）**\n表示沿手腕的佩戴位置：\n−0.3 表示靠近手腕主关节\n1.0 表示远离手腕主关节\n默认值：null（使用引擎默认值）\n\n![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\n**watch\\_shadow\\_intensity: float（0.0 到 1.0）**\n控制阴影强度：\n0.0 表示无阴影\n1.0 表示最大阴影\n默认值：0.15\n\n**watch\\_ambient\\_light\\_intensity: float（0.0 到 1.0）**\n定义光线在多大程度上参考目标手部图：\n0.0 忽略手部图的光线\n1.0 完全匹配手部图的光线与阴影渲染\n默认值：1.0\n\n**手表锚点：像素坐标下由 4 个点组成的数组（可选）**\n前两个点标出佩戴时表带的起点与终点。\n另外两个点标出表壳的上缘与下缘。\n\n![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 手表虚拟试戴|长边 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 手表虚拟试戴 V1.0 | 单件佩戴 1 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_earrings.yaml","link":"/zh-cn/reference/ai_earrings","routeSlug":"/zh-cn/reference/ai_earrings","label":"AI 耳环虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_earrings/section/概览","routeSlug":"/zh-cn/reference/ai_earrings/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_earrings/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_earrings/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_earrings/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_earrings/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_earrings/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_earrings/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_earrings/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_earrings/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_earrings/v1.0","routeSlug":"/zh-cn/reference/ai_earrings/v1.0","items":[{"label":"执行 AI 耳环虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","routeSlug":"/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post","metadata":{"seo":{"title":"执行 AI 耳环虚拟试戴 任务。","description":"本接口用于发起 AI 耳环虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐、阴影与佩戴位置的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/earring"},{"label":"查询 AI 耳环虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 耳环虚拟试戴 任务的状态。","description":"查询 AI 耳环虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/earring/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 耳环虚拟试戴","version":"","description":"# 概览\nAI 耳环虚拟试戴，行业顶级方案\n领先的 AI 虚拟穿耳与耳环试戴模拟方案\n\n用一张 2D 图片就能做出真实灵动的 AI 耳环虚拟试戴，不必花钱做 3D 建模。我们的先进算法能生成栩栩如生的试戴效果，光影细腻、动态符合物理规律。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/2d-vto/earring`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍图片：** 上传一张图片，或提供有效的图片 URL\n    2.  **准备耳环图片：** 上传一张耳环商品图片，或提供有效的商品图片 URL\n    3.  **发起 AI 任务并获取 Task ID：** 从响应中取到 `task_id`。\n    4.  **轮询状态（`GET`）：** 用 `task_id` 查询任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方在线调试台交互式地体验与测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/)\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* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。\n\n您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张耳环商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。\n\nAI 引擎支持自动去除耳环商品图的背景。您也可以为手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或耳环商品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮挡蒙版图，用于微调分割效果。\n\n---\n\n* 2. 创建 AI 耳环虚拟试戴任务并轮询结果\n\n图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/2d-vto/earring\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/2d-vto/earring/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 耳环虚拟试戴规格\n\n**支持的耳环参考图**\n* 单只耳环的正面图，画面清楚、无遮挡。\n*   所有参数（包括锚点、蒙版、位置等）**仅**在参考图为**单只耳环**佩戴状态时生效。\n*   若试戴参考图中是**两只耳环**，全部参数都将采用**自动检测与默认设置**。\n*   **双耳**同时试戴时，以较清晰的那只耳朵为源，另一侧由镜像生成。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg)\n\n**支持的自拍图视角**\n\n*   AI 耳环虚拟试戴支持正脸图片，但侧脸图片的效果最好。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png)\n\n**earring\\_wearing\\_location: 长度为 2 的整数数组**\n指定在自拍图中要佩戴耳环的位置。\n默认值：null（使用引擎默认值）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg)\n\n**earring\\_scale: 大于 0 的数值**\n按厘米控制耳环大小。\n默认值：null（使用引擎默认值）\n\n**earring\\_is\\_right\\_ear: boolean**\n表示耳环是否戴在右耳，默认戴在右耳。\n默认值：true\n\n**earring\\_occluded\\_type: number（枚举：0、1、2）**\n指定遮挡类型：\n0 为自动检测\n1 为有遮挡\n2 为无遮挡\n默认值：0\n\n**earring\\_shadow\\_intensity: float（0.0 到 1.0）**\n控制阴影强度：\n0.0 表示无阴影\n1.0 表示最大阴影\n默认值：0.15\n\n**earring\\_ambient\\_light\\_intensity: float（0.0 到 1.0）**\n定义光线在多大程度上参考自拍图：\n0.0 忽略自拍图的光线\n1.0 完全匹配自拍图的光线与阴影渲染\n默认值：1.0\n\n**earring\\_anchor\\_point: 像素坐标下 1 个点组成的数组（可选）**\n指定在耳环商品图中的佩戴位置。\n默认值：null（使用引擎默认值）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg)\n\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 耳环虚拟试戴|长边 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |\n| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 耳环虚拟试戴 V1.0 | 单件佩戴 1 点数 <br> 叠戴 2 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_necklace.yaml","link":"/zh-cn/reference/ai_necklace","routeSlug":"/zh-cn/reference/ai_necklace","label":"AI 项链虚拟试戴","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_necklace/section/概览","routeSlug":"/zh-cn/reference/ai_necklace/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_necklace/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_necklace/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_necklace/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_necklace/section/概览/文件规格与错误码"},{"type":"link","label":"JS Camera Kit","link":"/zh-cn/reference/ai_necklace/section/概览/js-camera-kit","routeSlug":"/zh-cn/reference/ai_necklace/section/概览/js-camera-kit"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_necklace/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_necklace/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_necklace/v1.0","routeSlug":"/zh-cn/reference/ai_necklace/v1.0","items":[{"label":"执行 AI 项链虚拟试戴 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","routeSlug":"/zh-cn/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post","metadata":{"seo":{"title":"执行 AI 项链虚拟试戴 任务。","description":"本接口用于发起 AI 项链虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐、阴影与佩戴位置的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace"},{"label":"查询 AI 项链虚拟试戴 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 项链虚拟试戴 任务的状态。","description":"查询 AI 项链虚拟试戴 任务的状态。"}},"httpPath":"/s2s/v2.0/task/2d-vto/necklace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 项链虚拟试戴","version":"","description":"# 概览\n顶尖虚拟试戴，尽显项链的高级质感\n精准的 AI 颈部与锁骨追踪，带来超真实的 AR 试戴体验，把线下试戴项链的高级质感还原到位。\n\n用一张 2D 图片就能做出真实灵动的 AI 项链虚拟试戴，不必花钱做 3D 建模。我们的先进算法能生成栩栩如生的试戴效果，光影细腻、动态符合物理规律。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/2d-vto/necklace`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer YOUR_API_KEY`\n*   **流程：**\n    1.  **准备自拍图片：** 上传一张图片，或提供有效的图片 URL\n    2.  **准备项链图片：** 上传一张项链商品图片，或提供有效的商品图片 URL\n    3.  **发起 AI 任务并获取 Task ID：** 从响应中取到 `task_id`。\n    4.  **轮询状态（`GET`）：** 用 `task_id` 查询任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方在线调试台交互式地体验与测试接口：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-necklace-virtual-try-on/)\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* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。\n\n您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张项链商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。\n\nAI 引擎支持自动去除自拍图的背景。您也可以为颈部（`srcmsk_file_id` 或 `srcmsk_file_url`）提供遮挡蒙版图，用于微调分割效果。\n\n---\n\n* 2. 创建 AI 项链虚拟试戴任务并轮询结果\n\n图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/2d-vto/necklace\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/2d-vto/necklace/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI 项链虚拟试戴规格\n\n**支持的项链图视角**\n项链图需为佩戴状态的正面图，并去除背景。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg)\n\n**支持的自拍图视角**\n正脸自拍，颈部清晰可见、无遮挡。头部水平旋转角度支持 20 度以内。头部比例要协调，颈部宽度至少占图片宽度的 15%。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png)\n\n**necklace\\_wearing\\_location: 由两个点组成的数组（可选）**\n指定在照片中要佩戴项链的目标位置。\n默认值：null（使用引擎默认值）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg)\n\n**necklace\\_shadow\\_intensity: float（0.0 到 1.0）**\n控制阴影强度：\n0.0 表示无阴影\n1.0 表示最大阴影\n默认值：0.15\n\n**necklace\\_ambient\\_light\\_intensity: float（0.0 到 1.0）**\n定义光线在多大程度上参考自拍图：\n0.0 忽略自拍图的光线\n1.0 完全匹配自拍图的光线与阴影渲染\n默认值：1.0\n\n**necklace\\_anchor\\_point: 像素坐标下由两个点组成的数组（可选）**\n指定商品图中项链链条左右两端可见处的锚点，用于对齐。\n默认值：null（使用引擎默认值）\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 项链虚拟试戴|长边 <= 4096 |< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| RUNTIME_ERROR | 运行时发生未知错误 |\n| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到颈部 |\n| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |\n| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |\n| INPUT_ERROR | 输入文件格式有误 |\n| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 项链虚拟试戴 V1.0 | 单件佩戴 1 点数 |\n\n---\n"}},{"type":"separator","label":"图像","labelTranslationKey":"sidebar.reference.separators.image"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_face_swap.yaml","link":"/zh-cn/reference/ai_face_swap","routeSlug":"/zh-cn/reference/ai_face_swap","label":"AI 换脸","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_face_swap/section/概览","routeSlug":"/zh-cn/reference/ai_face_swap/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_face_swap/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_face_swap/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_face_swap/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_face_swap/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_face_swap/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_face_swap/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_face_swap/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_face_swap/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_face_swap/v1.0","routeSlug":"/zh-cn/reference/ai_face_swap/v1.0","items":[{"label":"执行 AI 换脸人脸检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","routeSlug":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post","metadata":{"seo":{"title":"执行 AI 换脸人脸检测任务。","description":"当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 index 取值、您的应用也不需要手动挑选目标，这一步可以省略。"}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process"},{"label":"查询 AI 换脸人脸检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 换脸人脸检测任务的状态。","description":"查询 AI 换脸人脸检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-swap/pre-process/{task_id}"},{"label":"执行 AI 换脸 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","routeSlug":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post","metadata":{"seo":{"title":"执行 AI 换脸 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/face-swap"},{"label":"查询 AI 换脸 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 换脸 任务的状态。","description":"查询 AI 换脸 任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-swap/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 换脸","version":"","description":"# 概览\n用 AI 视频换脸做出逼真到位的效果，并支持多人脸。我们的人脸换脸人工智能支持一次换一张或多张脸。不管是想做搞怪换脸图，还是需要一套专业工具，我们都能满足。\n\n## 接入指南\n* 如何实现 AI 换脸\n\n   * 第 1 步：上传源图与参考图\n\n      1. 向接口请求上传 URL：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. 响应会给出一个预签名的**上传 URL** 和一个 `file_id`。\n        2. 用 HTTP PUT 请求把文件上传到该 URL。\n        3. 保存 `file_id` 备用。**目标图**与**参考图**都要重复这一套流程。\n\n      2. 把实际文件上传到**上传 URL**。\n\n---\n\n   * 第 2 步：预处理源图与参考图（人脸检测）\n\n        1. 创建预处理任务：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. 接口返回一个 `task_id`。\n        2. 在此接口轮询任务状态：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID\n        ```\n        1. 处理完成后，您会收到一份带边界框的检测到的人脸列表。\n\n---\n\n   * 第 3 步：执行换脸任务\n        1. 指定哪些参考图的脸去替换源图中的哪张脸\n        `face_mapping` 数组定义了**源图**中的人脸如何被**参考图列表**中的人脸替换，作用相当于把源图中检测到的人脸与指定参考图串起来的关联表。\n\n        * 结构\n\n            数组中的每个元素是一个包含两个属性的对象：\n\n            | 参数 | 类型 | 说明 |\n            | :--- | :--- | :--- |\n            | `position` | `integer` | **源图**中检测到的人脸下标（例如 0、1、2）。 |\n            | `index` | `integer` | **参考图列表**中要与之互换的人脸图片下标。 |\n\n                * 逻辑规则\n            1.  **下标映射：** `index` 直接对应您在参考图列表中提供的图片顺序。\n                *   `0`：第一张参考图。\n                *   `1`：第二张参考图。\n            2.  **跳过互换：** 要跳过源图中某张检测到的人脸，把 `index` 与 `position` 都设为 `-1`。\n            3.  **数组顺序：** 数组中各对象的排列顺序需与 `position` 对应。\n\n                * 使用示例\n\n            **场景：**\n            *   **参考图列表：** 提供 2 张图片（Image A、Image B）。\n            *   **源图：** 检测到 3 张脸（Face 0、Face 1、Face 2）。\n\n            **目标：**\n            *   把 **Face 0**（源图）与 **Image 1**（参考图）互换。\n            *   跳过 **Face 1**（源图）。\n            *   把 **Face 2**（源图）与 **Image 0**（参考图）互换。\n\n            **配置：**\n\n            ```json\n            \"face_mapping\": [\n                {\n                    \"index\": 1,  // Use the second reference image\n                    \"position\": 0 // Apply to the first detected face in source\n                },\n                {\n                    \"index\": -1, // Skip swapping\n                    \"position\": -1 // Skip swapping\n                },\n                {\n                    \"index\": 0,  // Use the first reference image\n                    \"position\": 2 // Apply to the third detected face in source\n                }\n            ]\n            ```\n\n        1. 发送主任务请求：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"request_id\": 2,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"],\n                \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\": [\n                {\n                \"id\": 0,\n                \"params\": {\n                    \"face_mapping\": [\n                    { \"index\": 0, \"position\": 0 },\n                    { \"index\": -1, \"position\": -1 }\n                    ]\n                }\n                }\n            ]\n            }\n        }\n        ```\n        1. 响应返回一个 `task_id`。\n\n---\n\n   * 第 4 步：轮询任务状态并取回结果\n        需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。\n        1. 在此接口轮询：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID\n        ```\n        2. 当 `status` 为 `success` 时，响应中包含生成图片的 URL。\n        3. 从该 URL 下载或展示图片。\n\n---\n\n   * 第 5 步：接入您的平台\n\n        * 在**网页前端**，可以直接用 JavaScript 的 fetch 或 Axios 实现。\n        * 在**后端**（Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。\n        * 任务是异步执行的，请实现重试与错误处理。\n\n---\n\n    * 排障指引\n        1. **Invalid TaskId 报错**\n            </br>**原因：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，发起 AI 任务之后，需要在 polling_interval 内持续轮询其状态，直到状态变为 success 或 error。\n            </br>**解决办法：** 为避免任务失效，需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。\n\n        2. **为什么源图里有些脸没被检测到**\n            </br>**原因：** 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大\n            </br>**解决办法：** 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡\n\n---\n\n## 输入与输出\n\n* 实际案例：\n多人换脸示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg)\n\n单人脸换脸示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg)\n\n* 拍摄建议：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 换脸|输入与输出：长边不得超过 4096 像素|< 10MB|jpg/jpeg/png|\n\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------ | ----------- |\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_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\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| error_multiple_people | 人数超出上限 |\n| error_no_shoulder | 源图中看不到肩部 |\n| error_large_face_angle | 上传图片中的脸部角度过大 |\n| error_unsupport_ratio | 输入图片的宽高比不受支持 |\n| unknown_internal_error | 其他内部错误 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 换脸 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_image_extender.yaml","link":"/zh-cn/reference/ai_image_extender","routeSlug":"/zh-cn/reference/ai_image_extender","label":"AI 图片扩展","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_image_extender/section/概览","routeSlug":"/zh-cn/reference/ai_image_extender/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_image_extender/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_image_extender/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_image_extender/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_image_extender/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_image_extender/v2.0","routeSlug":"/zh-cn/reference/ai_image_extender/v2.0","items":[{"label":"执行 AI 图片扩展 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","routeSlug":"/zh-cn/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint/post","metadata":{"seo":{"title":"执行 AI 图片扩展 任务。","description":"查询任务状态请参见轮询指南。本接口需要 3 个关键参数：输入图片、锚点、输出图片。"}},"httpPath":"/s2s/v2.0/task/out-paint"},{"label":"查询 AI 图片扩展 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_image_extender/v2.0/paths/~1s2s~1v2.0~1task~1out-paint~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片扩展 任务的状态。","description":"查询 AI 图片扩展 任务的状态。"}},"httpPath":"/s2s/v2.0/task/out-paint/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 图片扩展","version":"","description":"# 概览\n用尖端的 AI 图片扩展体验出色的画面延展。任意比例都能无损扩展，配合先进 AI 技术，让创意彻底放开。扩图同时保住最高画质，风格与美感都不打折。这款好用的 AI 工具支持一键自动扩展背景，照片即刻换貌。多亏先进的上下文感知技术，每位观者都能看到连贯入画的画面。\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_03_cf19a018d9.jpg \"AI Image Extender\")\n\n不管是为了发 Instagram，还是想裱起来当数码作品，都有多种尺寸与比例供您挑选。您尽管调、尽管改，AI 会在旁边无缝收尾，保证扩展出来的区域与原图严丝合缝。\n\n![AI Image Extender](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_outpainting_S1_img_01_1876fb85a5.jpg \"AI Image Extender\")\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 图片扩展 | 长边 <= 4096 | < 10MB | jpg/jpeg |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 图片扩展 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_object_removal_pro.yaml","link":"/zh-cn/reference/ai_object_removal_pro","routeSlug":"/zh-cn/reference/ai_object_removal_pro","label":"AI 物件移除","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_object_removal_pro/section/概览","routeSlug":"/zh-cn/reference/ai_object_removal_pro/section/概览","items":[{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_object_removal_pro/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_object_removal_pro/section/概览/点数消耗"}]},{"type":"group","label":"V4.0","link":"/zh-cn/reference/ai_object_removal_pro/v4.0","routeSlug":"/zh-cn/reference/ai_object_removal_pro/v4.0","items":[{"label":"执行 AI 物件移除 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","routeSlug":"/zh-cn/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill/post","metadata":{"seo":{"title":"执行 AI 物件移除 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/generative-fill"},{"label":"查询 AI 物件移除 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_object_removal_pro/v4.0/paths/~1s2s~1v2.0~1task~1generative-fill~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 物件移除 任务的状态。","description":"查询 AI 物件移除 任务的状态。"}},"httpPath":"/s2s/v2.0/task/generative-fill/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 物件移除","version":"","description":"# 概览\n用我们先进的 AI 物件移除（专业版）体验无痕修图。\n去除路人、反光、阴影等多余元素，同时把每一处细节都完整保留。\n上传照片，再配一张简单的灰度蒙版，就能得到干净自然的成果，让视觉内容更上一层。\n\n使用示例：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/YCE_web_relayout_sign_in_index_Object_Removal_b93ad75683.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2026-02-26/webp_6b27a29f-eab0-4205-a69d-d001fffd12ea.jpg)\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 物件移除 | 标准模式 1 点数 <br> 专业模式 2 点数 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_photo_enhance.yaml","link":"/zh-cn/reference/ai_photo_enhance","routeSlug":"/zh-cn/reference/ai_photo_enhance","label":"AI 照片优化","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_photo_enhance/section/概览","routeSlug":"/zh-cn/reference/ai_photo_enhance/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_photo_enhance/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_photo_enhance/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_photo_enhance/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_photo_enhance/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_photo_enhance/v1.0","routeSlug":"/zh-cn/reference/ai_photo_enhance/v1.0","items":[{"label":"执行 AI 照片优化 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","routeSlug":"/zh-cn/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance/post","metadata":{"seo":{"title":"执行 AI 照片优化 任务。","description":"本接口用于发起 AI 照片优化流程。您需要提供上传文件接口返回的文件 ID。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/enhance"},{"label":"查询 AI 照片优化 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_photo_enhance/v1.0/paths/~1s2s~1v2.0~1task~1enhance~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照片优化 任务的状态。","description":"查询 AI 照片优化 任务的状态。"}},"httpPath":"/s2s/v2.0/task/enhance/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片优化","version":"","description":"# 概览\nAI 照片优化借助先进 AI 与深度学习分析画面细节、提升分辨率，把低分辨率照片变清晰，也能修掉运动模糊。\n * 告别颗粒感：消除马赛克，画面更顺、更清楚。\n * 修复糊照：去掉虚焦，细节更锐利利落。\n * 提升画质：挖出更精细的细节，画面每一处都立得住。\n * 增强锐度：提高清晰度，画面更通透鲜活。\n * 改善通透度：整体清晰度上台阶，照片看着清爽又专业。\n * 人像增强：细化五官，让动态影像里的人像更真实、更精神。\n\n调整前示例：\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_1_0779bbdbdb.jpg \"AI Photo Enhance\")\n\n调整后示例：\n![AI Photo Enhance](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s5_poster_2_a2e15250ef.jpg \"AI Photo Enhance\")\n\n\n调整前示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_1_4cd6425807.jpg)\n\n调整后示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_s2_poster_2_7674281362.jpg)\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片优化 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 照片优化 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_background_removal.yaml","link":"/zh-cn/reference/ai_background_removal","routeSlug":"/zh-cn/reference/ai_background_removal","label":"AI 照片背景消除","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_background_removal/section/概览","routeSlug":"/zh-cn/reference/ai_background_removal/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_background_removal/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_background_removal/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_background_removal/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_background_removal/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_background_removal/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_background_removal/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_background_removal/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_background_removal/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_background_removal/v1.0","routeSlug":"/zh-cn/reference/ai_background_removal/v1.0","items":[{"label":"执行 AI 照片背景消除 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","routeSlug":"/zh-cn/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post","metadata":{"seo":{"title":"执行 AI 照片背景消除 任务。","description":"本接口用于发起抠图流程。您需要提供上传文件接口返回的文件 ID。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/sod"},{"label":"查询 AI 照片背景消除 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照片背景消除 任务的状态。","description":"查询 AI 照片背景消除 任务的状态。"}},"httpPath":"/s2s/v2.0/task/sod/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片背景消除","version":"","description":"# 概览\n去除图片背景，抠得干净利落，画质也保得住。\n* 自动识别背景：：用 AI 把主体与背景分离开来。\n* 边缘处理精细：：主体四周的边缘干净精准。\n* 支持多种类别：人物、商品、动物、汽车、图形等。\n* 便于串联其他 AI 任务：输出的文件 ID 转眼就能接进其他 AI 任务。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg)\n\n## 接入指南\n* AI 图片去背景怎么做\n1. **调整源图尺寸**</br>\n  把图片缩放到支持的尺寸范围，详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**\n\n2. **用 File 接口上传文件**</br>\n  通过 ***/s2s/v2.0/file*** 接口上传目标用户图片。\n    - 图片要求\n      - 详见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。\n    - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。<br>\n    调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。\n    \n      > **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。\n\n3. **执行 AI 任务**</br>\n  上传完成后，用文件 ID 调用 POST 'task/sod' 执行 AI 任务，并取得用于监控的 ***task_id***。\n\n4. **用 Webhook 或轮询监控任务状态，直到成功或报错**</BR>\n用这个 ***task_id*** 配置 Webhook 或实现轮询，在整个保留期内监控任务状态。AI 引擎完成任务之前，状态会一直是 running，这一阶段不消耗点数。处理完成后，任务状态会变为 success 或 error。\n\n1. **任务成功后取回结果**</BR>\n引擎成功处理您的输入文件、生成出图后，任务状态会变为 'success'。您会得到处理后图片的 URL 以及一个 dst_id，可直接串联下一个 AI 任务，不必把结果图重新上传。\n只有这种情况才会消耗点数。若引擎处理失败，任务状态会变为 'error'，不消耗点数。</BR>\n扣除点数时，系统优先扣除临近到期的点数；到期日相同时，优先扣除最早取得的点数。\n\n* 应用场景示例：\n常见实现方式：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg)\n\n## 输入与输出\n* 输入\n   * `Image`\n- **类型：** `image`\n- **说明：** 前景清楚的图片。\n\n实际应用场景（输入）： \n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png)\n\n---\n\n* 输出\n   * `Foreground image`\n- **类型：** `image`\n- **说明：** 已去除背景的图片。\n\n实际应用场景（输出）：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png)\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 图片去背景|输入与输出图片的建议与限制如下：</br>分辨率：4096 × 4096 像素（最长边不得超过 4096 像素）|<10MB|JPG 与 PNG|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\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_download_video|下载源视频出错|\n|error_decode_video|解码源视频出错|\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|error_multiple_people|源图中检测到多人|\n|error_no_shoulder|源图中看不到肩膀|\n|error_large_face_angle|上传图片中的脸部角度过大|\n|error_hair_too_short|输入的头发太短|\n|error_unexpected_video_duration|视频时长与 dstDuration 不一致|\n|error_bald_image|输入的发型为光头|\n|error_unsupport_ratio|输入图片的宽高比不受支持|\n|unknown_internal_error|其他|\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 图片去背景 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_photo_colorize.yaml","link":"/zh-cn/reference/ai_photo_colorize","routeSlug":"/zh-cn/reference/ai_photo_colorize","label":"AI 照片智能上色","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_photo_colorize/section/概览","routeSlug":"/zh-cn/reference/ai_photo_colorize/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_photo_colorize/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_photo_colorize/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_photo_colorize/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_photo_colorize/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_photo_colorize/v1.0","routeSlug":"/zh-cn/reference/ai_photo_colorize/v1.0","items":[{"label":"执行 AI 照片智能上色 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","routeSlug":"/zh-cn/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize/post","metadata":{"seo":{"title":"执行 AI 照片智能上色 任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/colorize"},{"label":"查询 AI 照片智能上色 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_photo_colorize/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照片智能上色 任务的状态。","description":"查询 AI 照片智能上色 任务的状态。"}},"httpPath":"/s2s/v2.0/task/colorize/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片智能上色","version":"","description":"# 概览\n用最新 AI 技术为黑白照片做 AI 照片智能上色，也能顺手修复。AI 照片智能上色可即刻生成 4 个不同的上色版本，从暖调到冷调各不相同。借助深度学习技术，几秒钟就能把黑白照片变成鲜活的彩色影像。\n\n![AI Photo Colorize](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_colorize_s4_poster_11c0bdfead.jpg \"AI Photo Colorize\")\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片智能上色 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 照片智能上色 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_photo_lighting.yaml","link":"/zh-cn/reference/ai_photo_lighting","routeSlug":"/zh-cn/reference/ai_photo_lighting","label":"AI 照片打光","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_photo_lighting/section/概览","routeSlug":"/zh-cn/reference/ai_photo_lighting/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_photo_lighting/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_photo_lighting/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_photo_lighting/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_photo_lighting/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_photo_lighting/v2.0","routeSlug":"/zh-cn/reference/ai_photo_lighting/v2.0","items":[{"label":"执行 AI 照片打光 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","routeSlug":"/zh-cn/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting/post","metadata":{"seo":{"title":"执行 AI 照片打光 任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/lighting"},{"label":"查询 AI 照片打光 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_photo_lighting/v2.0/paths/~1s2s~1v2.0~1task~1lighting~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照片打光 任务的状态。","description":"查询 AI 照片打光 任务的状态。"}},"httpPath":"/s2s/v2.0/task/lighting/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片打光","version":"","description":"# 概览\n用我们的 AI 图片提亮工具，轻松把图片提亮。凭这套成熟的 AI 技术，任何图片都能提亮。\n用 AI 照片打光给偏暗的照片提亮，转瞬之间就找回记忆里的亮度。\n\n调整前\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_1_b7d976b686.jpg)\n调整后\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v3_poster_2_79d3be33bc.jpg)\n用 AI 工具轻松提亮暗光照片，细节看得清，色彩也更鲜亮。\n\n\n\n调整前\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_1_2422530612.jpg)\n调整后\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_lighting_v6_poster_2_63f1ecc244.jpg)\n用 AI 补光提亮商品图，呈现更抓人、更出彩。\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 照片打光 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 照片打光 V2.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_color_correction.yaml","link":"/zh-cn/reference/ai_color_correction","routeSlug":"/zh-cn/reference/ai_color_correction","label":"AI 颜色校正","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_color_correction/section/概览","routeSlug":"/zh-cn/reference/ai_color_correction/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_color_correction/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_color_correction/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_color_correction/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_color_correction/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_color_correction/v1.0","routeSlug":"/zh-cn/reference/ai_color_correction/v1.0","items":[{"label":"执行 AI 颜色校正 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","routeSlug":"/zh-cn/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct/post","metadata":{"seo":{"title":"执行 AI 颜色校正 任务。","description":"查询任务状态的方法，请参见轮询指南。"}},"httpPath":"/s2s/v2.0/task/colorize/color-correct"},{"label":"查询 AI 颜色校正 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_color_correction/v1.0/paths/~1s2s~1v2.0~1task~1colorize~1color-correct~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 颜色校正 任务的状态。","description":"查询 AI 颜色校正 任务的状态。"}},"httpPath":"/s2s/v2.0/task/colorize/color-correct/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 颜色校正","version":"","description":"# 概览\nAI 颜色校正自动帮您调好照片的饱和度、色温与色相，省心省力。校正白平衡以修正色温，提升饱和度让画面更鲜活，校正曝光以平衡亮度，去除偏色与色罩，把肤色修得更自然，强化暗部与高光细节，降噪并提升清晰度，还能一键套用创意调色。AI 颜色校正能在几秒内生成 4 个不同的调色版本，从暖调到冷调各不相同。\n\n示例\n调整前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_before_dt_100_45429e8625.jpg)\n\n调整后：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_topbanner_after_dt_100_ef9f9c48ed.jpg)\n\n\n\n调整前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_before_dt_fa73b5d41a.jpg)\n\n调整后\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/color_correction_s1_image_after_dt_a3e88a101b.jpg)\n\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 颜色校正 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 颜色校正 V1.0 | 2 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_photo_background_change.yaml","link":"/zh-cn/reference/ai_photo_background_change","routeSlug":"/zh-cn/reference/ai_photo_background_change","label":"AI 照片背景更换","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_photo_background_change/section/概览","routeSlug":"/zh-cn/reference/ai_photo_background_change/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_photo_background_change/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_photo_background_change/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_photo_background_change/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_photo_background_change/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_photo_background_change/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_photo_background_change/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_photo_background_change/v2.0","routeSlug":"/zh-cn/reference/ai_photo_background_change/v2.0","items":[{"label":"列出预置的 AI 照片背景更换 V2 模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","routeSlug":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1template~1bg-replace/get","metadata":{"seo":{"title":"列出预置的 AI 照片背景更换 V2 模板。","description":"列出预置的 AI 照片背景更换 V2 模板。"}},"httpPath":"/s2s/v2.0/task/template/bg-replace"},{"label":"执行 AI 照片背景更换 V2（V2） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","routeSlug":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace/post","metadata":{"seo":{"title":"执行 AI 照片背景更换 V2（V2） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/bg-replace"},{"label":"查询 AI 照片背景更换 V2（V2） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照片背景更换 V2（V2） 任务的状态。","description":"查询 AI 照片背景更换 V2（V2） 任务的状态。"}},"httpPath":"/s2s/v2.0/task/bg-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片背景更换","version":"","description":"# 概览\nAI 图片换背景接口会先把主体从原背景中分离出来，再对图片做增强，可广泛用于电商商品图等商用场景。\n\n这个接口支持用自定义提示词或预设模板来替换背景。\n\n**使用示例**\n\n调整前：\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)\n\n调整后：\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)\n\n\n调整前：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)\n\n调整后：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)\n\n---\n\n## 接入指南\n\n**1. 上传图片**\n\n通过以下接口取得上传 URL 与文件 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n用返回的 URL 把图片上传上去。\n也可以提供您自有存储上可公开访问的图片 URL。\n\n\n**2. 准备背景描述提示词，或挑选背景模板。**\n\n```\nGET /s2s/v2.0/task/template/bg-replace\n```\n\n取得预设背景模板列表，用其中的 template_id 选定一个。使用 prompt（默认方式）时，背景依据您给的提示词生成；使用 template 时，背景由 template_id 指定的预设模板生成，prompt 参数将被忽略。\n\n\n**3. 执行分析任务**\n\n```\nPOST /s2s/v2.0/task/bg-replace\n```\n\n用文件 ID 或图片 URL 作为输入，连同您要的背景提示词一起提交任务。\n响应会返回一个 task_id，用于追踪并取回结果。\n\n\n**4. 取回任务结果**\n\n```\nGET /s2s/v2.0/task/bg-replace/{task_id}\n```\n\n用任务 ID 追踪状态并取得结果。\n\n可配置 [Webhooks](/develop/webhook.md)，在任务完成（状态为 success 或 error）时接收异步通知。也支持轮询：反复调用任务接口，直到状态从 running 变为 success 或 error。\n\n只有任务成功完成才计费。\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 图片换背景 | 长边不超过 4096 像素。 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| size_mismatch_on_input_image_and_mask | 输入图片的尺寸必须与输入蒙版图片的宽高一致。 |\n| invalid_parameter | 参数取值无效。请求参数缺失、格式有误，或包含不支持的取值。|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 图片换背景 V2.0 | 4 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_photo_background_blur.yaml","link":"/zh-cn/reference/ai_photo_background_blur","routeSlug":"/zh-cn/reference/ai_photo_background_blur","label":"AI 照片背景虚化","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_photo_background_blur/section/概览","routeSlug":"/zh-cn/reference/ai_photo_background_blur/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_photo_background_blur/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_photo_background_blur/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_photo_background_blur/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_photo_background_blur/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_photo_background_blur/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_photo_background_blur/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_photo_background_blur/v2.0","routeSlug":"/zh-cn/reference/ai_photo_background_blur/v2.0","items":[{"label":"执行 背景虚化 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","routeSlug":"/zh-cn/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post","metadata":{"seo":{"title":"执行 背景虚化 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/bg-blur"},{"label":"查询 背景虚化 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1{task_id}/get","metadata":{"seo":{"title":"查询 背景虚化 任务的状态。","description":"查询 背景虚化 任务的状态。"}},"httpPath":"/s2s/v2.0/task/bg-blur/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照片背景虚化","version":"","description":"# 概览\n背景虚化（焦外）是摄影里很常用的一种手法：把背景虚下去，让主体更突出。照片加一点这种效果更有艺术味，看着更专业、更抓人眼球。\n\n用 AI 图片背景虚化接口就能做出专业观感的照片：它自动把主体分离出来，套上自然的背景虚化，把视线引到最该看的地方。\n\n\n**使用场景示例：**\n\n* 人像美化\n套上自然的焦外虚化，让人物更突出，头像照、人像照的画质观感更好。\n\n    调整前：\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)\n\n    调整后：\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)\n\n* 专业形象照\n用普通照片做出照相馆级的背景虚化效果，适合商务头像、企业员工名录。\n\n    调整前：\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)\n\n    调整后：\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)\n\n---\n\n## 接入指南\n\n**输入要求与处理条件：**\n\n- 上传一张前景主体清楚、突出的图片。\n- 图片长边不得超过 **4,096 px**。\n- 源文件大小须小于 **10 MB**。\n- 至少需要一个清晰可见的前景主体。\n- 只支持单人分析。画面中有多人时，接口会自动选取可见面积最大的那位主体。\n\n\n**流程：**\n\n1. 调用 File 接口。\n2. 从响应中取得签名的上传 URL。\n3. 把实际图片上传到该 URL。\n4. 创建 AI 任务。\n5. 配置 Webhook，或轮询任务状态直到完成。\n6. 处理成功后下载生成的结果图片。\n\n---\n\n**第 1 步 — 用 File 接口上传文件元数据**\n\n用 `POST /s2s/v2.0/file` 建立文件记录，取得源图的上传信息。\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\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n**File 接口响应示例：**\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**第 2 步 — 取得 File 接口响应内容**\n\n响应包含：\n\n| 字段 | 说明 |\n| --- | --- |\n| `file_id` | 用于创建 AI 任务的标识。 |\n| `requests.url` | 上传实际图片文件的签名 URL。 |\n| `requests.method` | 上传方式，通常为 `PUT`。 |\n| `requests.headers` | 上传请求所需的请求头。 |\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 步 — 创建 AI 任务**\n\n用 `POST /s2s/v2.0/task/bg-blur` 创建 AI 任务。\n\n| 参数 | 说明 | 示例 |\n| --- | --- | --- |\n| `src_file_id` | File 接口上传流程返回的文件 ID。走上传文件流程时必填。 | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | 源图的直接 URL。可作为 `src_file_id` 的替代方案。 | `\"https://example.com/selfie.jpg\"` |\n| `intensity` | 模糊强度。0 表示不模糊，100 表示最大模糊。 | 50 |\n\n**请求示例：**\n\n```javascript\nconst resp = await fetch(\n  'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: 'Bearer <YOUR_TOKEN_HERE>'\n    },\n    body: JSON.stringify({\n      src_file_url: 'https://example.com/selfie.jpg',\n      intensity: 50\n    })\n  }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI 任务接口响应：**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n---\n\n**第 5 步 — 配置 Webhook 或轮询任务结果**\n\n配置与验证细节见 [Webhook 接入指南](/develop/webhook.md)。\n\n若走轮询，请用返回的 `task_id` 查看任务状态。\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n**第 6 步 — 取回结果图片**\n\n处理成功时，响应会在 `data.results.url` 中给出下载 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\n**API 密钥无效的响应：**\n\n访问令牌无效时，接口返回 `401` 响应。\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## 文件规格与错误码\n\n**文件规格：**\n\n| 规格项 | 要求 |\n| --- | --- |\n| 图片类型 | 图片需包含一位清楚、突出的前景主体或人物。 |\n| 长边分辨率上限 | 长边不得超过 **4096 px**。 |\n| 文件大小上限 | 须小于 **10 MB**。 |\n| 支持格式 | `jpg`、`png`。 |\n\n**错误码：**\n\n| 错误码 | 说明 |\n| --- | --- |\n| `exceed_max_filesize` | 源图超出允许的尺寸或文件大小上限。长边不得超过 4096 px，文件大小须保持在 10 MB 以下。 |\n| `error_nsfw_content_detected` | 在源图或生成的结果图中检测到疑似不适宜内容（NSFW）。 |\n| `invalid_parameter` | 源键、目标键、动作、模式取值、强度档位或任务配置中提供了无效参数。 |\n| `error_download_image` | 源图片下载失败。 |\n| `error_decode_image` | 源图片解码失败。 |\n\n**运行环境与依赖：**\n\n| 工具 / 语言 | 建议运行时版本 |\n| --- | --- |\n| cURL | Bash ≥ 3.2；curl ≥ 7.58（支持现代 TLS/HTTP）；jq ≥ 1.6（稳健的 JSON 解析）。 |\n| Node.js | Node ≥ 18，以支持全局 `fetch`。 |\n| JavaScript 浏览器支持 | Chrome / Edge ≥ 80、Firefox ≥ 74、Safari ≥ 13.1。 |\n| PHP | PHP ≥ 7.4（兼容现代 TLS）；建议 ext-curl，或 `allow_url_fopen=On` 并具备 OpenSSL 与 JSON 支持。 |\n| Python | Python ≥ 3.10（支持 f-string）；requests ≥ 2.20.0。 |\n| Java | Java 11+（HttpClient）；Jackson Databind ≥ 2.12.0。 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 图片背景虚化 V2.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_replace.yaml","link":"/zh-cn/reference/ai_replace","routeSlug":"/zh-cn/reference/ai_replace","label":"AI 替换物件","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_replace/section/概览","routeSlug":"/zh-cn/reference/ai_replace/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_replace/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_replace/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_replace/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_replace/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_replace/v1.0","routeSlug":"/zh-cn/reference/ai_replace/v1.0","items":[{"label":"执行 AI 替换物件 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","routeSlug":"/zh-cn/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace/post","metadata":{"seo":{"title":"执行 AI 替换物件 任务。","description":"查询任务状态请参见轮询指南。本接口需要源图片、蒙版文件，以及描述蒙版区域要替换成什么的提示词。"}},"httpPath":"/s2s/v2.0/task/obj-replace"},{"label":"查询 AI 替换物件 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_replace/v1.0/paths/~1s2s~1v2.0~1task~1obj-replace~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 替换物件 任务的状态。","description":"查询 AI 替换物件 任务的状态。"}},"httpPath":"/s2s/v2.0/task/obj-replace/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 替换物件","version":"","description":"# 概览\nAI 替换物件可以拿新物体换掉您不想要的元素。调用这个接口，您只要用文字描述，就能即刻去除照片中的多余物体、换上新的。从包到车，想换就换。​\n\n示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_02_a73a26bcc3.jpg)\n\n\n对想经营好社交账号的内容创作者来说，AI 替换物件是打磨旅行照、宣传图的省事办法。元素随您删换，内容更出彩。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_03_42c9cd98d0.jpg)\n\n\n用 AI 替换物件做出亮眼的空间效果图：往空荡的地方摆上好看的家具与物件，整个空间的观感立刻不一样。\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_replace_S3_feature_img_04_4d2d82f76e.jpg)\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 替换物件 | 长边 <= 2048 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 替换物件 V1.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_avatar_generator.yaml","link":"/zh-cn/reference/ai_avatar_generator","routeSlug":"/zh-cn/reference/ai_avatar_generator","label":"AI 虚拟化身生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_avatar_generator/section/概览","routeSlug":"/zh-cn/reference/ai_avatar_generator/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_avatar_generator/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_avatar_generator/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_avatar_generator/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_avatar_generator/section/概览/点数消耗"}]},{"type":"group","label":"V3.0","link":"/zh-cn/reference/ai_avatar_generator/v3.0","routeSlug":"/zh-cn/reference/ai_avatar_generator/v3.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","routeSlug":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-avatar/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/ai-avatar"},{"label":"执行 AI 虚拟化身生成器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","routeSlug":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar/post","metadata":{"seo":{"title":"执行 AI 虚拟化身生成器 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/ai-avatar"},{"label":"查询 AI 虚拟化身生成器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_avatar_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-avatar~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 虚拟化身生成器 任务的状态。","description":"查询 AI 虚拟化身生成器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/ai-avatar/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 虚拟化身生成器","version":"","description":"# 概览\nAI 魔法头像这款应用用的是图生图技术，也就是以您的照片为基础生成头像。用户选好照片后，应用内置的技术就开始分析并学习您的五官特征。\n\n想要更多头像风格，请参见 https://yce.makeupar.com/avatar\n\n使用场景：\n![AI Avatar Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Christmas_Avatar_b861c35edf.jpg \"AI Avatar Generator\")\n\n![AI Avatar Generator](https://plugins-media.makeupar.com/smb/blog/post/2023-04-06/fc2c3b2e-2b7f-48c9-96c1-cdb780f9dc1d.jpg \"AI Avatar Generator\")\n\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ----  | ---- |\n| AI 虚拟化身生成器 | 输入：长边 <= 4096，输出：长边 <= 1024 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 虚拟化身生成器 V3.0 | 4 张图 1 点数 * |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_headshot_generator.yaml","link":"/zh-cn/reference/ai_headshot_generator","routeSlug":"/zh-cn/reference/ai_headshot_generator","label":"AI 形象照生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_headshot_generator/section/概览","routeSlug":"/zh-cn/reference/ai_headshot_generator/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_headshot_generator/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_headshot_generator/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_headshot_generator/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_headshot_generator/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_headshot_generator/v1.0","routeSlug":"/zh-cn/reference/ai_headshot_generator/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","routeSlug":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1headshot/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/headshot"},{"label":"执行 AI 形象照生成器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","routeSlug":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot/post","metadata":{"seo":{"title":"执行 AI 形象照生成器 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/headshot"},{"label":"查询 AI 形象照生成器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_headshot_generator/v1.0/paths/~1s2s~1v2.0~1task~1headshot~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 形象照生成器 任务的状态。","description":"查询 AI 形象照生成器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/headshot/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 形象照生成器","version":"","description":"# 概览\n用 AI 职业形象照生成，把照片变成出众的职业形象照。借助这套强大的 AI 工具，快速高效地把形象照提升到专业水准。\n* 风格多样：从得体的 LinkedIn 头像、商务形象照，到有个性的模特形象照，任您挑选最合需要的样子。\n* 效果专业：由 AI 把关，形象照自然好看，给雇主与客户留下好印象。\n* 省时省力：随时随地生成多张 AI 形象照，不用请摄影师，最适合日程紧的专业人士。\n\n想要更多 AI 形象照风格，请参见 https://yce.makeupar.com/ai-headshot-generator。\n\n使用场景：\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s2_img_03_4b55742358.jpg \"AI Headshot Generator\")\n\n![AI Headshot Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_headshot_s1_img_1_d03183d7e0.jpg \"AI Headshot Generator\")\n\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 形象照生成 | 请确保输入图片中只有一个人，OpenPose 可看到两侧肩点与完整脸部，短边 ≤ 1024 像素——超出时引擎会自动缩放到 1024。输出：长边 <= 1024 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| exceed_max_filesize |\t输入文件大小超出上限 |\n| invalid_parameter |\t参数取值无效 |\n| error_download_image\t| 下载原图出错 |\n| error_decode_image\t| 解码原图出错 |\n| error_nsfw_content_detected\t| 在原图中检测到不适宜内容（NSFW） |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 形象照生成 V1.0 | 2 张图 1 点数 * |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_studio_generator.yaml","link":"/zh-cn/reference/ai_studio_generator","routeSlug":"/zh-cn/reference/ai_studio_generator","label":"AI 照相馆生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_studio_generator/section/概览","routeSlug":"/zh-cn/reference/ai_studio_generator/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_studio_generator/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_studio_generator/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_studio_generator/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_studio_generator/section/概览/点数消耗"}]},{"type":"group","label":"V3.0","link":"/zh-cn/reference/ai_studio_generator/v3.0","routeSlug":"/zh-cn/reference/ai_studio_generator/v3.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","routeSlug":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1template~1ai-studio/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/ai-studio"},{"label":"执行 AI 照相馆生成器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","routeSlug":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio/post","metadata":{"seo":{"title":"执行 AI 照相馆生成器 任务。","description":"查询任务状态请参见轮询指南。本接口需要源图片、模板 ID 与输出张数设置。"}},"httpPath":"/s2s/v2.0/task/ai-studio"},{"label":"查询 AI 照相馆生成器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_studio_generator/v3.0/paths/~1s2s~1v2.0~1task~1ai-studio~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 照相馆生成器 任务的状态。","description":"查询 AI 照相馆生成器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/ai-studio/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 照相馆生成器","version":"","description":"# 概览\n感受照相馆级 AI 人像生成的出色品质。一张自拍，转眼变成照相馆质感的人像照。​\n* 不用照相馆也省心：不必请摄影师、也不必跑摄影楼，随时随地都能做出照相馆级的艺术照​\n* 出片快：处理迅速，高质量艺术照即刻到手，临时要更新头像最合用\n* 艺术照质感高：细节清楚、光线到位，达到专业水准，就像真在摄影楼里拍的一样\n\n使用场景：\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S1_img_19b627b6af.jpg \"AI Studio Generator\")\n\n![AI Studio Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_AI_studio_S2_img_01_2e318817e9.jpg \"AI Studio Generator\")\n\n\n拍摄建议：\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png \"Suggestions for How to Shoot\")\n\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 照相馆生成器|请确保输入图片中有一张人脸，短边不小于 200 像素、长边不超过 1920 像素；图中有多张人脸时，引擎取最大的一张；输出分辨率不超过 960×1280（宽×高）|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size\t|输入图片分辨率过小|\n|error_exceed_max_image_size\t|输入图片分辨率过大|\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 照相馆生成器生成 V3.0 | 2 张图 1 点数 * |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_image_generator.yaml","link":"/zh-cn/reference/ai_image_generator","routeSlug":"/zh-cn/reference/ai_image_generator","label":"AI 图片生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_image_generator/section/概览","routeSlug":"/zh-cn/reference/ai_image_generator/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_image_generator/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_image_generator/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_image_generator/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_image_generator/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_image_generator/v2.0","routeSlug":"/zh-cn/reference/ai_image_generator/v2.0","items":[{"label":"执行 AI 图片生成器 V2（文字生成图片）任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","routeSlug":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam/post","metadata":{"seo":{"title":"执行 AI 图片生成器 V2（文字生成图片）任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam"},{"label":"查询 AI 图片生成器 V2（文字生成图片）任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片生成器 V2（文字生成图片）任务的状态。","description":"查询 AI 图片生成器 V2（文字生成图片）任务的状态。"}},"httpPath":"/s2s/v2.0/task/text-to-image/youcam/{task_id}"},{"label":"执行 AI 图片生成器 V2（图生图）任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","routeSlug":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam/post","metadata":{"seo":{"title":"执行 AI 图片生成器 V2（图生图）任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam"},{"label":"查询 AI 图片生成器 V2（图生图）任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_image_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-image~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片生成器 V2（图生图）任务的状态。","description":"查询 AI 图片生成器 V2（图生图）任务的状态。"}},"httpPath":"/s2s/v2.0/task/image-to-image/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_image_generator/v1.0","routeSlug":"/zh-cn/reference/ai_image_generator/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","routeSlug":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1text-to-image/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/text-to-image"},{"label":"执行 AI 图片生成器 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","routeSlug":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image/post","metadata":{"seo":{"title":"执行 AI 图片生成器 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/text-to-image"},{"label":"查询 AI 图片生成器 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_image_generator/v1.0/paths/~1s2s~1v2.0~1task~1text-to-image~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片生成器 任务的状态。","description":"查询 AI 图片生成器 任务的状态。"}},"httpPath":"/s2s/v2.0/task/text-to-image/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 图片生成器","version":"","description":"# 概览\n用我们创新的文生图工具，见识 AI 的能量！一句话即刻变成亮眼画面，提示词随您试，卡通、油画、素描等风格随您玩，把创意痛快释放出来。不论您是画家、设计师还是热爱创意的人，这套工具都能给足空间，把您脑海里的画面做出来。还能加入参考图，激发新的创作方向，由 AI 打磨成完全原创的作品。\n\n想要更多灵感？请参见 https://yce.makeupar.com/ai-art-generator。\n\n使用场景：\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v3_video_02f161f909.jpg \"AI Image Generator\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_v4_poster_092d2fbb9f.jpg \"AI Image Generator\")\n\n输出示例：\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_2_e325681588.jpg \"AI Image Generator\")\n\n![AI Image Generator](https://bcw-media.s3.ap-northeast-1.amazonaws.com/text_to_image_topbanner_dt_5_8b4fa13c6a.jpg \"AI Image Generator\")\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n| V1.0 文生图 | 输出：长边 1024 像素。 | 提示词不得超过 500 个字符 | 不适用 |\n| V2.0 文生图 | 输出：默认分辨率 1664 × 928，支持 1664 × 928（16:9）、1472 × 1104（4:3）、1328 × 1328（1:1）、1104 × 1472（3:4）、928 × 1664（9:16）。 | 提示词不得超过 800 个字符 | 不适用 |\n| V2.0 图生图 | 输入：宽与高都须在 384 到 3072 像素之间。<br>输出：宽高可自行设定，范围 512 到 2,048 像素；默认设置的总像素约为 1,024 × 1,024，比例依输入图而定。 | <10MB<br> 提示词不得超过 800 个字符 | JPG、JPEG、PNG、BMP、TIFF、WEBP、GIF。<br>动图 GIF 仅处理第一帧。 |\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---------- | ----------- |\n| exceed_max_filesize | 上传的文件大小超出上限。 |\n| invalid_parameter | 有参数缺失或取值无效 |\n| error_download_image | 下载原图失败。 |\n| error_decode_image | 解码或解析原图失败。 |\n| error_nsfw_content_detected | 在原图中检测到不适宜内容（NSFW）。 |\n| error_unsupport_ratio | 输入图片的宽高比不受支持。 |\n| unknown_internal_error | 发生未知的内部错误。 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 图片生成器 V1.0 | 2 |\n| AI 图片生成器 V2.0 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_watermark_removal.yaml","link":"/zh-cn/reference/ai_watermark_removal","routeSlug":"/zh-cn/reference/ai_watermark_removal","label":"AI 水印移除","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_watermark_removal/section/概览","routeSlug":"/zh-cn/reference/ai_watermark_removal/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_watermark_removal/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_watermark_removal/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_watermark_removal/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_watermark_removal/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_watermark_removal/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_watermark_removal/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_watermark_removal/v1.0","routeSlug":"/zh-cn/reference/ai_watermark_removal/v1.0","items":[{"label":"执行 去水印 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal/post","routeSlug":"/zh-cn/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal/post","metadata":{"seo":{"title":"执行 去水印 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/wmk-removal"},{"label":"查询 去水印 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_watermark_removal/v1.0/paths/~1s2s~1v2.0~1task~1wmk-removal~1{task_id}/get","metadata":{"seo":{"title":"查询 去水印 任务的状态。","description":"查询 去水印 任务的状态。"}},"httpPath":"/s2s/v2.0/task/wmk-removal/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 水印移除","version":"","description":"# 概览\nAI 去水印\n\n稳定检测并消除水印、logo 及其他标记，原图的画质与细节原样保住。\n\n    > 请合规使用本工具，避免用于不道德的场景，例如为未经授权的商业用途去除水印。请尊重图片的原始用途，遵循合理使用的原则。\n\n![](https://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_Image_24bf9f2ed1.png)\n\n---\n\n## 接入指南\n\n* AI 去水印使用指引\n\n本指引说明如何上传图片、准备参考服装，以及用 AI 去水印创建虚拟试穿任务。\n\n***\n\n   * 第 1 步：用 File 接口上传文件\n\n用 **File 接口**（`/s2s/v2.0/file`）上传目标图片。\n\n***\n\n   * 第 2 步：取得 File 接口响应\n\n响应中包含：\n\n*   用于创建 AI 任务的 `file_id`。\n*   用于上传实际图片文件的 `requests.url`。\n\n***\n\n   * 第 3 步：把图片上传到提供的 URL\n\n用 File 接口响应中的 `requests.url` 上传图片：\n\n***\n\n   * 第 4 步：创建 AI 任务\n\n用 **AI 任务接口**（`/s2s/v2.0/task/wmk-removal`）创建 AI 任务。\n\n***\n\n   * 第 5 步：轮询任务结果\n\n用任务 ID 查看状态：\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/wmk-removal/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n***\n\n   * 第 6 步：取回结果\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![](https://d32qvgpd29lguw.cloudfront.net/Watermark_Remover_BA_2_c8bbf561af.png)\n\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n|  ---- | ---- | ---- | ---- |\n| AI 去水印 | 最长边 4096 px | < 10MB | jpg/png |\n\n    > 未经版权方同意或出于未经授权的目的去除水印可能违法。请确保您对该图片拥有相应权利。\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---------- | ----------- |\n| invalid_parameter |参数缺失或取值无效。 |\n| error_download_image | 图片下载失败。 |\n| exceed_max_filesize | 图片过大。文件大小不得超过 10 MB，长边不得超过 4096 像素。 |\n| error_below_min_image_size | 图片过小。长边不得小于 128 像素。 |\n| error_nsfw_content_detected | 在结果图中检测到疑似不适宜内容（NSFW）。 |\n| error_editing_failed | 编辑失败：结果图与原图过于相似。 |\n| unknown_internal_error | 处理本次请求时我们这边出了错。 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 去水印 | 1 |\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_retake.yaml","link":"/zh-cn/reference/ai_retake","routeSlug":"/zh-cn/reference/ai_retake","label":"AI Retake","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_retake/section/概览","routeSlug":"/zh-cn/reference/ai_retake/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_retake/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_retake/section/概览/接入指南"},{"type":"link","label":"输入与输出","link":"/zh-cn/reference/ai_retake/section/概览/输入与输出","routeSlug":"/zh-cn/reference/ai_retake/section/概览/输入与输出"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_retake/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_retake/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_retake/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_retake/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_retake/v2.0","routeSlug":"/zh-cn/reference/ai_retake/v2.0","items":[{"label":"执行 AI Retake人脸检测任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process/post","routeSlug":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process/post","metadata":{"seo":{"title":"执行 AI Retake人脸检测任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/retake/pre-process"},{"label":"查询 AI Retake人脸检测任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process~1{task_id}/get","metadata":{"seo":{"title":"查询 AI Retake人脸检测任务的状态。","description":"查询 AI Retake人脸检测任务的状态。"}},"httpPath":"/s2s/v2.0/task/retake/pre-process/{task_id}"},{"label":"执行 AI Retake 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake/post","routeSlug":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake/post","metadata":{"seo":{"title":"执行 AI Retake 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/retake"},{"label":"查询 AI Retake 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1{task_id}/get","metadata":{"seo":{"title":"查询 AI Retake 任务的状态。","description":"查询 AI Retake 任务的状态。"}},"httpPath":"/s2s/v2.0/task/retake/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI Retake","version":"","description":"# 概览\n留住这一刻，把脸换一换。AI 换脸（Retake）可以逐张逐脸地重建任意合照。不管是想做搞怪换脸图，还是需要一套专业工具，我们都能满足。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/3d504686-8057-418e-a0cb-eba3d47ea42c.jpg)\n\n## 接入指南\n* 如何实现 AI 换脸（Retake）\n\n   * 第 1 步：上传源图与参考图\n\n      1. 向接口请求上传 URL：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. 响应会给出一个预签名的**上传 URL** 和一个 `file_id`。\n        2. 用 HTTP PUT 请求把文件上传到该 URL。\n        3. 保存 `file_id` 备用。**目标图**与**参考图**都要重复这一套流程。\n\n      2. 把实际文件上传到**上传 URL**。\n\n---\n\n   * 第 2 步：预处理源图与参考图（人脸检测）\n\n        1. 创建预处理任务：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. 接口返回一个 `task_id`。\n        2. 在此接口轮询任务状态：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process?task_id=TASK_ID\n        ```\n        1. 处理完成后，您会收到一份带边界框的检测到的人脸列表。\n\n---\n\n   * 第 3 步：执行 AI 换脸（Retake）任务\n        1. 指定哪张参考图的脸去替换源图中的哪张脸\n        `face_mapping` 数组定义了**源图**中的人脸如何被**参考图**的人脸替换，作用相当于把源图中检测到的人脸与指定参考图串起来的关联表。 \n        \n        单次请求只支持替换一张脸。所有非目标的人脸都必须设为 `{\"index\": -1, \"position\": -1}`。尝试替换超过一张脸会返回 `error_change_too_many_faces`。返回该错误的请求不会计费。参考图只支持使用检测到的第一张脸，因此 index 必须始终为 0。\n\n        * 参数\n            \n            | 参数\t| 类型\t| 说明 |\n            | -- | -- | -- |\n            | position\t| 整数\t| 源图中检测到的人脸下标（例如 0、1、2）。\n            | index\t| 整数\t| 参考图人脸下标。目前只支持第一张检测到的人脸，因此该值必须为 0。\n            \n        * 规则\n          * 单脸替换：单次请求只能把一张源图人脸映射到一张参考图人脸。\n          * 跳过某张脸：把 index 与 position 都设为 -1。\n          * 参考图人脸下标：参考图只支持检测到的第一张脸，因此 index 始终为 0。\n            \n        * 示例\n\n            场景\n            * 参考图：1 张含单张受支持人脸的图片。\n            * 源图：检测到 4 张脸（Face 0、Face 1、Face 2、Face 3）。\n            * 目标：只替换 Face 2，Face 0、Face 1、Face 3 保持不动。\n            ```\n                \"face_mapping\": [\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                    {\n                        \"index\": 0, // Always use the first reference image\n                        \"position\": 2 // Apply to the third detected face in source\n                    },\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                ]\n            ```\n        1. 发送主任务请求：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n          \"request_id\": 2,\n          \"payload\"   : {\n            \"file_sets\": {\n              \"src_ids\": [\"TARGET_FILE_ID\"   ],\n              \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\"  : [\n              {\n                \"id\"    : 0,\n                \"params\": {\n                  \"face_mapping\": [\n                    {\"index\": -1, \"position\": -1},\n                    {\"index\": -1, \"position\": -1},\n                    {\"index\":  0, \"position\":  2},\n                    {\"index\": -1, \"position\": -1}\n                  ]\n                }\n              }\n            ]\n          }\n        }\n        ```\n        1. 响应返回一个 `task_id`。\n\n---\n\n   * 第 4 步：轮询任务状态并取回结果\n        需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。\n        1. 在此接口轮询：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake?task_id=TASK_ID\n        ```\n        2. 当 `status` 为 `success` 时，响应中包含生成图片的 URL。\n        3. 从该 URL 下载或展示图片。\n\n---\n\n   * 第 5 步：接入您的平台\n\n        * 在**网页前端**，可以直接用 JavaScript 的 fetch 或 Axios 实现。\n        * 在**后端**（Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。\n        * 任务是异步执行的，请实现重试与错误处理。\n\n---\n\n    * 排障指引\n\n        1. **为什么源图里有些脸没被检测到**\n            </br>**原因：** 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大\n            </br>**解决办法：** 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡\n\n---\n\n## 输入与输出\n\n* 实际案例：\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/9aeab2bb-28aa-48f5-ab86-2edd897ad908.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-02/webp_0196a9d4-1430-4121-9680-5e81b58b66ac.webp)\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ---- | ---- |\n| AI 换脸（Retake） | 输入与输出：长边不得超过 4096 像素 | < 10MB | jpg/jpeg/png |\n\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------ | ----------- |\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_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\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| error_multiple_people | 人数超出上限 |\n| error_no_shoulder | 源图中看不到肩部 |\n| error_large_face_angle | 上传图片中的脸部角度过大 |\n| error_unsupport_ratio | 输入图片的宽高比不受支持 |\n| error_change_too_many_faces | 单次请求只支持替换一张脸。所有非目标的人脸都必须设为 {\"index\": -1, \"position\": -1}。尝试替换超过一张脸就会返回该错误。 |\n| unknown_internal_error | 其他内部错误 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 换脸（Retake）V2.0 | 1 |\n\n---\n"}},{"type":"separator","label":"视频","labelTranslationKey":"sidebar.reference.separators.video"},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_generator.yaml","link":"/zh-cn/reference/ai_video_generator","routeSlug":"/zh-cn/reference/ai_video_generator","label":"AI 视频生成器","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_generator/section/概览","routeSlug":"/zh-cn/reference/ai_video_generator/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_generator/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_generator/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_generator/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_generator/section/概览/点数消耗"}]},{"type":"group","label":"V2.0","link":"/zh-cn/reference/ai_video_generator/v2.0","routeSlug":"/zh-cn/reference/ai_video_generator/v2.0","items":[{"label":"执行 AI 图片生成器视频（V2） 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","routeSlug":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam/post","metadata":{"seo":{"title":"执行 AI 图片生成器视频（V2） 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam"},{"label":"查询 AI 图片生成器视频（V2） 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1image-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片生成器视频（V2） 任务的状态。","description":"查询 AI 图片生成器视频（V2） 任务的状态。"}},"httpPath":"/s2s/v2.0/task/image-to-video/youcam/{task_id}"},{"label":"执行 文字生成视频 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","routeSlug":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam/post","metadata":{"seo":{"title":"执行 文字生成视频 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam"},{"label":"查询 文字生成视频 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_generator/v2.0/paths/~1s2s~1v2.0~1task~1text-to-video~1youcam~1{task_id}/get","metadata":{"seo":{"title":"查询 文字生成视频 任务的状态。","description":"查询 文字生成视频 任务的状态。"}},"httpPath":"/s2s/v2.0/task/text-to-video/youcam/{task_id}"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_video_generator/v1.0","routeSlug":"/zh-cn/reference/ai_video_generator/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","routeSlug":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1template~1image-to-video/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/image-to-video"},{"label":"执行 AI 图片生成器视频 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","routeSlug":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video/post","metadata":{"seo":{"title":"执行 AI 图片生成器视频 任务。","description":"本接口用于发起 AI 图片生成器视频流程。您需要提供模板 ID 与源文件（URL 或文件 ID）。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。"}},"httpPath":"/s2s/v2.0/task/image-to-video"},{"label":"查询 AI 图片生成器视频 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_generator/v1.0/paths/~1s2s~1v2.0~1task~1image-to-video~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 图片生成器视频 任务的状态。","description":"查询 AI 图片生成器视频 任务的状态。"}},"httpPath":"/s2s/v2.0/task/image-to-video/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频生成器","version":"","description":"# 概览\nYouCam AI 视频生成器能把文字提示和图片变成引人入胜的视频，操作轻松。依托先进 AI 技术，生成逼真的动态效果，让您的点子与照片活起来。还有大量经过专业调校的模板，静态图片很快就能变成好看好玩的高画质视频内容。\n\n想用 AI 生成 AI 视频，请挑一张背景干净、人物清楚的照片。上传图片即可，剩下的交给 YouCam AI 视频生成器，转眼之间就把您的文字提示与照片做成一段动感视频。\n\n使用场景：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_Animate%20Photo_047_d9e1cff579.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Dance_Video_61cf4c58d1.png)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/241216_AI_Kiss_image05_c3b7f1ac5b.jpg)\n\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| V1.0 图生视频（标准版） |输入：>= 300*300px，宽高比介于 1:2.5 ~ 2.5:1。输出：最高 720p 30fps|输入：<10MB。输出：5 秒或 10 秒|jpg/jpeg/png|\n| V1.0 图生视频（专业版） |输入：>= 300*300px，宽高比介于 1:2.5 ~ 2.5:1。输出：最高 1080p 30fps|输入：<10MB。输出：5 秒或 10 秒|jpg/jpeg/png|\n| V2.0 图生视频 | 输入图片长边不超过 4096 像素，宽高比介于 1:2.5 与 2.5:1 之间。 <br> 支持的输出分辨率为 480p、720p、1080p。若输入图片短边大于所选分辨率，或长边小于目标分辨率，引擎会自动缩放，使短边与所选分辨率一致。 |输入：<10MB。输出：5 秒或 10 秒|jpg/jpeg/png|\n\n* 错误码\n\n| 错误类别 | 场景 / 说明 | 建议处理 |\n| -------------- | ---------------------- | ---------------- |\n| 请求参数无效 | 请求参数无效或缺失 | 确认所有请求参数填写正确 |\n| | 参数取值无效（例如密钥有误、取值不合法） | 查看响应中的错误信息字段，修正请求参数 |\n| | 请求方法有误 | 查阅接口文档，改用正确的 HTTP 方法 |\n| | 请求的资源不存在（例如模型未找到） | 参照响应中的错误信息字段修正请求参数|\n| 触发策略 | 触发平台策略 | 检查是否有违反平台策略之处 |\n| | 触发内容安全策略  | 检查并修改输入内容后重新发起请求 |\n| | 请求频率过高（超出限流）| 降低请求频率、稍后重试，或联系客服提升额度 |\n| | 并发或 QPS 超出配额   | 降低请求频率，或稍后重试 |\n| 内部错误  | 服务器内部错误 | 稍后重试或联系客服 |\n| | 服务器暂时不可用 | 稍后重试或联系客服 |\n| | 请求积压导致内部超时| 稍后重试或联系客服 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频生成器（标准版） V1.0 | 3（每秒）* |\n| AI 视频生成器（专业版） V1.0 | 6（每秒）* |\n| AI 视频生成器（图生视频） V2.0 | 1 点数（480p / 每秒）* <br> 2 点数（720p / 每秒）* <br> 3 点数（1080p / 每秒）* |\n| AI 视频生成器（文生视频） V2.0 | 2 点数（720p / 每秒）* <br> 3 点数（1080p / 每秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_enhancer.yaml","link":"/zh-cn/reference/ai_video_enhancer","routeSlug":"/zh-cn/reference/ai_video_enhancer","label":"AI 视频优化","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_enhancer/section/概览","routeSlug":"/zh-cn/reference/ai_video_enhancer/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_enhancer/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_enhancer/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_enhancer/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_enhancer/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_video_enhancer/v1.0","routeSlug":"/zh-cn/reference/ai_video_enhancer/v1.0","items":[{"label":"执行 AI 视频优化 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","routeSlug":"/zh-cn/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr/post","metadata":{"seo":{"title":"执行 AI 视频优化 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/video-sr"},{"label":"查询 AI 视频优化 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_enhancer/v1.0/paths/~1s2s~1v2.0~1task~1video-sr~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 视频优化 任务的状态。","description":"查询 AI 视频优化 任务的状态。"}},"httpPath":"/s2s/v2.0/task/video-sr/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频优化","version":"","description":"# 概览\n\nAI 视频优化接口让开发者几乎不费力气就能把视频画质提上去。它用先进 AI 处理修复模糊、调整锐度、优化亮度，并把低分辨率素材放大增强。一次简单的接口调用，就能把低清片段、老视频变成干净通透的高清画质。\n\n这套方案专为快速接入设计，不需要视频剪辑或机器学习的经验。处理用户生成内容的应用、媒体平台、营销工具、内容自动化系统用它正合适。\n\n\n**核心能力**\n\n1. 模糊修复\n   接口会检测运动模糊与发虚的细节，再用 AI 增强模型重建更锐利的画面。\n\n2. 锐度优化\n   强化边缘与纹理，视频看起来更立体、更清爽。\n\n3. 亮度与曝光调整\n   自动校正光线不均，提升可见度与色彩平衡。\n\n4. AI 超分放大\n   从 480p 等低画质格式智能提升分辨率到高清，细节不打折。\n\n5. AI 照片优化\n   降噪并去除瑕疵，成果干净、专业。\n\n使用示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_enhancer_S2_feature_video_03_S_0_10169a6902.jpg)\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 视频优化 | 输入视频时长不超过 60 秒，分辨率 2K 及以下，帧率不超过每秒 30 帧。 | 时长上限：60 秒 | 封装格式：mov、mp4 <br>视频编码：MPEG-4、MPEG-4 AVC，<br>音频编码：aac、amr、mp3 |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_unsupported_video | 视频格式不受支持 |\n| exceed_max_filesize | 输入文件大小超出上限|\n| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |\n| error_decode_mask | 解码蒙版图片出错 |\n| invalid_parameter | 参数取值无效|\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频优化 V1.0 | 1（每 2 秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_face_swap.yaml","link":"/zh-cn/reference/ai_video_face_swap","routeSlug":"/zh-cn/reference/ai_video_face_swap","label":"AI 视频换脸","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_face_swap/section/概览","routeSlug":"/zh-cn/reference/ai_video_face_swap/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_face_swap/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_face_swap/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_face_swap/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_face_swap/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_video_face_swap/v1.0","routeSlug":"/zh-cn/reference/ai_video_face_swap/v1.0","items":[{"label":"执行 AI 视频换脸 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","routeSlug":"/zh-cn/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid/post","metadata":{"seo":{"title":"执行 AI 视频换脸 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/face-swap-vid"},{"label":"查询 AI 视频换脸 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap-vid~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 视频换脸 任务的状态。","description":"查询 AI 视频换脸 任务的状态。"}},"httpPath":"/s2s/v2.0/task/face-swap-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频换脸","version":"","description":"# 概览\nAI 视频换脸是一项由 AI 驱动的处理：借助 YouCam 的 AI 视频换脸接口，把视频里一个人的脸换成另一个人的脸。\n在先进 AI 技术的加持下，AI 视频换脸的效果相当逼真。脸部表情、光线、肤色都会精细调校，换上来的脸与原视频画面浑然一体。\n\n> **说明：** 本接口仅支持单人脸视频。需要定制方案，请[联系我们](mailto:YouCamOnlineEditor_API@perfectcorp.com)。\n\n使用示例：\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-08-23/b1f96100-37d6-4c28-b467-d397e9c3a25d.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_face_swap_S3_video_03_28785ebe0c.jpg)\n\n![](https://plugins-media.makeupar.com/smb/story/2024-09-12/3582f617-e88e-4219-9e72-43d4c26791cd.png)\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 视频换脸 | 输入视频不得超过 30 秒、4K 分辨率或 30 FPS；输出限制为长边 1280 分辨率、30 FPS、最长 30 秒。 | 时长上限：30 秒 | 封装格式：mov、mp4 <br>视频编码：MPEG-4、MPEG-4 AVC，<br>音频编码：aac、amr、mp3 |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_unsupported_video | 视频格式不受支持 |\n| exceed_max_filesize | 输入文件大小超出上限|\n| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |\n| error_decode_mask | 解码蒙版图片出错 |\n| invalid_parameter | 参数取值无效|\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频换脸 V1.0 | 1（每 5 秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_style_transfer.yaml","link":"/zh-cn/reference/ai_video_style_transfer","routeSlug":"/zh-cn/reference/ai_video_style_transfer","label":"AI 视频风格迁移","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_style_transfer/section/概览","routeSlug":"/zh-cn/reference/ai_video_style_transfer/section/概览","items":[{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_style_transfer/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_style_transfer/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_style_transfer/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_style_transfer/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_video_style_transfer/v1.0","routeSlug":"/zh-cn/reference/ai_video_style_transfer/v1.0","items":[{"label":"列出预置模板。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","routeSlug":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1template~1video-trans/get","metadata":{"seo":{"title":"列出预置模板。","description":"列出预置模板。"}},"httpPath":"/s2s/v2.0/task/template/video-trans"},{"label":"执行 AI 视频风格迁移 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","routeSlug":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans/post","metadata":{"seo":{"title":"执行 AI 视频风格迁移 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/video-trans"},{"label":"查询 AI 视频风格迁移 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_style_transfer/v1.0/paths/~1s2s~1v2.0~1task~1video-trans~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 视频风格迁移 任务的状态。","description":"查询 AI 视频风格迁移 任务的状态。"}},"httpPath":"/s2s/v2.0/task/video-trans/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频风格迁移","version":"","description":"# 概览\n用 AI 视频滤镜与特效做出独一无二的视频，轻松给每段视频加上亮眼的 AI 风格。AI 视频滤镜即刻出效果：套用滤镜，画面马上焕然一新。波普、复古、动漫等多种独特风格任您挑，让每一帧都更有层次、更有创意。\n\n使用示例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_style_transfer_S1_video_1_0_6d571a8bbb.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_web_video_style_transfe_S2_feature_03_0_6dd652a6f2.jpg)\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 视频风格迁移 | 输入视频不得超过 30 秒、4K 分辨率或 30 FPS；输出限制为长边 1280 分辨率、16 FPS、最长 30 秒。 | 时长上限：30 秒 | 封装格式：mov、mp4 <br>视频编码：MPEG-4、MPEG-4 AVC，<br>音频编码：aac、amr、mp3 |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_unsupported_video | 视频格式不受支持 |\n| exceed_max_filesize | 输入文件大小超出上限|\n| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |\n| error_decode_mask | 解码蒙版图片出错 |\n| invalid_parameter | 参数取值无效|\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频风格迁移 V1.0 | 4（每秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_object_removal.yaml","link":"/zh-cn/reference/ai_video_object_removal","routeSlug":"/zh-cn/reference/ai_video_object_removal","label":"AI 视频对象移除","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_object_removal/section/概览","routeSlug":"/zh-cn/reference/ai_video_object_removal/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_video_object_removal/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_video_object_removal/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_object_removal/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_object_removal/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_object_removal/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_object_removal/section/概览/点数消耗"}]},{"type":"group","label":"V2.1","link":"/zh-cn/reference/ai_video_object_removal/v2.1","routeSlug":"/zh-cn/reference/ai_video_object_removal/v2.1","items":[{"label":"创建新文件。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","routeSlug":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1file~1obj-rem-vid/post","metadata":{"seo":{"title":"创建新文件。","description":"上传新文件要先调用 File API。它会给您一个 URL， 用这个 URL 把文件传上去。上传完成后，就可以用同一次响应里的 file_id 开始使用我们的 AI 功能。"}},"httpPath":"/s2s/v2.0/file/obj-rem-vid"},{"label":"执行 AI 视频对象移除 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","routeSlug":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid/post","metadata":{"seo":{"title":"执行 AI 视频对象移除 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/obj-rem-vid"},{"label":"查询 AI 视频对象移除 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_object_removal/v2.1/paths/~1s2s~1v2.0~1task~1obj-rem-vid~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 视频对象移除 任务的状态。","description":"查询 AI 视频对象移除 任务的状态。"}},"httpPath":"/s2s/v2.0/task/obj-rem-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频对象移除","version":"","description":"# 概览\n\n**AI 视频对象移除**\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-02-04/webp_537ec670-48c0-49fc-b96b-8073de21a64b.webp)\n\nAI 视频对象移除接口可以把视频里多余的东西干净移除。不管是挤满游客的背景、桌上堆满纸巾水瓶的杂乱环境，还是玻璃上的反光干扰，这个接口都能把蒙版标出的区域精准、稳定地消除掉，效果前后一致。\n\n\n---\n\n## 接入指南\n\n**1. 准备源视频与蒙版图片**\n输入视频时长不超过 60 秒；输出视频长轴不超过 1920 像素，帧率不超过每秒 30 帧。\n\n\n**2. 上传文件**\n通过以下接口取得上传 URL 与文件 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n输入视频：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_input_edd43a2470.png)\n\n\n参考蒙版：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_mask_4a1c9fb658.png)\n\n\n**3. 执行 AI 任务**\n\n```\nPOST /s2s/v2.0/task/obj-rem-vid\n```\n\n用文件 ID 或图片 URL 作为输入提交任务。响应会返回一个 task_id，用于追踪并取回结果。\n\n\n**4. 取回任务结果**\n\n```\nGET /s2s/v2.0/task/obj-rem-vid/{task_id}\n```\n\n用任务 ID 追踪状态并取得结果。\n\n可配置 [Webhooks](/develop/webhook.md)，在任务完成（状态为 success 或 error）时接收异步通知。也支持轮询：反复调用任务接口，直到状态从 running 变为 success 或 error。\n\n只有任务成功完成才计费。\n\n\n输出视频示例：\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_video_object_removal_output_eb7670cd9e.png)\n\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 视频对象移除 | 输入视频时长不超过 60 秒；输出视频长轴不超过 1920 像素，帧率不超过每秒 30 帧。 | 时长上限：60 秒 | 封装格式：mov、mp4 <br>视频编码：MPEG-4、MPEG-4 AVC，<br>音频编码：aac、amr、mp3 |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_unsupported_video | 视频格式不受支持 |\n| exceed_max_filesize | 输入文件大小超出上限|\n| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |\n| error_decode_mask | 解码蒙版图片出错 |\n| invalid_parameter | 参数取值无效|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频对象移除 V2.1 | 2（每秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}},{"type":"group","fsPath":"@l10n/zh-CN/reference/ai_video_background_replace.yaml","link":"/zh-cn/reference/ai_video_background_replace","routeSlug":"/zh-cn/reference/ai_video_background_replace","label":"AI 视频背景替换","items":[{"type":"group","label":"概览","link":"/zh-cn/reference/ai_video_background_replace/section/概览","routeSlug":"/zh-cn/reference/ai_video_background_replace/section/概览","items":[{"type":"link","label":"接入指南","link":"/zh-cn/reference/ai_video_background_replace/section/概览/接入指南","routeSlug":"/zh-cn/reference/ai_video_background_replace/section/概览/接入指南"},{"type":"link","label":"文件规格与错误码","link":"/zh-cn/reference/ai_video_background_replace/section/概览/文件规格与错误码","routeSlug":"/zh-cn/reference/ai_video_background_replace/section/概览/文件规格与错误码"},{"type":"link","label":"点数消耗","link":"/zh-cn/reference/ai_video_background_replace/section/概览/点数消耗","routeSlug":"/zh-cn/reference/ai_video_background_replace/section/概览/点数消耗"}]},{"type":"group","label":"V1.0","link":"/zh-cn/reference/ai_video_background_replace/v1.0","routeSlug":"/zh-cn/reference/ai_video_background_replace/v1.0","items":[{"label":"执行 AI 视频背景替换 任务。","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","routeSlug":"/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post","metadata":{"seo":{"title":"执行 AI 视频背景替换 任务。","description":"AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 success 或 error 通知后，用收到的 task_id 查询任务结果。配置与校验的细节请见 Webhook 接入指南。"}},"httpPath":"/s2s/v2.0/task/bg-replace-vid"},{"label":"查询 AI 视频背景替换 任务的状态。","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","routeSlug":"/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1{task_id}/get","metadata":{"seo":{"title":"查询 AI 视频背景替换 任务的状态。","description":"查询 AI 视频背景替换 任务的状态。"}},"httpPath":"/s2s/v2.0/task/bg-replace-vid/{task_id}"}]}],"metadata":{"type":"openapi","title":"AI 视频背景替换","version":"","description":"# 概览\n\n**AI 视频背景替换**\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png)\n\nAI 视频背景替换接口可以让您把任意背景无缝加进画面。风景、自定义图片、趣味画面随您选，创作空间完全交给您，把视频场景做到最理想的状态。\n不用摄影棚，也不用绿幕。换掉视频背景轻轻松松，画面干净又专业。无论想换个新环境，还是去掉画面里多余的东西，这套方案都很合适，不必购置昂贵设备，就能做出好看的视频与教学片。\n\n\n---\n\n## 接入指南\n\n**1. 准备源视频与背景图片**\n输出为 MP4 格式，分辨率与输入一致；帧率上限为每秒 30 帧，输入超出时自动转换；时长上限 600 秒，输入视频更长时只保留前 600 秒。\n\n背景图片须为 JPG 或 PNG 格式，分辨率最高 4096 × 4096 像素，长边不超过 4096 像素，文件大小上限 10 MB。\n\n\n**2. 上传文件**\n通过以下接口取得上传 URL 与文件 ID：\n\n```\nPOST /s2s/v2.0/file\n```\n\n\n**3. 执行 AI 任务**\n\n```\nPOST /s2s/v2.0/task/bg-replace-vid\n```\n\n用文件 ID 或图片 URL 作为输入提交任务。响应会返回一个 task_id，用于追踪并取回结果。\n\n\n**4. 取回任务结果**\n\n```\nGET /s2s/v2.0/task/bg-replace-vid/{task_id}\n```\n\n用任务 ID 追踪状态并取得结果。\n\n可配置 [Webhooks](/develop/webhook.md)，在任务完成（状态为 success 或 error）时接收异步通知。也支持轮询：反复调用任务接口，直到状态从 running 变为 success 或 error。\n\n只有任务成功完成才计费。\n\n\n\n---\n\n## 文件规格与错误码\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n| AI 视频背景替换 | 输出为 MP4 格式，分辨率与输入一致；帧率上限为每秒 30 帧，输入超出时自动转换；时长上限 600 秒，输入视频更长时只保留前 600 秒。 <br>背景图片须为 JPG 或 PNG 格式，分辨率最高 4096 × 4096 像素，长边不超过 4096 像素，文件大小上限 10 MB。 | 视频时长上限：600 秒 <br> 背景图片：<10MB | 封装格式：mp4 <br>视频编码：MPEG-4、MPEG-4 AVC，<br>音频编码：aac、amr、mp3 |\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_unsupported_video | 视频格式不受支持 |\n| exceed_max_filesize | 输入文件大小超出上限|\n| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |\n| error_decode_mask | 解码蒙版图片出错 |\n| invalid_parameter | 参数取值无效|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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| AI 功能 | 消耗点数 |\n|---|---|\n| AI 视频背景替换 V1.0 | 2（每秒）* |\n\n    > *若图片数量或视频时长不能整除，点数按向上取整计算。\n\n---\n"}}]}