# AI Necklace Virtual Try On # Overview Luxurious Look and Feel with State-of-the-Art Virtual Try-On for Necklace Precise AI neck and clavicle tracking gives users an ultra-realistic AR try-on experience, recreating the luxurious look and feel of physical necklace sampling. Create realistic and dynamic necklace vitual try-on from a 2D image, no expensive 3D modelling required. Our advanced algorithms create lifelike virtual try-on necklace SKUs with sophisticated lighting effects and physically accurate motions. ## Integration Guide This guide walks you through: * **Endpoint:** `/s2s/v2.0/task/2d-vto/necklace` * **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY` * **Workflow:** 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL 2. **Prepare a necklace image:** Uploading an image or provide a valid image URL of a necklace product 3. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response. 4. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `"success"` or `"error"`. --- * API Playground Interactively explore and test the API using our official playground: **API Playground:** [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/) --- * Authentication - Include your API key in the request header using **Bearer Token**: ``` Authorization: Bearer YOUR_API_KEY ``` You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/. * 1. Upload an Image You may upload a file directly to the server or provide a valid image URL in the VTO task payload. * Upload Endpoint ``` POST /s2s/v2.0/file ``` Alternatively, skip this step if you already have a public image URL. You may upload a file directly to the URL provided in the response from the File API and then use the corresponding `src_file_id` returned by the File API to invoke the AI task later. Or provide a valid image URL in the VTO task payload as `src_file_url`. The `src_file_id` or `src_file_url` will serve as the virtual try-on target. You must also provide another necklace product image as a reference using `ref_file_ids` or `ref_file_urls` to be applied to your `src_file_id` or `src_file_url`. The AI engine supports automatic background removal for your selfie. However, you may provide an occlusion mask image file for your neck (`srcmsk_file_id` or `srcmsk_file_url`) to fine-tune the segmentation. --- * 2. Create a Necklace VTO Task and Poll for Results Once you have an image and a template ID, create a task. The API processes the request asynchronously. You must poll the task status until it reaches `success` or `error`. * Create Task Endpoint ``` POST /s2s/v2.0/task/2d-vto/necklace ``` * Polling Endpoint ``` GET /s2s/v2.0/task/2d-vto/necklace/{task_id} ``` --- ## File Specs & Errors * AI Necklace Virtual Try-On Specification **Supported Necklace View** A front-facing image of the necklace worn, with the background removed. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/necklace_product_01_124206cfbe_3993a2128d.jpg) **Supported Selfie View** A front-facing selfie with the neck clearly visible and unobstructed. Horizontal head rotation is supported within 20 degrees. The head size should be proportionate, and the neck width should occupy at least 15 per cent of the image width. ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Necklace_restriction_83410fb6c1.png) **necklace\_wearing\_location: array of two points (optional)** Specifies the target locations in the photo where the necklace should be placed. Default: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_874264bb70.jpg) **necklace\_shadow\_intensity: float (0.0 to 1.0)** Controls the shadow strength: 0.0 represents no shadow 1.0 represents maximum shadow Default value: 0.15 **necklace\_ambient\_light\_intensity: float (0.0 to 1.0)** Defines how much the lighting references the selfie image: 0.0 ignores the selfie image lighting 1.0 fully matches the selfie image lighting and shadow rendering Default value: 1.0 **necklace\_anchor\_point: array of two points in pixel coordinate (optional)** Specifies the anchor points for the left and right visible ends of the necklace chain in the product image, used for alignment. Default: null (engine default) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_7f9b254ca4.jpg) --- * Supported Formats & Dimensions |AI Feature|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Necklace Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png| * Error Codes |Error Code|Description| | ---- | ---- | | RUNTIME_ERROR | An unexpected error occurred dunecklace runtime | | PHOTO_DETECTION_FAIL | The user photo could not be processed correctly, for example no neck detected | | OBJECT_DETECTION_FAIL | The object photo could not be processed correctly, for example no product detected | | PHOTO_CHECK_INVALID | The pose or size of the user photo is invalid | | INPUT_ERROR | The input file format is incorrect | | INPUT_MAIN_IMAGE_EMPTY | A user image is required | * Environment & Dependency | Sample Code Language / Tool | Recommended Runtime Versions | |---|---| | 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 {% partial file="/_partials/js-camera-kit.md" /%} --- ## Unit Consumption | AI Feature | Unit Consumed | |---|---| | AI Necklace Virtual Try-On V1.0 | 1 Unit for Single-item wear | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 [object Object] Type: http Scheme: bearer ## Download OpenAPI description - [AI Necklace Virtual Try On](https://docs.perfectcorp.com/_bundle/reference/ai_necklace.yaml) ## V1.0 - [POST /s2s/v2.0/task/2d-vto/necklace](https://docs.perfectcorp.com/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace/post.md): This endpoint initiates the necklace virtual try-on process. You must provide source file(s) and reference image(s) (via URL or File ID), along with specific parameters for alignment, shadowing, and w - [GET /s2s/v2.0/task/2d-vto/necklace/{task_id}](https://docs.perfectcorp.com/reference/ai_necklace/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1necklace~1%7Btask_id%7D/get.md)