コンテンツへスキップ
フルメイク/
/
ファイル仕様とエラー

フルメイク

概要

フルメイク 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/

  • 認証
  • リクエストヘッダーに 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 リクエスト例
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
  }
}

備考: 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 実装例
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 機能対応寸法対応ファイルサイズ対応フォーマット
フルメイク長辺 < 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-string 用), requests >= 2.20.0
JavaJava 11+ (HttpClient 用), Jackson Databind >= 2.12.0

ユニット消費量

AI 機能消費ユニット
フルメイク V1.02
OpenAPI記述をダウンロード
ai_look_vto.json
ai_look_vto.yaml
概要
メール
YouCamOnlineEditor_API@perfectcorp.com
ライセンス
Privacy policy
利用規約
言語
サーバー
https://yce-api-01.makeupar.com