虛擬試穿 API 只需要兩張圖片：一張人物照片和一張商品照片，就能合成一張該人物穿戴該商品的全新實穿照。本指南將示範如何使用 [Genlook Try-On API](https://genlook.app/developers)，將這項功能整合進 Web 應用程式、行動 App 或自建電商平台。無論是服飾、鞋履、眼鏡、飾品、手錶、包包還是帽子，都能以相同的流程完成串接。
_利益揭露：本 API 由 Genlook 開發。若您還在挑選合適的服務商，我們整理的 [10 款虛擬試穿 API 實測比較](/blog/2026-nian-zui-jia-xu-ni-shi-chuan-api-ping-ce-yu-zhi-nan) 提供了所有生成效果的並列對比。_
## 串接前準備
- 一組 API 金鑰：請在 [platform.genlook.app](https://platform.genlook.app) 註冊帳號。新帳號皆享有 10 點免費額度，足以完整測試整套流程。
- 後端伺服器：API 金鑰必須存放在伺服器端，切勿暴露在瀏覽器前端或打包進行動 App 中。
- 一張人物照片：格式支援 JPEG、PNG、WebP 或 HEIC，檔案大小在 10 MB 以內，需為正面照，並完整露出預計穿戴商品的身體部位。
- 一張商品圖片：直接使用商品頁面上的現成照片即可。無論是白底去背照（packshot）、平鋪照（flat lay）或模特兒實穿照都能完美支援，完全不需要 3D 模型。
## 運作流程解析
每一次串接體驗都遵循以下三個步驟：
1. **上傳人物照片**：呼叫 `POST /images/upload`。成功後會取得一個 `imageId`，後續這張照片的所有試穿皆可重複使用該 ID。
2. **發起試穿請求**：呼叫 `POST /try-on`。在請求內容中直接帶入商品資訊（圖片、標題與描述）以及 `imageId`，無須事先同步整批商品型錄。
3. **取得生成結果**：可輪詢 `GET /generations/:id`、呼叫 SDK 提供的 `waitFor()`，或是接收 `generation.completed` Webhook 通知。平均生成時間約為 8 秒。
如果您偏好只發送單次請求，可使用 `POST /try-on/sync` 同步端點。連線會保持暢通直到結果產出並直接回傳，非常適合用於自動化腳本或 Serverless 雲端函式。
## 使用 TypeScript 完成首次試穿
官方提供的 SDK 為 [`@genlook/api`](https://genlook.app/docs/tryon-api/sdk)，可在 Node 20+、Deno、Bun 以及 Edge 環境下順暢執行。
```ts
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 支援任何程式語言。以下示範如何使用單次請求的同步端點：
```bash
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>" } } }
}'
```
```python
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 中，因此行動端的整合流程一律需經由後端轉發：
1. App 拍攝或選取照片，並上傳至您的後端伺服器。
2. 後端將照片上傳至 Genlook API 並發起試穿任務。
3. 後端取得圖片 URL 後回傳給 App，或於收到 Webhook 通知時主動推播至 App。
4. App 載入並展示試穿成果。
您的後端只要具備發送 HTTP 請求的能力即可，因此 App 所使用的語言或框架完全不受限制。
## 費用結構
每次生成扣除 1 點額度，若試穿失敗則全額退還點數。隨買即用的儲值方案為每次試穿 0.04 美元，最低 5 美元起購且點數永久有效。月繳方案更優惠：Starter 方案每次試穿僅需 0.02 美元（每月 20 美元享 1,000 點），Scale 方案更可降至 0.015 美元（每月 300 美元享 20,000 點）。您可以透過開發者頁面上的 [費用估算工具](https://genlook.app/developers#pricing)，根據預估用量計算出精準的月費。
## 開發時應避免的常見錯誤
- **直接在前端瀏覽器呼叫 API**：這會導致金鑰外洩，請務必透過後端伺服器進行呼叫。
- **商品名稱描述過於簡略**：標題與描述有助於 AI 理解商品的剪裁與版型。填寫「短版羊毛開襟衫，寬鬆廓形剪裁」的合成效果，遠比填寫「商品 4417」好得多。
- **重複上傳相同商品的完整資訊**：首次處理某件商品時會進行分析，耗時略長數秒。後續試穿相同商品時，只需帶入該商品的 `externalId`，系統就會直接沿用先前的分析成果。
- **未設定圖片保留天數**：上傳圖片時，可將 `keepForDays` 設為 1、3 或 7 天，並帶入您的 `externalUserId`。這樣當使用者提出隱私刪除要求時，就能透過單一 API 呼叫一併刪除該使用者的所有照片。
- **開發期間白白消耗額度**：測試前端介面時，可將商品標題設為 `mock`，API 就會即時且免費回傳未經修改的人物原圖，讓您安心測試 UI。
<Faq>
<FaqItem question="有哪款 API 能合成人物穿戴指定服飾的照片嗎？">
有的。虛擬試穿 API 正是為此而生：您只要傳入人物照片與服飾照片，系統便能生成該人物穿戴該款衣服的全新實穿照。使用 Genlook，只要呼叫一次同步端點，或呼叫兩次搭配輪詢，平均約 8 秒即可完成。
</FaqItem>
<FaqItem question="我需要準備商品的 3D 模型嗎？">
不需要。API 直接使用現有的商品平面圖即可運作，也就是您官網商品頁面上正在使用的照片。
</FaqItem>
<FaqItem question="合成出來的圖片可以做商業用途嗎？">
可以。Genlook 是專為電商平台與商業應用打造的商用級 API。相較之下，如 IDM-VTON 和 CatVTON 等學術研究模型多半採用非商業授權，無法直接商用。
</FaqItem>
<FaqItem question="我的電商網站是用 Shopify、WooCommerce 或 PrestaShop 架設的，還需要串接 API 嗎？">
不需要。您可以直接安裝 Genlook 的專屬 App、外掛或模組，免寫程式碼就能直接在商品頁面啟用虛擬試穿功能。API 主要是提供給客製化電商網站、行動 App 或其他自研產品使用。
</FaqItem>
</Faq>
Shopify
WooCommerce
API