跳转到内容
AI 完整妝容虛擬試妝/
/
整合指南

AI 完整妝容虛擬試妝

概述

AI 完整妝容虛擬試妝 API 提供完整的工作流程，將專業設計的臉部造型套用到使用者照片。每個造型都由美妝專家打造，可透過 API 即刻套用。

整合指南

本指南將引導您完成：

  • 端點： /s2s/v2.0/task/look-vto
  • 認證： 所有請求都需要 Authorization: Bearer <TOKEN>
  • 工作流程：
    1. 準備自拍： 上傳圖片，或提供有效的圖片網址
    2. 列出造型範本： 列出可用的 AI 完整妝容範本
    3. 啟動任務（POST）： 提交您的圖片 id/網址與造型 template_id。
    4. 取得任務 ID： 從回應中取得 task_id。
    5. 輪詢狀態（GET）： 使用 task_id 查詢任務狀態。持續輪詢，直到 task_status 為 "success" 或 "error"。
  • API Playground

使用我們的官方 playground 進行互動式探索與測試：

API Playground： http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/

  • 認證
  • 使用 Bearer Token 將您的 API key 納入請求標頭：
    Authorization: Bearer <API Key>

您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。

    1. 上傳圖片

您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。

  • 上傳端點
POST /s2s/v2.0/file

或者，若您已有公開的圖片網址，可跳過此步驟。

    1. 列出可用的造型風格

取得所有可用於虛擬試妝的 AI 彩妝造型範本。

  • 端點
GET /s2s/v2.0/task/template/look-vto
  • 查詢參數
參數說明
page_size每頁的項目數量
starting_token用於分頁的令牌（選填）
  • 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=73a3c9e69b89');
xhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');

xhr.send(data);
  • 成功回應範例
{
  "status": 200,
  "data": {
    "templates": [
      {
        "id": "good_template_001",
        "thumb": "縮略圖預覽圖片網址",
        "title": "Berry Smooth",
        "category_name": "Daily"
      }
    ],
    "next_token": 73a3c9e69b89
  }
}

注意： 在建立造型 VTO 任務時，使用 id 值（template_id）。

    1. 建立造型 VTO 任務並輪詢結果

當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 success 或 error。

  • 建立任務端點
POST /s2s/v2.0/task/look-vto
  • 輪詢端點
GET /s2s/v2.0/task/look-vto/{task_id}
  • 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 YOUR_API_KEY"
};

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);
  }
})();
  • 成功回應範例
{
  "status": 200,
  "data": {
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?..."
    },
    "task_status": "success"
  }
}

results.url 欄位包含最終渲染的虛擬彩妝影像。

  • 摘要
步驟說明
1. 上傳圖片直接上傳，或提供圖片網址。
2. 列出造型範本取得可用的造型風格及其 ID。
3. 建立 VTO 任務提交圖片網址 + 範本 ID。
4. 輪詢至完成取得最終結果圖片網址。

這個工作流程確保可靠、開發者友善的整合，用於即時虛擬彩妝試色體驗。

檔案規格與錯誤

  • 支援的格式與尺寸
AI 功能支援的尺寸支援的檔案大小支援的格式
AI 完整妝容虛擬試妝長邊 < 1920，臉寬 >= 100< 10MBjpg/jpeg/png
  • 錯誤代碼
錯誤代碼說明
error_below_min_image_size來源圖片尺寸小於最小值（期望：寬 >= 100px，高 >= 100px）
error_exceed_max_image_size來源圖片尺寸大於最大值（期望：寬 < 1920px，高 < 1080px）
error_face_position_invalid請確保您的整張臉在圖片中完全可見
error_face_position_too_small偵測到的臉部過小。請靠近鏡頭
error_face_position_out_of_boundary臉部過大或部分在畫面之外。請調整您的位置
error_face_angle_invalid臉部角度不正確。正面照片請將頭部保持在 10° 內。側面照片請確保超過 15°。
  • 環境與相依性
範例程式語言 / 工具建議的執行環境版本
cURL- bash >= 3.2
- curl >= 7.58（現代 TLS/HTTP 支援）
- jq >= 1.6（穩健的 JSON 解析）
Node.js（JavaScript）Node >= 18（支援全域 fetch）
JavaScript- Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1
PHPPHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json
PythonPython >= 3.10（支援 f-strings），requests >= 2.20.0
JavaJava 11+（支援 HttpClient），Jackson Databind >= 2.12.0

點數消耗

AI 功能消耗的點數
AI 完整妝容虛擬試妝 V1.02
下载 OpenAPI 描述
ai_look_vto.json
ai_look_vto.yaml
概述
电子邮件
YouCamOnlineEditor_API@perfectcorp.com
许可证
Privacy policy
服务条款
语言
服务器
https://yce-api-01.makeupar.com