openapi: 3.0.0 info: title: AI Watch Virtual Try On description: "# Overview\nVirtually Try-On AR Watches with Ease! Only One 2D Image Needed.\n\nWith just\ \ a single 2D image upload, users can instantly try on top-notch watches virtually using our innovative\ \ AR-Watches App. This unique feature sets us apart in the world of e-commerce, making it easier than\ \ ever for customers to experience your products.\n\n## Integration Guide\nThis guide walks you through:\n\ \n* **Endpoint:** `/s2s/v2.0/task/2d-vto/watch`\n* **Authentication:** All requests require an\ \ `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a wrist image:** Uploading\ \ an image or provide a valid image URL of your wrist\n 1. **Prepare a watch image:** Uploading\ \ an image or provide a valid image URL of a watch product\n 1. **Fire an AI task and Retrieve\ \ Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id`\ \ to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"\ `.\n\n---\n\n* API Playground\n\nInteractively explore and test the API using our official playground:\n\ \n**API Playground:**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-watch-virtual-try-on/)\n\ \n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n\ \ ```\n Authorization: Bearer YOUR_API_KEY\n ```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\ \n\n* 1. Upload an Image\n\nYou may upload a file directly to the server or provide a valid image\ \ URL in the VTO task payload.\n\n * Upload Endpoint\n\n```\nPOST /s2s/v2.0/file\n```\n\nAlternatively,\ \ skip this step if you already have a public image URL.\n\nYou 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.\n\ \nYou must also provide another watch 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`.\n\nThe AI engine supports automatic background\ \ removal for your watch product image. However, you may provide an occlusion mask image file for\ \ either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the watch product (`refmsk_file_ids`\ \ or `refmsk_file_urls`) to fine-tune the segmentation.\n\n---\n\n* 2. Create a Watch VTO Task and\ \ Poll for Results\n\nOnce 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`.\n\n\ \ * Create Task Endpoint\n\n```\nPOST /s2s/v2.0/task/2d-vto/watch\n```\n\n * Polling Endpoint\n\ \n```\nGET /s2s/v2.0/task/2d-vto/watch/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Watch\ \ Virtual Try-On Specification\n\n**Supported Watch View**\nA watch image in a clear front view with\ \ the watch face unobstructed. The strap should be cropped to resemble a realistic wearing length.\n\ \n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_product_01_aab8053028_50ab7fe9a5.jpg)\n\ \n**Supported Wrist View**\nThe back of the wrist should be fully visible with all five fingers clearly\ \ shown and without any occlusion.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/watch_and_bracelet_user_01_09f16603cb_878dc89179.jpg)\n\ \n**watch\\_wearing\\_location: float (āˆ’0.3 to 1.0)**\nIndicates the position along the wrist:\nāˆ’0.3\ \ represents near the main wrist joint\n1.0 represents far from the main wrist joint\nDefault value:\ \ null (use engine default)\n\n![watch_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/bracelet_wearing_location_01ac0a048e.jpg)\n\ \n**watch\\_shadow\\_intensity: float (0.0 to 1.0)**\nControls the strength of the shadow:\n0.0 represents\ \ no shadow\n1.0 represents maximum shadow\nDefault value: 0.15\n\n**watch\\_ambient\\_light\\_intensity:\ \ float (0.0 to 1.0)**\nDefines the extent to which lighting references the target hand image:\n0.0\ \ ignores the hand image lighting\n1.0 fully matches the hand image lighting and shadow rendering\n\ Default value: 1.0\n\n**Watch Anchor Points: array of 4 points in pixel coordinate (optional)**\n\ The first two points mark the beginning and end of the strap when worn.\nThe remaining two points\ \ mark the upper and lower edges of the watch case.\n\n![watch_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Product_anchors_ece6851c88.jpg)\n\ \n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported\ \ Formats|\n| ---- | ---- | ---- | ---- |\n|AI Watch Virtual Try-On|long side <= 4096 |< 10MB|jpg/jpeg/png|\n\ \n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| RUNTIME_ERROR | An unexpected error\ \ occurred duwatch runtime |\n| PHOTO_DETECTION_FAIL | The user photo could not be processed correctly,\ \ for example no hand detected |\n| OBJECT_DETECTION_FAIL | The object photo could not be processed\ \ correctly, for example no product detected |\n| PHOTO_CHECK_INVALID | The pose or size of the user\ \ photo is invalid |\n| INPUT_ERROR | The input file format is incorrect |\n| INPUT_MAIN_IMAGE_EMPTY\ \ | A user image is required |\n\n\n* Environment & Dependency\n\n| Sample Code Language / Tool |\ \ Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58 (modern\ \ TLS/HTTP support)
- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18\ \ (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari\ \ >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On\ \ + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java\ \ | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## JS Camera Kit\n{% partial\ \ file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed\ \ |\n|---|---|\n| AI Watch Virtual Try-On V1.0 | 1 Unit for Single-item wear |\n\n---\n" version: '' termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api contact: email: YouCamOnlineEditor_API@perfectcorp.com license: name: Privacy policy url: https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api servers: - url: https://yce-api-01.makeupar.com tags: - name: V1.0 description: Generate virtual try-on experiences for watches from uploaded images using AI processing, supporting alignment and shadow parameters. paths: /s2s/v2.0/task/2d-vto/watch: post: summary: Run an AI 2D Virtual Try On Watch task. description: 'This endpoint initiates the watch 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 wearing location. The task will be processed asynchronously, and you can check its status using the task_id returned in this response. ' tags: - V1.0 security: - BearerAuthenticationV2: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WatchRunTaskV2' responses: '200': description: Successful execution of the task content: application/json: schema: $ref: '#/components/schemas/BasicRunTaskResponseV2' '400': description: Failed execution of task content: application/json: schema: allOf: - $ref: '#/components/schemas/RunError' '401': $ref: '#/components/responses/InvalidApiKey' '429': $ref: '#/components/responses/TooManyRequests' /s2s/v2.0/task/2d-vto/watch/{task_id}: get: summary: Check the status of a AI 2D Virtual Try On Watch task. tags: - V1.0 security: - BearerAuthenticationV2: [] parameters: - name: task_id in: path required: true schema: type: string example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe description: ID of task to check responses: '200': description: Successful check of the task status content: application/json: schema: $ref: '#/components/schemas/TaskStatusResponseV2' '400': $ref: '#/components/responses/InvalidTaskId' '401': $ref: '#/components/responses/InvalidApiKey' '500': $ref: '#/components/responses/TaskTimeout' components: securitySchemes: BearerAuthenticationV2: type: http scheme: bearer description: 'Use the standard ''Bearer authentication''. Put your ''API Key'' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is '' '' a space between ''Bearer'' and the ''YOUR_API_KEY''.' schemas: WatchRunTaskV2: allOf: - $ref: '#/components/schemas/2dVtoRunTaskV2' - type: object properties: object_infos: type: array items: type: object properties: parameter: type: object properties: watch_need_remove_background: type: boolean description: Whether the watch image needs background removal. default: true example: true watch_anchor_point: type: array description: 'First 2 points mark the strap end when worn. Remaining 2 points mark the upper & lower edges of watch case.
Type: 4x2 list of integers
Range: 4 (x, y) pixel coordinates
Default: null (use engine default)' default: null example: null minItems: 4 maxItems: 4 items: type: array minItems: 2 maxItems: 2 items: type: integer watch_wearing_location: type: number description: 'Defines the placement of the watch on the wrist in the user photo.
Range: -0.3 ~ 1.0 (0 = closest to the wrist joint)
(smaller number = placed close to the palm
larger number = placed further away from the wrist)
Default: null (use engine default)' minimum: -0.3 maximum: 1 default: null example: null watch_shadow_intensity: type: number description: Shadow intensity applied to the watch (higher = darker shadow). minimum: 0 maximum: 1 default: 0.3 example: 0.3 watch_ambient_light_intensity: type: number description: Ambient light adjustment intensity for the watch. minimum: 0 maximum: 1 default: 1 example: 1 BasicRunTaskV2SrcFileUrl: type: object required: - src_file_url properties: src_file_url: type: string description: Url of the file to run task. The url should be publicly accessible. example: https://example.com/selfie.jpg 2dVtoRunTaskV2SrcmskFileUrl: type: object properties: srcmsk_file_url: type: string description: Url of the source mask file to run task. The url should be publicly accessible. example: https://example.com/src_mask.jpg 2dVtoRunTaskV2RefFileUrls: type: object required: - ref_file_urls properties: ref_file_urls: type: array description: Url of the reference file to run task. The url should be publicly accessible. example: - https://example.com/vto_sku.jpg items: type: string 2dVtoRunTaskV2RefmskFileUrls: type: object properties: refmsk_file_urls: type: array description: Url of the reference mask file to run task. The url should be publicly accessible. example: - https://example.com/vto_sku_mask.jpg items: type: string 2dVtoRunTaskV2RefFileIds: type: object required: - ref_file_ids properties: ref_file_ids: type: array description: ID of the reference file file to run task. File ID from upload file API. example: - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE= items: type: string 2dVtoRunTaskV2RefmskFileIds: type: object properties: refmsk_file_ids: type: array description: ID of the reference mask file file to run task. File ID from upload file API. example: - pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE= items: type: string BasicRunTaskV2SrcFileId: type: object required: - src_file_id properties: src_file_id: type: string description: ID of file to run task. File ID from upload file API. example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE= 2dVtoRunTaskV2SrcmskFileId: type: object properties: srcmsk_file_id: type: string description: ID of the source mask file to run task. File ID from upload file API. example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE= 2dVtoRunTaskV2SrcInfo: type: object required: - source_info properties: source_info: type: object description: Contain source photo informations. properties: name: type: string description: The source url or File ID. example: https://example.com/selfie.jpg mask_name: type: string description: The source mask url or File ID. example: https://example.com/src_mask.jpg required: - name 2dVtoRunTaskV2ObjInfos: type: object required: - object_infos properties: object_infos: type: array items: type: object description: Contain several object informations in this list. properties: name: type: string description: The reference url or File ID. Indicate which reference product image should be matched. example: https://example.com/vto_sku.jpg mask_name: type: string description: The reference mask url or File ID. Indicate which reference product image should be matched. example: https://example.com/vto_sku_mask.jpg required: - name 2dVtoRunTaskV2: allOf: - anyOf: - allOf: - title: Run task with src file url & srcmsk file url & ref file urls & refmsk file urls - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl' - $ref: '#/components/schemas/2dVtoRunTaskV2SrcmskFileUrl' - $ref: '#/components/schemas/2dVtoRunTaskV2RefFileUrls' - $ref: '#/components/schemas/2dVtoRunTaskV2RefmskFileUrls' - allOf: - title: Run task with src file url & srcmsk file url & ref file IDs & refmsk file IDs - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl' - $ref: '#/components/schemas/2dVtoRunTaskV2SrcmskFileUrl' - $ref: '#/components/schemas/2dVtoRunTaskV2RefFileIds' - $ref: '#/components/schemas/2dVtoRunTaskV2RefmskFileIds' - allOf: - title: Run task with src file ID & srcmsk file ID & ref file urls & refmsk file urls - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId' - $ref: '#/components/schemas/2dVtoRunTaskV2SrcmskFileId' - $ref: '#/components/schemas/2dVtoRunTaskV2RefFileUrls' - $ref: '#/components/schemas/2dVtoRunTaskV2RefmskFileUrls' - allOf: - title: Run task with src file ID & srcmsk file ID & ref file IDs & refmsk file IDs - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId' - $ref: '#/components/schemas/2dVtoRunTaskV2SrcmskFileId' - $ref: '#/components/schemas/2dVtoRunTaskV2RefFileIds' - $ref: '#/components/schemas/2dVtoRunTaskV2RefmskFileIds' - $ref: '#/components/schemas/2dVtoRunTaskV2SrcInfo' - $ref: '#/components/schemas/2dVtoRunTaskV2ObjInfos' BasicRunTaskResponseV2: type: object properties: status: type: integer description: Response status example: 200 data: type: object properties: task_id: type: string description: ID of this task. Task result is valid to query by this ID for 24 hours. example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe RunError: type: object properties: status: type: integer description: Response status example: 400 error: type: string description: Error message example: The operation could not be completed error_code: type: string enum: - InvalidParameters - CreditInsufficiency - InvalidStyleGroup - InvalidStyle - BadRequest description: "Error code:\n * InvalidParameters - Invalid request parameters\n * CreditInsufficiency\ \ - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup\ \ - Invalid style group id\n * InvalidStyle - Invalid style id\n" EngineErrorCode: type: string nullable: true enum: - error_exceed_max_image_size - exceed_max_filesize - invalid_parameter - error_download_image - error_download_mask - error_decode_image - error_decode_mask - error_nsfw_content_detected - error_no_face - error_pose - error_face_parsing - error_inference - exceed_nsfw_retry_limits - error_upload - unknown_internal_error description: 'Errors: - \`error_exceed_max_image_size\` - Input image size exceeds the maximum limit - \`exceed_max_filesize\` - Input file size exceeds the maximum limit - \`invalid_parameter\` - Invalid parameter value - \`error_download_image\` - Download source image error - \`error_download_mask\` - Download mask image error - \`error_decode_image\` - Decode source image error - \`error_decode_mask\` - Decode mask image error - \`error_nsfw_content_detected\` - NSFW content detected in source image - \`error_no_face\` - No face detected on source image - \`error_pose\` - Failed to detect pose on source image - \`error_face_parsing\` - Failed to do face segmentation on source image - \`error_inference\` - Inference pipeline error - \`exceed_nsfw_retry_limits\` - Exceed the retry limits to avoid generated NSFW image - \`error_upload\` - Upload result image error - \`unknown_internal_error\` - Others ' TaskStatusResponseBodySingleUrlResultsV2: type: object properties: url: type: string description: URL to download this result. Valid for 2 hours example: https://example.com/sample-result-url TaskStatusResponseV2: type: object properties: status: type: integer description: Response status example: 200 data: type: object properties: task_status: type: string enum: - running - success - error description: Status of this task error: $ref: '#/components/schemas/EngineErrorCode' error_message: type: string description: Detailed description of error results: null $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2' responses: InvalidApiKey: description: Invalid or missing API key content: application/json: schema: type: object properties: status: type: integer example: 401 description: Response status error: type: string example: Invalid API key TooManyRequests: description: Too many requests content: application/json: schema: type: object properties: status: type: integer example: 429 description: Response status error: type: string example: Too many requests InvalidTaskId: description: Invalid task ID content: application/json: schema: type: object properties: status: type: integer example: 400 description: Response status error: type: string example: Invalid task ID TaskTimeout: description: Task execution timeout content: application/json: schema: type: object properties: status: type: integer example: 500 description: Response status error: type: string example: Task execution timed out