AI Look Virtual Try-On
The AI Look Virtual Try-On API provides a complete workflow for applying professionally designed facial looks to user photos. Each look is crafted by beauty experts and can be applied instantly via API.
This guide walks you through:
- Endpoint:
/s2s/v2.0/task/look-vto - Authentication: All requests require an
Authorization: Bearer <TOKEN> - Workflow:
- Prepare a selfie: Uploading an image or provide a valid image URL
- List look templates: Listing available AI look templates
- Start Task (
POST): Submit your image id/URL and a looktemplate_id. - Retrieve Task ID: Capture the
task_idfrom the response. - Poll Status (
GET): Use thetask_idto check the status of the task. Continue polling untiltask_statusis"success"or"error".
- API Playground
Interactively explore and test the API using our official playground:
- Authentication
- Include your API key in the request header using Bearer Token:
Authorization: Bearer <API Key>
You can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.
- 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/fileAlternatively, skip this step if you already have a public image URL.
- List Available Look Styles
Retrieve all AI makeup look templates available for virtual try-on.
- Endpoint
GET /s2s/v2.0/task/template/look-vto- Query Parameters
| Parameter | Description |
|---|---|
page_size | Number of items per page |
starting_token | Token for pagination (optional) |
- Sample Javascript Request
const data = null;
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener('readystatechange', function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');
xhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');
xhr.send(data);- Sample Successful Response
{
"status": 200,
"data": {
"templates": [
{
"id": "good_template_001",
"thumb": "thumbnail preview image URL",
"title": "Berry Smooth",
"category_name": "Daily"
}
],
"next_token": 73a3c9e69b89
}
}Note: Use the
idvalue (template_id) when creating the Look VTO task.
- Create a Look 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/look-vto- Polling Endpoint
GET /s2s/v2.0/task/look-vto/{task_id}- Sample JavaScript Implementation
const BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';
const START_METHOD = 'POST';
const HEADERS = {
"Content-Type": "application/json",
"Authorization": "Bearer FT6Xa7xuU1SBU2ZW6pdAAUh9D093kuX3"
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function startTask() {
const init = {
method: START_METHOD,
headers: HEADERS,
body: JSON.stringify({
"src_file_url": "https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg",
"template_id": "all_rosy_chic"
})
};
const res = await fetch(BASE_URL, init);
if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);
const payload = await res.json().catch(() => ({}));
const taskId = payload?.data?.task_id;
if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));
console.log('[startTask] Task started, id =', taskId);
return taskId;
}
async function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const pollUrl = `${BASE_URL}/${taskId}`;
const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });
if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);
const payload = await res.json().catch(() => ({}));
const status = payload?.data?.task_status;
console.log(`[pollTask] Attempt ${attempt} status = ${status}`);
if (status === 'success') {
console.log('[pollTask] Success results:', payload?.data?.results);
return payload;
}
if (status === 'error') {
throw new Error('Task failed: ' + JSON.stringify(payload));
}
await sleep(intervalMs);
}
throw new Error('Polling timeout: Max attempts exceeded');
}
(async () => {
try {
const taskId = await startTask();
const final = await pollTask(taskId);
console.log('[main] Final response:', final);
} catch (e) {
console.error('[main] Flow error:', e);
}
})();- Sample Success Response
{
"status": 200,
"data": {
"results": {
"url": "https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?..."
},
"task_status": "success"
}
}The results.url field contains the final rendered virtual makeup image.
- Summary
| Step | Description |
|---|---|
| 1. Upload Image | Upload directly or provide an image URL. |
| 2. List Look Templates | Retrieve available look styles with IDs. |
| 3. Create VTO Task | Submit image URL + template ID. |
| 4. Poll for Completion | Retrieve the final result image URL. |
This workflow ensures a reliable, developer-friendly integration for real-time virtual makeup try-on experiences.
- Supported Formats & Dimensions
| AI Feature | Supported Dimensions | Supported File Size | Supported Formats |
|---|---|---|---|
| AI Look Virtual Try-On | long side < 1920, face width >= 100 | < 10MB | jpg/jpeg/png |
- Error Codes
| Error Code | Description |
|---|---|
| error_below_min_image_size | the size of the source image is smaller than minimum (expect: width >= 100px, height >= 100px) |
| error_exceed_max_image_size | the size of the source image is larger than maximum (expect: width < 1920px, height < 1080px) |
| error_face_position_invalid | Please ensure your entire face is fully visible within the image |
| error_face_position_too_small | The detected face is too small. Move closer to the camera |
| error_face_position_out_of_boundary | The face is too large or partially outside the image frame. Adjust your position |
| error_face_angle_invalid | The face angle is incorrect. For front-facing photos, keep your head within 10°. For side-facing photos, ensure more than 15°. |
- 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 |