# フルメイク

# 概要
フルメイク API では、事前定義されたメイクアップルックをユーザー写真に適用します。
## 統合ガイド
このガイドでは、以下の手順を解説します。
* **エンドポイント:**

`/s2s/v2.0/task/look-vto`
* **認証:**
 すべてのリクエストには
`Authorization: Bearer <TOKEN>`
 が必要です
* **ワークフロー:**
  1. **セルフィーの準備:**
 画像をアップロードするか、有効な画像 URL を指定します
  2. **ルックテンプレートのリスト取得:**
 利用可能な AI ルックテンプレートを一覧表示します
  3. **タスクの開始 (`POST`):**
 画像 ID/URL とルック
`template_id`
 を送信します。
  4. **タスク ID の取得:**
 レスポンスから
`task_id`
 を取得します。
  5. **ステータスのポーリング (`GET`):**

`task_id`
 を使用してタスクのステータスを確認します。
`task_status`
 が
`"success"`
 または
`"error"`
 になるまでポーリングを継続します。



---

* API プレイグラウンド

API プレイグラウンドで API を対話的にテストします。
**API プレイグラウンド:**
[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/)


---

* 認証

- リクエストヘッダーに
**Bearer トークン**
 を使用して API キーを含めます:

```
Authorization: Bearer <API Key>
```

API キーの確認場所: 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` | ページネーション用トークン（省略可） |

* JavaScript リクエスト例


```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);
```
* 成功時のレスポンス例


```json
{
  "status": 200,
  "data": {
    "templates": [
      {
        "id": "good_template_001",
        "thumb": "thumbnail preview image URL",
        "title": "Berry Smooth",
        "category_name": "Daily"
      }
    ],
    "next_token": 73a3c9e69b89
  }
}
```
> **備考:** Look VTO タスクを作成する際は、`id` 値（`template_id`）を使用してください。



---

*   1. Look VTO タスクの作成と結果のポーリング

画像とテンプレート ID が用意できたら、タスクを作成します。API はリクエストを非同期で処理します。ステータスが `success` または `error` になるまで、タスクステータスをポーリングする必要があります。
* タスク作成エンドポイント


```
POST /s2s/v2.0/task/look-vto
```
* ポーリングエンドポイント


```
GET /s2s/v2.0/task/look-vto/{task_id}
```


---

* JavaScript 実装例


```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);
  }
})();
```


---

* 成功時のレスポンス例


```json
{
  "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 機能 | 対応寸法 | 対応ファイルサイズ | 対応フォーマット |
|  --- | --- | --- | --- |
| フルメイク | 長辺 < 1920、顔幅 >= 100 | < 10MB | jpg/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 |
| PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json |
| Python | Python >= 3.10 (f-string 用), requests >= 2.20.0 |
| Java | Java 11+ (HttpClient 用), Jackson Databind >= 2.12.0 |



---

## ユニット消費量
| AI 機能 | 消費ユニット |
|  --- | --- |
| フルメイク V1.0 | 2 |



---

License: Privacy policy

## Servers

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

## Security

### BearerAuthenticationV2

標準の 'Bearer authentication' を使用します。ヘッダーに 'API Key' を設定してください：`Authorization:Bearer YOUR_API_KEY`。'Bearer' と 'YOUR_API_KEY' の間にスペースがあることに注意してください。

Type: http
Scheme: bearer

## Download OpenAPI description

 - [フルメイク](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_look_vto.yaml)

## V1.0

 - [GET /s2s/v2.0/task/template/look-vto](https://docs.perfectcorp.com/ja/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1template~1look-vto/get.md)
 - [POST /s2s/v2.0/task/look-vto](https://docs.perfectcorp.com/ja/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto/post.md): このエンドポイントは、テンプレートとソース画像を使用してフルメイクのプロセスを開始します。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。
 - [GET /s2s/v2.0/task/look-vto/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_look_vto/v1.0/paths/~1s2s~1v2.0~1task~1look-vto~1%7Btask_id%7D/get.md)