# 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
    1.  **List look templates:** Listing available AI look templates
    1.  **Start Task (`POST`):** Submit your image id/URL and a look ``template_id``.
    1.  **Retrieve Task ID:** Capture the `task_id` from the response.
    1.  **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-look-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/)

---

* 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/look-vto
```

Alternatively, skip this step if you already have a public image URL.

---

* 2. 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

```javascript
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=13045969587275114');
xhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');

xhr.send(data);
```

   * Sample Successful Response

```json
{
  "status": 200,
  "data": {
    "templates": [
      {
        "id": "good_template_001",
        "thumb": "thumbnail preview image URL",
        "title": "Berry Smooth",
        "category_name": "Daily"
      }
    ],
    "next_token": 13045969587275114
  }
}
```

> **Note:** Use the `id` value (`template_id`) when creating the Look VTO task.

---

* 3. 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

```javascript
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

```json
{
  "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.

---

## File Specs & Errors
* 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</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 |

---


License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

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'.

Type: http
Scheme: bearer

## Download OpenAPI description

[AI Look Virtual Try-On](https://docs.perfectcorp.com/_bundle/reference/ai_look_vto.yaml)

## V1.0

Generate virtual try-on experiences for full looks from uploaded images using AI processing.

### Create a new file.

 - [POST /s2s/v2.0/file/look-vto](https://docs.perfectcorp.com/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1file~1look-vto/post.md): To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features.

### List predefined templates.

 - [GET /s2s/v2.0/task/template/look-vto](https://docs.perfectcorp.com/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get.md)

### Run an AI Look Virtual Try On task.

 - [POST /s2s/v2.0/task/look-vto](https://docs.perfectcorp.com/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post.md): This endpoint initiates the look virtual try-on process using a template and source image. The task will be processed asynchronously, and you can check its status using the task_id returned in this response.

### Check the status of a AI Look Virtual Try On task.

 - [GET /s2s/v2.0/task/look-vto/{task_id}](https://docs.perfectcorp.com/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1%7Btask_id%7D/get.md)