AI 项链虚拟试戴
顶尖虚拟试戴，尽显项链的高级质感 精准的 AI 颈部与锁骨追踪，带来超真实的 AR 试戴体验，把线下试戴项链的高级质感还原到位。
用一张 2D 图片就能做出真实灵动的 AI 项链虚拟试戴，不必花钱做 3D 建模。我们的先进算法能生成栩栩如生的试戴效果，光影细腻、动态符合物理规律。
本指南将带您走完全流程：
- 接口地址：
/s2s/v2.0/task/2d-vto/necklace - 鉴权： 所有请求都需要
Authorization: Bearer YOUR_API_KEY - 流程：
- 准备自拍图片： 上传一张图片，或提供有效的图片 URL
- 准备项链图片： 上传一张项链商品图片，或提供有效的商品图片 URL
- 发起 AI 任务并获取 Task ID： 从响应中取到
task_id。 - 轮询状态（
GET）： 用task_id查询任务状态，持续轮询直到task_status为"success"或"error"。
- API Playground
用官方在线调试台交互式地体验与测试接口：
- 鉴权
- 请在请求头中以 Bearer Token 方式带上您的 API 密钥：
Authorization: Bearer YOUR_API_KEY
API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。
- 上传图片
您可以把文件直接上传到服务器，也可以在 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）提供遮挡蒙版图，用于微调分割效果。
- 创建 AI 项链虚拟试戴任务并轮询结果
图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 success 或 error。
- 创建任务接口
POST /s2s/v2.0/task/2d-vto/necklace- 轮询接口
GET /s2s/v2.0/task/2d-vto/necklace/{task_id}- AI 项链虚拟试戴规格
支持的项链图视角 项链图需为佩戴状态的正面图，并去除背景。
支持的自拍图视角 正脸自拍，颈部清晰可见、无遮挡。头部水平旋转角度支持 20 度以内。头部比例要协调，颈部宽度至少占图片宽度的 15%。
necklace_wearing_location: 由两个点组成的数组（可选） 指定在照片中要佩戴项链的目标位置。 默认值：null（使用引擎默认值）
necklace_shadow_intensity: float（0.0 到 1.0） 控制阴影强度： 0.0 表示无阴影 1.0 表示最大阴影 默认值：0.15
necklace_ambient_light_intensity: float（0.0 到 1.0） 定义光线在多大程度上参考自拍图： 0.0 忽略自拍图的光线 1.0 完全匹配自拍图的光线与阴影渲染 默认值：1.0
necklace_anchor_point: 像素坐标下由两个点组成的数组（可选） 指定商品图中项链链条左右两端可见处的锚点，用于对齐。 默认值：null（使用引擎默认值）
- 支持的格式与尺寸
| 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 |