# フルメイク

# 概要
フルメイク API では、事前定義されたメイクアップルックをユーザー写真に適用します。

## 統合ガイド
このガイドでは、以下の手順を解説します。

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

---

* 2. 利用可能なルックスタイルのリスト取得

バーチャル試着に利用可能なすべての 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`）を使用してください。

---

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

---

   * 成功時のレスポンス例

```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</br>   - curl >= 7.58 (モダンな TLS/HTTP サポート)</br>   - jq >= 1.6 (堅牢な JSON 解析) |
| Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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

[object Object]

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)