# AI 戒指虚拟试戴 # 概览 AR 戒指、求婚钻戒试戴，轻松做。您只要上传图片就行。采用 2D 图片即可轻松获得高质量的虚拟试戴体验，几乎不费力气。 ## 接入指南 本指南将带您走完全流程： * **接口地址：** `/s2s/v2.0/task/2d-vto/ring` * **鉴权：** 所有请求都需要 `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-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-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。 * 上传接口 ``` POST /s2s/v2.0/file ``` 如果您已有公开可访问的图片 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`）提供遮挡蒙版图，用于微调分割效果。 --- * 1. 创建 AI 戒指虚拟试戴任务并轮询结果 图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。 * 创建任务接口 ``` POST /s2s/v2.0/task/2d-vto/ring ``` * 轮询接口 ``` GET /s2s/v2.0/task/2d-vto/ring/{task_id} ``` --- ## 文件规格与错误码 * AI 戒指虚拟试戴规格 **支持的戒指图视角** 戒指图需采用斜前方视角（约 45 度）。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg) **支持的手部图视角** 手背需完整可见，五根手指清晰可辨，且无任何遮挡。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg) **ring_wearing_finger: integer（0–4）** 指定戒指戴在哪根手指上： 0 = 拇指 1 = 食指 2 = 中指 3 = 无名指 4 = 小指 **ring_wearing_location: float（0.0–1.0）** 表示沿手指的佩戴位置： 0.0 = 靠近 MCP 关节（大指节） 1.0 = 靠近 PIP 关节（中指节） ![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg) **ring_shadow_intensity: float（0.0–1.0）** 控制阴影强度： 0.0 = 无阴影 1.0 = 最大阴影 默认值：0.15 **ring_ambient_light_intensity: float（0.0–1.0）** 定义光线在多大程度上参考目标手部图： 0.0 = 忽略手部图的光线 1.0 = 完全匹配手部图的光线与阴影渲染 默认值：1.0 **ring_anchor_point: 像素坐标下由两个点组成的数组（可选）** 标出戒指内缘与手指接触处的左右两个点。戒圈较宽或较厚时尤其好用。 不提供该参数时，AI 引擎会自动检测锚点。 ![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.jpg) --- * 支持的格式与尺寸 | AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | AI 戒指虚拟试戴 | 长边 <= 4096 | < 10MB | jpg/jpeg/png | * 错误码 | 错误码 | 说明 | | --- | --- | | RUNTIME_ERROR | 运行时发生未知错误 | | PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 | | OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 | | PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 | | INPUT_ERROR | 输入文件格式有误 | | INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 | * 运行环境与依赖 | 示例代码语言 / 工具 | 建议运行时版本 | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) | | Node.js (JavaScript) | Node >= 18 (for global fetch) | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json | | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 | | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 | --- ## JS Camera Kit --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 戒指虚拟试戴 V1.0 | 单件佩戴 1 点数 叠戴 2 点数 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 戒指虚拟试戴](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ring_vto.yaml) ## V1.0 - [POST /s2s/v2.0/file/2d-vto/ring](https://docs.perfectcorp.com/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post.md): 上传新文件要先调用 File API。它会给您一个 URL， 用这个 URL 把文件传上去。上传完成后，就可以用同一次响应里的 file_id 开始使用我们的 AI 功能。 - [POST /s2s/v2.0/task/2d-vto/ring](https://docs.perfectcorp.com/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/2d-vto/ring/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1%7Btask_id%7D/get.md)