{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_look_vto.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_look_vto.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_look_vto"},"disableAutoScroll":true,"seo":{"title":"AI 妆容虚拟试妆","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI 妆容虚拟试妆","version":"","description":"# 概览\nAI 造型虚拟试穿接口提供一套完整流程，把美妆专家设计的整组脸部造型套到用户照片上。每套造型都由美妆专家打造，通过接口即可即时套用。\n\n## 接入指南\n本指南将带您走完全流程：\n\n*   **接口地址：** `/s2s/v2.0/task/look-vto`\n*   **鉴权：** 所有请求都需要 `Authorization: Bearer <TOKEN>`\n*   **流程：**\n    1.  **准备自拍照：** 上传图片，或提供一个有效的图片 URL\n    1.  **列出造型模板：** 取得可用的 AI 造型模板清单\n    1.  **发起任务（`POST`）：** 提交您的图片 id/URL 与造型 ``template_id``。\n    1.  **取得 Task ID：** 从响应中取回 `task_id`。\n    1.  **轮询状态（`GET`）：** 用 `task_id` 查看任务状态，持续轮询直到 `task_status` 为 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n用官方演练场交互式地体验和测试接口：\n\n**API Playground：**\n[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/)\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n    ```\n    Authorization: Bearer <API Key>\n    ```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。\n\n   * 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 2. 列出可用造型风格\n\n取得所有可用于虚拟试穿的 AI 妆效造型模板。\n\n   * 接口地址\n\n```\nGET /s2s/v2.0/task/template/look-vto\n```\n\n   * 查询参数\n\n| 参数        | 说明                     |\n| ---------------- | ------------------------------- |\n| `page_size`      | 每页笔数        |\n| `starting_token` | 分页用的 token（选填） |\n\n   * JavaScript 请求示例\n\n```javascript\nconst data = null;\n\nconst xhr = new XMLHttpRequest();\nxhr.withCredentials = true;\n\nxhr.addEventListener('readystatechange', function () {\n    if (this.readyState === this.DONE) {\n        console.log(this.responseText);\n    }\n});\n\nxhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');\nxhr.setRequestHeader('Authorization', 'Bearer <access_token for v1, API Key for v2>');\n\nxhr.send(data);\n```\n\n   * 成功响应示例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"templates\": [\n      {\n        \"id\": \"good_template_001\",\n        \"thumb\": \"thumbnail preview image URL\",\n        \"title\": \"Berry Smooth\",\n        \"category_name\": \"Daily\"\n      }\n    ],\n    \"next_token\": 73a3c9e69b89\n  }\n}\n```\n\n> **说明：** 创建造型 VTO 任务时，请使用 `id` 的值（即 `template_id`）。\n\n---\n\n* 3. 创建造型 VTO 任务并轮询结果\n\n图片和模板 ID 都备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n   * 创建任务接口\n\n```\nPOST /s2s/v2.0/task/look-vto\n```\n\n   * 轮询接口\n\n```\nGET /s2s/v2.0/task/look-vto/{task_id}\n```\n\n---\n\n   * JavaScript 实现示例\n\n```javascript\nconst BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';\nconst START_METHOD = 'POST';\nconst HEADERS = {\n  \"Content-Type\": \"application/json\",\n  \"Authorization\": \"Bearer YOUR_API_KEY\"\n};\n\nconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nasync function startTask() {\n  const init = {\n    method: START_METHOD,\n    headers: HEADERS,\n    body: JSON.stringify({\n      \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg\",\n      \"template_id\": \"all_rosy_chic\"\n    })\n  };\n\n  const res = await fetch(BASE_URL, init);\n  if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);\n\n  const payload = await res.json().catch(() => ({}));\n  const taskId = payload?.data?.task_id;\n  if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));\n\n  console.log('[startTask] Task started, id =', taskId);\n  return taskId;\n}\n\nasync function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    const pollUrl = `${BASE_URL}/${taskId}`;\n    const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });\n\n    if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);\n\n    const payload = await res.json().catch(() => ({}));\n    const status = payload?.data?.task_status;\n    console.log(`[pollTask] Attempt ${attempt} status = ${status}`);\n\n    if (status === 'success') {\n      console.log('[pollTask] Success results:', payload?.data?.results);\n      return payload;\n    }\n\n    if (status === 'error') {\n      throw new Error('Task failed: ' + JSON.stringify(payload));\n    }\n\n    await sleep(intervalMs);\n  }\n\n  throw new Error('Polling timeout: Max attempts exceeded');\n}\n\n(async () => {\n  try {\n    const taskId = await startTask();\n    const final = await pollTask(taskId);\n    console.log('[main] Final response:', final);\n  } catch (e) {\n    console.error('[main] Flow error:', e);\n  }\n})();\n```\n\n---\n\n   * 成功响应示例\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n`results.url` 字段就是最终渲染完成的虚拟妆效图片。\n\n---\n\n* 流程小结\n\n| 步骤                       | 说明                              |\n| -------------------------- | ---------------------------------------- |\n| **1. 上传图片**        | 直接上传，或提供图片 URL。 |\n| **2. 列出造型模板** | 取得可用造型风格及其 ID。 |\n| **3. 创建 VTO 任务**     | 提交图片 URL + 模板 ID。          |\n| **4. 轮询至完成** | 取回最终结果图片的 URL。     |\n\n这套流程稳定可靠、对开发者友好，可支撑即时上线的虚拟妆效试穿体验。\n\n---\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n|  ----  | ----  | ----  | ----  |\n|AI 造型虚拟试穿|长边 < 1920，脸部宽度 >= 100|< 10MB|jpg/jpeg/png|\n\n* 错误码\n\n|错误码|说明|\n|  ----  | ----  |\n|error_below_min_image_size|源图尺寸小于下限（要求：宽 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|源图尺寸超过上限（要求：宽 < 1920px，高 < 1080px）\n|error_face_position_invalid |请确保整张脸在画面中完整可见|\n|error_face_position_too_small|检测到的人脸太小，请靠近相机|\n|error_face_position_out_of_boundary|人脸过大，或部分超出画面边界，请调整位置|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 造型虚拟试穿 V1.0 | 2 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.216.199"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_look_vto","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}