AI 耳环虚拟试戴

接入指南

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

• 接口地址： /s2s/v2.0/task/2d-vto/earring
• 鉴权： 所有请求都需要 Authorization: Bearer YOUR_API_KEY
• 流程：
  1. 准备自拍图片： 上传一张图片，或提供有效的图片 URL
  2. 准备耳环图片： 上传一张耳环商品图片，或提供有效的商品图片 URL
  3. 发起 AI 任务并获取 Task ID： 从响应中取到 task_id。
  4. 轮询状态（GET）： 用 task_id 查询任务状态，持续轮询直到 task_status 为 "success" 或 "error"。

• API Playground

用官方在线调试台交互式地体验与测试接口：

API Playground： http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/

• 鉴权

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

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

• 1. 上传图片

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

• 上传接口

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

您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 src_file_id；也可以在 VTO 任务参数中以 src_file_url 提供有效的图片 URL。src_file_id 或 src_file_url 就是虚拟试戴的目标图。

您还需用 ref_file_ids 或 ref_file_urls 提供一张耳环商品图作为参考，套用到您的 src_file_id 或 src_file_url 上。

AI 引擎支持自动去除耳环商品图的背景。您也可以为手部（srcmsk_file_id 或 srcmsk_file_url）或耳环商品（refmsk_file_ids 或 refmsk_file_urls）提供遮挡蒙版图，用于微调分割效果。

• 2. 创建 AI 耳环虚拟试戴任务并轮询结果

图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 success 或 error。

• 创建任务接口

• 轮询接口

文件规格与错误码

• AI 耳环虚拟试戴规格

支持的耳环参考图

• 单只耳环的正面图，画面清楚、无遮挡。
• 所有参数（包括锚点、蒙版、位置等）仅在参考图为单只耳环佩戴状态时生效。
• 若试戴参考图中是两只耳环，全部参数都将采用自动检测与默认设置。
• 双耳同时试戴时，以较清晰的那只耳朵为源，另一侧由镜像生成。

支持的自拍图视角

• AI 耳环虚拟试戴支持正脸图片，但侧脸图片的效果最好。

earring_wearing_location: 长度为 2 的整数数组 指定在自拍图中要佩戴耳环的位置。 默认值：null（使用引擎默认值）

earring_scale: 大于 0 的数值 按厘米控制耳环大小。 默认值：null（使用引擎默认值）

earring_is_right_ear: boolean 表示耳环是否戴在右耳，默认戴在右耳。 默认值：true

earring_occluded_type: number（枚举：0、1、2） 指定遮挡类型： 0 为自动检测 1 为有遮挡 2 为无遮挡 默认值：0

earring_shadow_intensity: float（0.0 到 1.0） 控制阴影强度： 0.0 表示无阴影 1.0 表示最大阴影 默认值：0.15

earring_ambient_light_intensity: float（0.0 到 1.0） 定义光线在多大程度上参考自拍图： 0.0 忽略自拍图的光线 1.0 完全匹配自拍图的光线与阴影渲染 默认值：1.0

earring_anchor_point: 像素坐标下 1 个点组成的数组（可选） 指定在耳环商品图中的佩戴位置。 默认值：null（使用引擎默认值）

• 支持的格式与尺寸

• 错误码

• 运行环境与依赖

JS Camera Kit

点数消耗