genlook
Guide執筆: Thibault Mathian

APIを使ってアプリにAIバーチャル試着を組み込む方法

APIを一度呼び出すだけで、指定した服やメガネ、ネックレスを人物が身につけた写真を生成。実装の構成、TypeScript・cURL・Pythonコード、アプリ対応、コスト、避けるべき注意点まで解説。

目次

バーチャル試着APIとは、人物の写真と商品の写真の2枚を渡すことで、その人物が商品を身につけた新しい画像を返す仕組みです。この記事では、Genlook Try-On APIを使ってWebアプリやモバイルアプリ、自社ECサイトへ組み込む手順を解説します。服だけでなく、靴、メガネ、ジュエリー、時計、バッグ、帽子でも同じフローで実装できます。

注記：GenlookはこのAPIを開発・提供しています。他のサービスと比較検討中の場合は、/blog/2026-virtual-try-on-api-benchmarkで各社APIの生成結果を直接見比べることができます。

必要なもの

  • APIキー：platform.genlook.appでアカウントを作成してください。新規登録で10回分の無料クレジットが付与されるため、実装フロー全体のテストが可能です。
  • バックエンド環境：APIキーはサーバー側で保持し、ブラウザやモバイルアプリのコード内に含めないでください。
  • 人物写真：JPEG、PNG、WebP、HEIC形式（最大10MB）。正面を向いており、商品を身につける部位が写っている必要があります。
  • 商品画像：商品ページですでに使用している写真で問題ありません。白抜きの商品写真、平置き写真、モデル着用写真のいずれにも対応しています。3Dモデルを用意する必要はありません。

処理の流れ

どのプラットフォームでも、実装は以下の3ステップで完了します。

  1. 人物写真をアップロード：POST /images/uploadを実行します。返却されたimageIdは、同じ写真を使う試着で再利用できます。
  2. 試着リクエストの作成：POST /try-onを実行します。商品情報（画像、タイトル、説明）とimageIdをインラインで送信します。事前にカタログ同期などの初期登録は不要です。
  3. 結果の取得：GET /generations/:idをポーリングするか、SDKのwaitFor()を呼び出すか、あるいはgeneration.completedのWebhookを受信します。生成にかかる時間の中央値は約8秒です。

リクエストを1回で完結させたい場合は、処理が完了するまで接続を維持して結果を直接返すPOST /try-on/syncも利用できます。スクリプトやサーバーレス関数での処理に適しています。

TypeScriptでの初回実装

公式SDKは@genlook/apiです。Node 20以降、Deno、Bun、およびEdgeランタイムに対応しています。

import { Genlook } from "@genlook/api";
import { readFile } from "node:fs/promises";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// 1. 人物写真をアップロード（imageIdを再利用可能）
const { imageId } = await client.images.upload(
  await readFile("./person.jpg"),
  { mimeType: "image/jpeg" },
);

// 2. 試着処理を作成。商品情報はリクエスト内で直接定義
const { generationId } = await client.tryOn.create({
  products: [{
    externalId: "linen-shirt-12",
    title: "Relaxed linen shirt",
    description: "Oversized fit, dropped shoulders, falls below the hip.",
    images: [{ source: { url: "https://cdn.example.com/linen-shirt.jpg" } }],
  }],
  person: { image: { source: { id: imageId } } },
});

// 3. 生成完了まで待機
const result = await client.generations.waitFor(generationId);
console.log(result.resultImageUrl);

cURLやPythonでの呼び出し

Python専用のSDKはありませんが、標準のREST APIとしてどの言語からでも呼び出せます。以下は、同期（sync）エンドポイントを使った1回のリクエストで完結する例です。

