虚拟试穿 API 的原理非常直观：传入一张人物照片和一张商品图，接口便会返回一张该人物穿戴该商品的新照片。本文将详细演示如何借助 [Genlook Try-On API](https://genlook.app/developers)，为 Web 网页、移动端 App 或自建电商独立站接入这一功能。无论是服装、鞋履、眼镜、珠宝首饰、手表、箱包还是帽子，均适用同一套交互流程。
_说明：Genlook 是此 API 的开发方。如果你还在对比不同的技术选型，欢迎查阅我们整理的 [10 款虚拟试穿 API 横向测评](/blog/zuijia-xuni-shiyi-api-2026)，内含各家生成效果的直观对比。_
## 准备工作
- API Key：在 [platform.genlook.app](https://platform.genlook.app) 注册账号即可获取。新用户免费赠送 10 个算力点数，足够跑通完整测试流程。
- 服务端环境：API Key 属于机密凭证，必须妥善保存在后端服务器，切勿暴露在前端浏览器或移动端安装包中。
- 人物照片：格式支持 JPEG、PNG、WebP 或 HEIC，文件不超过 10 MB；需正面朝向，且待试穿部位清晰可见。
- 商品图片：直接使用商品详情页现有的实拍图即可。无论是白底图、平铺图还是模特实拍图均可直接识别，无需准备 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` 同步接口。该接口会保持 HTTP 连接挂起，生成完毕后直接返回图片地址，特别适合自动化脚本或 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 调用
即便暂时没有官方 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 秒。如果超时后图像仍未完成渲染，接口会返回 `202` 状态码与 `generationId`，你可以随后通过轮询获取最终图片。
## 适配眼镜、配饰、鞋履等多样化品类
调用接口时无需额外声明商品类型。API 底层模型会自动识别输入商品，并精准穿戴在人体对应的生理部位：眼镜贴合面部、耳环落在耳垂、项链环绕锁骨、鞋子穿在脚上。传参逻辑与试穿衬衫完全一致。
开发时只需留意两点规范：
- **整套搭配（Outfit）仅限服装品类**：一次任务中最多支持组合 4 件衣物（例如上衣、裤子加外套）。眼镜、帽子、鞋履、包袋与饰品等品类需要单独创建试穿任务。
- **人物照片必须露出品类所对应的身体区域**：例如半身近景肖像完全适合试戴眼镜或耳环，但无法用于鞋类试穿。
## 移动端开发指南（iOS、Android、Flutter、React Native）
鉴于 API Key 绝不能内嵌打包在客户端 App 中，移动端业务链路必须通过你的服务端进行中转：
1. App 引导用户拍照或从相册选图，并上传到你的业务服务器。
2. 你的业务服务器将图片提交给 Genlook API 并发起试穿任务。
3. 服务器拿到最终图片 URL 后返回给 App，或在收到 Webhook 通知后通过长链接/推送同步给客户端。
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 Key 泄露。所有核心请求必须由后端代发。
- **商品标题填写过于简陋**：标题和描述能帮助 AI 理解材质剪裁与版型特征。“宽松落肩羊毛开衫”的成图质量会显著优于类似“商品 4417”这样毫无语义的名称。
- **重复全量提交相同的商品信息**：首次试穿某个商品时，模型需要耗费数秒进行深度解析。后续任务直接传该商品的 `externalId` 即可复用解析缓存，大幅提升出图速度。
- **无节制存储用户照片**：上传图片时建议将 `keepForDays` 参数配置为 1、3 或 7 天自动过期。配合传入唯一的 `externalUserId`，当用户发起隐私清除请求时即可一键抹除全部关联数据。
- **开发调试期浪费生产点数**：将商品标题命名为 `mock` 时，接口会迅速且完全免费地直接回传原始人物图，非常便于前后端联调 UI 流程。
<Faq>
<FaqItem question="是否有成熟的 API 可以直接生成某人试穿特定衣物的效果图？">
完全可以。虚拟试穿 API 专门解决这一场景：传入人物图与商品图，系统自动合成试穿后的真实照片。使用 Genlook 同步接口只需一次请求，或者通过异步轮询两步搞定，通常只需 8 秒左右。
</FaqItem>
<FaqItem question="接入前必须先给商品建模建 3D 资产吗？">
不需要。接口直接利用你商品页现成的实拍平铺图、白底图或模特图即可运作。
</FaqItem>
<FaqItem question="生成的试穿图片可以用于商业用途吗？">
可以。Genlook 是专为企业线上商城与数字化应用打造的商用级 API。学术开源模型（如 IDM-VTON、CatVTON 等）通常附带严格的非商用协议限制，而 Genlook 完全支持商用场景。
</FaqItem>
<FaqItem question="我的独立站基于 Shopify、WooCommerce 或 PrestaShop，还需要对接 API 吗？">
不需要。针对这些主流电商平台，Genlook 提供了开箱即用的插件与应用，无需编写任何代码即可在商品详情页嵌入试穿组件。API 接口主要面向自研独立站架构、移动端 App 以及定制化系统集成。
</FaqItem>
</Faq>
Shopify
WooCommerce
API