Skip to content

AI Look Virtual Try-On

Overview

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.

Integration Guide

This guide walks you through:

  • Endpoint: /s2s/v2.0/task/look-vto
  • Authentication: All requests require an Authorization: Bearer <TOKEN>
  • Workflow:
    1. Prepare a selfie: Uploading an image or provide a valid image URL
    2. List look templates: Listing available AI look templates
    3. Start Task (POST): Submit your image id/URL and a look template_id.
    4. Retrieve Task ID: Capture the task_id from the response.
    5. 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:


  • 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/.

    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.


    1. 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
ParameterDescription
page_sizeNumber of items per page
starting_tokenToken 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 id value (template_id) when creating the Look VTO task.


    1. 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
StepDescription
1. Upload ImageUpload directly or provide an image URL.
2. List Look TemplatesRetrieve available look styles with IDs.
3. Create VTO TaskSubmit image URL + template ID.
4. Poll for CompletionRetrieve the final result image URL.

This workflow ensures a reliable, developer-friendly integration for real-time virtual makeup try-on experiences.


File Specs & Errors

  • Supported Formats & Dimensions
AI FeatureSupported DimensionsSupported File SizeSupported Formats
AI Look Virtual Try-Onlong side < 1920, face width >= 100< 10MBjpg/jpeg/png
  • Error Codes
Error CodeDescription
error_below_min_image_sizethe size of the source image is smaller than minimum (expect: width >= 100px, height >= 100px)
error_exceed_max_image_sizethe size of the source image is larger than maximum (expect: width < 1920px, height < 1080px)
error_face_position_invalidPlease ensure your entire face is fully visible within the image
error_face_position_too_smallThe detected face is too small. Move closer to the camera
error_face_position_out_of_boundaryThe face is too large or partially outside the image frame. Adjust your position
error_face_angle_invalidThe 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 / ToolRecommended 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
PHPPHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json
PythonPython >= 3.10 (for f-strings), requests >= 2.20.0
JavaJava 11+ (for HttpClient), Jackson Databind >= 2.12.0

Unit Consumption

AI FeatureUnit Consumed
AI Look Virtual Try-On V1.02

Download OpenAPI description
Languages
Servers
https://yce-api-01.makeupar.com