curl -X POST "https://api.genlook.app/tryon/v1/try-on/sync" \
  -H "x-api-key: $GENLOOK_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 100 \
  -d '{
    "products": [{
      "externalId": "linen-shirt-12",
      "title": "Relaxed linen shirt",
      "description": "Oversized fit, dropped shoulders, falls below the hip.",
      "images": [{ "source": { "url": "https://cdn.example.com/linen-shirt.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "<imageId>" } } }
  }'

import os, requests

BASE = "https://api.genlook.app/tryon/v1"
headers = {"x-api-key": os.environ["GENLOOK_API_KEY"]}

with open("person.jpg", "rb") as f:
    image_id = requests.post(f"{BASE}/images/upload", headers=headers,
                             files={"file": ("person.jpg", f, "image/jpeg")}).json()["imageId"]

result = requests.post(f"{BASE}/try-on/sync", headers=headers, timeout=100, json={
    "products": [{
        "externalId": "linen-shirt-12",
        "title": "Relaxed linen shirt",
        "description": "Oversized fit, dropped shoulders, falls below the hip.",
        "images": [{"source": {"url": "https://cdn.example.com/linen-shirt.jpg"}}],
    }],
    "person": {"image": {"source": {"id": image_id}}},
}).json()

print(result["resultImageUrl"])

syncリクエストは最大90秒間結果を待ちます。万が一タイムアウトした場合でも、generationIdを含むステータス202が返されるため、ポーリングに切り替えて結果を取得できます。

メガネ、ジュエリー、靴など他の商品カテゴリ

商品タイプをパラメータで指定する必要はありません。APIが商品画像を自動解析し、メガネは顔へ、ピアスは耳へ、ネックレスは首元へ、靴は足元へと、適切な位置に合成します。リクエストの構造はシャツを試着する場合とまったく同じです。

実装にあたって知っておくべきポイントは2点あります。

  • まとめ買い・セット試着は衣類のみ対応：トップス、ボトムス、ジャケットなど、衣類であれば1回のリクエストで最大4点まで同時に試着可能です。メガネ、帽子、靴、バッグ、ジュエリーなどは、単体でそれぞれ試着リクエストを実行してください。
  • 商品を身につける部位が写っていること：顔から胸元までのセルフィー写真ならメガネやピアスは試着できますが、靴を試着させることはできません。

モバイルアプリ（iOS、Android、Flutter、React Native）での対応

APIキーをアプリ内に埋め込むことはできないため、モバイルアプリからの連携は必ずバックエンドを経由します。

  1. アプリ側で写真を撮影または選択し、自社バックエンドへ送信します。
  2. バックエンドがAPIに写真をアップロードし、試着リクエストを開始します。
  3. バックエンドが生成された画像のURLを返すか、Webhook受信時にアプリへ通知します。
  4. アプリが試着結果の画像を表示します。

バックエンドはHTTPリクエストを送信できる環境であれば言語を問わないため、アプリ側の開発フレームワークに制約はありません。

料金体系

試着1回につき1クレジットを消費し、生成に失敗した場合はクレジットが自動的に返金されます。都度購入（従量課金）は試着1回あたり0.04ドルで、5ドルから購入でき有効期限はありません。月額プランを利用すると、スタータープラン（月額20ドルで1,000回）で1回あたり0.02ドル、スケールプラン（月額300ドルで20,000回）なら1回あたり0.015ドルまで単価を抑えられます。開発者向けページの料金シミュレーターで、想定の利用規模に応じた月額費用を試算できます。

避けるべき注意点

  • ブラウザから直接APIを呼び出す：APIキーが第三者に漏洩する危険があります。必ずバックエンド経由で実行してください。
  • 大雑把な商品タイトルを指定する：タイトルと説明文は、AIが商品の形状やシルエットを理解するための重要な手がかりです。「商品 4417」とするよりも、「クロップド丈のウールカーディガン、ボクシーフィット」のように具体的に指定するほうが精度が高まります。
  • 毎回同じ商品を新規として送信する：初めて試着する商品は画像の解析処理が入るため、数秒余計に時間がかかります。2回目以降は同じexternalIdを指定するだけで、初回の解析結果が再利用されます。
  • 不要になった写真を保持し続ける：アップロード時にkeepForDaysを1、3、7日のいずれかに設定してください。また、独自のexternalUserIdを付与しておけば、ユーザーからの削除要求があった場合も1回のAPIコールで該当ユーザーの画像をすべて削除できます。
  • 開発中のUIテストで無駄にクレジットを消費する：商品タイトルにmockと指定すると、人物写真をそのまま無料かつ高速で返すため、クレジットを消費せずにUIの動作確認が可能です。

FAQ

疑問にお答えします。

特定の商品を人物に着せた写真を生成できるAPIはありますか？↓

はい。バーチャル試着APIがまさにその役割を果たします。人物写真と商品写真を渡すだけで、その商品を着用した姿の画像を生成します。Genlookなら同期エンドポイントを使って1回のリクエストで実行でき、約8秒で結果が得られます。

商品の3Dモデルは必要ですか？↓

いいえ、不要です。ECサイトの商品ページで使用している通常の写真素材（白抜き、物撮り、モデル着用など）からそのまま生成できます。

生成した画像は商用利用できますか？↓

はい、可能です。Genlookはオンラインストアや商用アプリでの本番運用を前提に設計された商用APIです。なお、IDM-VTONやCatVTONなどの研究用オープンソースモデルは非商用ライセンスで公開されていることが一般的です。

Shopify、WooCommerce、PrestaShopでショップを運営している場合もAPIの実装が必要ですか？↓

いいえ、APIを使う必要はありません。Genlookの公式アプリやプラグインを導入すれば、ノーコードで商品ページにバーチャル試着機能を追加できます。APIは、独自開発のECフロントエンドやモバイルアプリ、自社プロダクトへ組み込む場合に適しています。