透過 API 串接虛擬試穿功能

虛擬試穿 API 只需要兩張圖片：一張人物照片和一張商品照片，就能合成一張該人物穿戴該商品的全新實穿照。本指南將示範如何使用 Genlook Try-On API，將這項功能整合進 Web 應用程式、行動 App 或自建電商平台。無論是服飾、鞋履、眼鏡、飾品、手錶、包包還是帽子，都能以相同的流程完成串接。

利益揭露：本 API 由 Genlook 開發。若您還在挑選合適的服務商，我們整理的 10 款虛擬試穿 API 實測比較提供了所有生成效果的並列對比。

串接前準備

一組 API 金鑰：請在 platform.genlook.app 註冊帳號。新帳號皆享有 10 點免費額度，足以完整測試整套流程。
後端伺服器：API 金鑰必須存放在伺服器端，切勿暴露在瀏覽器前端或打包進行動 App 中。
一張人物照片：格式支援 JPEG、PNG、WebP 或 HEIC，檔案大小在 10 MB 以內，需為正面照，並完整露出預計穿戴商品的身體部位。
一張商品圖片：直接使用商品頁面上的現成照片即可。無論是白底去背照（packshot）、平鋪照（flat lay）或模特兒實穿照都能完美支援，完全不需要 3D 模型。

運作流程解析

每一次串接體驗都遵循以下三個步驟：

上傳人物照片：呼叫 POST /images/upload。成功後會取得一個 imageId，後續這張照片的所有試穿皆可重複使用該 ID。
發起試穿請求：呼叫 POST /try-on。在請求內容中直接帶入商品資訊（圖片、標題與描述）以及 imageId，無須事先同步整批商品型錄。
取得生成結果：可輪詢 GET /generations/:id、呼叫 SDK 提供的 waitFor()，或是接收 generation.completed Webhook 通知。平均生成時間約為 8 秒。

如果您偏好只發送單次請求，可使用 POST /try-on/sync 同步端點。連線會保持暢通直到結果產出並直接回傳，非常適合用於自動化腳本或 Serverless 雲端函式。

使用 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 呼叫 API

雖然目前未提供專屬的 Python SDK，但 REST API 支援任何程式語言。以下示範如何使用單次請求的同步端點：

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"])

同步請求最多會等待 90 秒。若超過此時間仍在處理中，API 會回傳帶有 generationId 的 202 狀態碼，方便您改以輪詢方式查詢結果。

眼鏡、飾品、鞋款與其他配件

您不需要在參數中指定商品類別。API 會自動辨識商品圖，並將配件精準置於對應位置：眼鏡戴在臉上、耳環貼合耳垂、項鍊垂於鎖骨、鞋子穿在腳上。呼叫方式與襯衫完全相同。

注意事項：

整套穿搭僅限服裝：在單次試穿任務中，最多可同時傳送 4 件服飾（例如上衣、長褲搭配外套）。至於眼鏡、帽子、鞋履、包包與飾品，請個別發起獨立的試穿任務。
人物照片必須完整露出穿戴部位：胸部以上的自拍照適用於眼鏡和耳環，但無法用來試穿鞋款。

行動 App 整合（iOS、Android、Flutter、React Native）

由於 API 金鑰不可打包進 App 中，因此行動端的整合流程一律需經由後端轉發：

App 拍攝或選取照片，並上傳至您的後端伺服器。
後端將照片上傳至 Genlook API 並發起試穿任務。
後端取得圖片 URL 後回傳給 App，或於收到 Webhook 通知時主動推播至 App。
App 載入並展示試穿成果。

您的後端只要具備發送 HTTP 請求的能力即可，因此 App 所使用的語言或框架完全不受限制。

費用結構

每次生成扣除 1 點額度，若試穿失敗則全額退還點數。隨買即用的儲值方案為每次試穿 0.04 美元，最低 5 美元起購且點數永久有效。月繳方案更優惠：Starter 方案每次試穿僅需 0.02 美元（每月 20 美元享 1,000 點），Scale 方案更可降至 0.015 美元（每月 300 美元享 20,000 點）。您可以透過開發者頁面上的費用估算工具，根據預估用量計算出精準的月費。

開發時應避免的常見錯誤

直接在前端瀏覽器呼叫 API：這會導致金鑰外洩，請務必透過後端伺服器進行呼叫。
商品名稱描述過於簡略：標題與描述有助於 AI 理解商品的剪裁與版型。填寫「短版羊毛開襟衫，寬鬆廓形剪裁」的合成效果，遠比填寫「商品 4417」好得多。
重複上傳相同商品的完整資訊：首次處理某件商品時會進行分析，耗時略長數秒。後續試穿相同商品時，只需帶入該商品的 externalId，系統就會直接沿用先前的分析成果。
未設定圖片保留天數：上傳圖片時，可將 keepForDays 設為 1、3 或 7 天，並帶入您的 externalUserId。這樣當使用者提出隱私刪除要求時，就能透過單一 API 呼叫一併刪除該使用者的所有照片。
開發期間白白消耗額度：測試前端介面時，可將商品標題設為 mock，API 就會即時且免費回傳未經修改的人物原圖，讓您安心測試 UI。

常見問答

為您解答疑問。

有哪款 API 能合成人物穿戴指定服飾的照片嗎？↓

有的。虛擬試穿 API 正是為此而生：您只要傳入人物照片與服飾照片，系統便能生成該人物穿戴該款衣服的全新實穿照。使用 Genlook，只要呼叫一次同步端點，或呼叫兩次搭配輪詢，平均約 8 秒即可完成。

我需要準備商品的 3D 模型嗎？↓

不需要。API 直接使用現有的商品平面圖即可運作，也就是您官網商品頁面上正在使用的照片。

合成出來的圖片可以做商業用途嗎？↓

可以。Genlook 是專為電商平台與商業應用打造的商用級 API。相較之下，如 IDM-VTON 和 CatVTON 等學術研究模型多半採用非商業授權，無法直接商用。

我的電商網站是用 Shopify、WooCommerce 或 PrestaShop 架設的，還需要串接 API 嗎？↓

不需要。您可以直接安裝 Genlook 的專屬 App、外掛或模組，免寫程式碼就能直接在商品頁面啟用虛擬試穿功能。API 主要是提供給客製化電商網站、行動 App 或其他自研產品使用。