openapi: 3.0.0
info:
title: AI Earrings Virtual Try On
description: "# Overview\nThe Ultimate AI Earring Virtual Try-On\nTop AI ear piercing simulator for\
\ virtual earring try-on and virtual piercing try-on\n\nCreate realistic and dynamic earrings vitual\
\ try-on from a 2D image, no expensive 3D modelling required. Our advanced algorithms create lifelike\
\ virtual try-on earring SKUs with sophisticated lighting effects and physically accurate motions.\n\
\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/task/2d-vto/earring`\n\
* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n\
\ 1. **Prepare a selfie image:** Uploading an image or provide a valid image URL\n 2. **Prepare\
\ an earring image:** Uploading an image or provide a valid image URL of an earring product\n 3.\
\ **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 4. **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-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-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 earring 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 earring product image. However, you may provide an occlusion mask image file for\
\ either your hand (`srcmsk_file_id` or `srcmsk_file_url`) or the earring product (`refmsk_file_ids`\
\ or `refmsk_file_urls`) to fine-tune the segmentation.\n\n---\n\n* 2. Create a Earring 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/earring\n```\n\n * Polling Endpoint\n\
\n```\nGET /s2s/v2.0/task/2d-vto/earring/{task_id}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Earring\
\ Virtual Try-On Specification\n\n**Supported Earring Reference Image**\n* A single earring image\
\ in a clear front view without obstruction.\n* All parameters (including anchor points, masks,\
\ location, etc.) apply **only** when the reference image shows a **single earring** being worn.\n\
* If the try-on reference image shows **both earrings**, all parameters will use **auto-detection\
\ and default settings**.\n* When trying on **both earrings**, the clearer ear will be used as the\
\ source, and the other ear will be generated by mirroring it.\n\n\
\ \n\
\n**Supported Selfie View**\n\n* The AI Earring Virtual Try-On supports front-facing images, but\
\ the best results are achieved with side-facing images.\n\n\n\
\n**earring\\_wearing\\_location: integer array of size 2**\nSpecifies the target location in the\
\ selfie where the earring should be placed.\nDefault value: null (engine default)\n\n\n\
\n**earring\\_scale: number greater than 0**\nControls the earring size in centimetres.\nDefault value:\
\ null (engine default)\n\n**earring\\_is\\_right\\_ear: boolean**\nIndicates whether the earring\
\ is worn on the right ear. By default, it is worn on the right ear.\nDefault value: true\n\n**earring\\\
_occluded\\_type: number (Enum: 0, 1, 2)**\nSpecifies the occlusion type:\n0 means auto-detect\n1\
\ means occluded\n2 means no occlusion\nDefault value: 0\n\n**earring\\_shadow\\_intensity: float\
\ (0.0 to 1.0)**\nControls the shadow strength:\n0.0 represents no shadow\n1.0 represents maximum\
\ shadow\nDefault value: 0.15\n\n**earring\\_ambient\\_light\\_intensity: float (0.0 to 1.0)**\nDefines\
\ how much the lighting references the selfie image:\n0.0 ignores the selfie image lighting\n1.0 fully\
\ matches the selfie image lighting and shadow rendering\nDefault value: 1.0\n\n**earring\\_anchor\\\
_point: array of one point in pixel coordinate (optional)**\nSpecifies the wearing position in the\
\ earring product image.\nDefault value: null (engine default)\n\n\n\
\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported\
\ Formats|\n| ---- | ---- | ---- | ---- |\n|AI Earring 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 duearring 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 Earrings Virtual Try-On V1.0 | 1 Unit for Single-item wear
2 Units for Stacked\
\ 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 earrings from uploaded images using AI processing,
supporting alignment and shadow parameters.
paths:
/s2s/v2.0/task/2d-vto/earring:
post:
summary: Run an AI 2D Virtual Try On Earring task.
description: 'This endpoint initiates the earring 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/EarringRunTaskV2'
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/earring/{task_id}:
get:
summary: Check the status of a AI 2D Virtual Try On Earring 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:
EarringRunTaskV2:
allOf:
- $ref: '#/components/schemas/2dVtoRunTaskV2'
- type: object
properties:
object_infos:
type: array
items:
type: object
properties:
parameter:
type: object
properties:
earring_need_remove_background:
type: boolean
description: Whether the earring image needs background removal.
default: true
example: true
earring_anchor_point:
type: array
description: 'The anchor point of the earring image, used for alignment.
Type:
list of 2 integers
Range: [x, y] (pixel coordinates)
Default: null (use
engine default)'
default: null
example: null
minItems: 2
maxItems: 2
items:
type: integer
earring_wearing_location:
type: array
description: 'The target location of photo where the earring should be placed.
Type:
list of 2 integers
Range: [x, y] (pixel coordinates)
Default: null (use
engine default)'
default: null
example: null
minItems: 2
maxItems: 2
items:
type: integer
earring_scale:
type: number
description: 'Controls the earring’s size in centimeters.
Default: null (use
engine default)'
default: null
minimum: 0
exclusiveMinimum: true
example: null
earring_is_right_ear:
type: boolean
description: Whether the earring is worn in right ear, defaultly is worn in right
ear.
default: true
example: true
earring_occluded_type:
type: number
description: Which occluded type the earring is. 0 means auto-detect, 1 means occluded
type, 2 means no.
default: 0
enum:
- 0
- 1
- 2
example: 0
earring_shadow_intensity:
type: number
description: Shadow intensity applied to the earring (higher = darker shadow).
minimum: 0
maximum: 1
default: 0.5
example: 0.5
earring_ambient_light_intensity:
type: number
description: Ambient light adjustment intensity for the earring.
minimum: 0
maximum: 1
default: 0.5
example: 0.5
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