Skip to content
AI Ring Virtual Try-On/
/
Run an AI 2D Virtual Try...

Run an AI 2D Virtual Try On Ring task.

Request

AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details.

If webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is success or error.

Security
BearerAuthenticationV2
Bodyapplication/jsonrequired
Any of:
source_infoobjectrequired

Contain source photo informations.

object_infosArray of objectsrequired
src_file_urlstringrequired

Url of the file to run task. The url should be publicly accessible.

Example:"https://example.com/selfie.jpg"
srcmsk_file_urlstring

Url of the source mask file to run task. The url should be publicly accessible.

Example:"https://example.com/src_mask.jpg"
ref_file_urlsArray of stringsrequired

Url of the reference file to run task. The url should be publicly accessible.

Example:
[
  "https://example.com/vto_sku.jpg"
]
refmsk_file_urlsArray of strings

Url of the reference mask file to run task. The url should be publicly accessible.

Example:
[
  "https://example.com/vto_sku_mask.jpg"
]
POST
/s2s/v2.0/task/2d-vto/ring
curl -i -X POST \
  https://yce-api-01.makeupar.com/s2s/v2.0/task/2d-vto/ring \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "src_file_url": "https://example.com/selfie.jpg",
    "srcmsk_file_url": "https://example.com/src_mask.jpg",
    "ref_file_urls": [
      "https://example.com/vto_sku.jpg"
    ],
    "refmsk_file_urls": [
      "https://example.com/vto_sku_mask.jpg"
    ],
    "source_info": {
      "name": "https://example.com/selfie.jpg",
      "mask_name": "https://example.com/src_mask.jpg"
    },
    "object_infos": [
      {
        "name": "https://example.com/vto_sku.jpg",
        "mask_name": "https://example.com/vto_sku_mask.jpg",
        "parameter": {
          "ring_need_remove_background": true,
          "ring_anchor_point": null,
          "ring_wearing_finger": null,
          "ring_wearing_location": null,
          "ring_shadow_intensity": 0.15,
          "ring_ambient_light_intensity": 1
        }
      }
    ]
  }'

Responses

Successful execution of the task

Bodyapplication/json
statusinteger

Response status

Example:200
dataobject
Response
{
  "status": 200,
  "data": {
    "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
  }
}