跳转到内容
AI 妆容虚拟试妆/
/
文件规格与错误码

AI 妆容虚拟试妆

概览

AI 造型虚拟试穿接口提供一套完整流程，把美妆专家设计的整组脸部造型套到用户照片上。每套造型都由美妆专家打造，通过接口即可即时套用。

接入指南

本指南将带您走完全流程：

  • 接口地址： /s2s/v2.0/task/look-vto
  • 鉴权： 所有请求都需要 Authorization: Bearer <TOKEN>
  • 流程：
    1. 准备自拍照： 上传图片，或提供一个有效的图片 URL
    2. 列出造型模板： 取得可用的 AI 造型模板清单
    3. 发起任务（POST）： 提交您的图片 id/URL 与造型 template_id。
    4. 取得 Task ID： 从响应中取回 task_id。
    5. 轮询状态（GET）： 用 task_id 查看任务状态，持续轮询直到 task_status 为 "success" 或 "error"。
  • API Playground

用官方演练场交互式地体验和测试接口：

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

  • 鉴权
  • 请在请求头中以 Bearer Token 方式带上您的 API 密钥：
    Authorization: Bearer <API Key>

API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。

    1. 上传图片

您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。

  • 上传接口
POST /s2s/v2.0/file

如果您已有公开可访问的图片 URL，这一步可以跳过。

    1. 列出可用造型风格

取得所有可用于虚拟试穿的 AI 妆效造型模板。

  • 接口地址
GET /s2s/v2.0/task/template/look-vto
  • 查询参数
参数说明
page_size每页笔数
starting_token分页用的 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": "thumbnail preview image URL",
        "title": "Berry Smooth",
        "category_name": "Daily"
      }
    ],
    "next_token": 73a3c9e69b89
  }
}

说明： 创建造型 VTO 任务时，请使用 id 的值（即 template_id）。

    1. 创建造型 VTO 任务并轮询结果

图片和模板 ID 都备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 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. 上传图片直接上传，或提供图片 URL。
2. 列出造型模板取得可用造型风格及其 ID。
3. 创建 VTO 任务提交图片 URL + 模板 ID。
4. 轮询至完成取回最终结果图片的 URL。

这套流程稳定可靠、对开发者友好，可支撑即时上线的虚拟妆效试穿体验。

文件规格与错误码

  • 支持的格式与尺寸
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 (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

点数消耗

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