通过 API 为应用接入虚拟试穿

虚拟试穿 API 的原理非常直观：传入一张人物照片和一张商品图，接口便会返回一张该人物穿戴该商品的新照片。本文将详细演示如何借助 Genlook Try-On API，为 Web 网页、移动端 App 或自建电商独立站接入这一功能。无论是服装、鞋履、眼镜、珠宝首饰、手表、箱包还是帽子，均适用同一套交互流程。

说明：Genlook 是此 API 的开发方。如果你还在对比不同的技术选型，欢迎查阅我们整理的 10 款虚拟试穿 API 横向测评，内含各家生成效果的直观对比。

准备工作

API Key：在 platform.genlook.app 注册账号即可获取。新用户免费赠送 10 个算力点数，足够跑通完整测试流程。
服务端环境：API Key 属于机密凭证，必须妥善保存在后端服务器，切勿暴露在前端浏览器或移动端安装包中。
人物照片：格式支持 JPEG、PNG、WebP 或 HEIC，文件不超过 10 MB；需正面朝向，且待试穿部位清晰可见。
商品图片：直接使用商品详情页现有的实拍图即可。无论是白底图、平铺图还是模特实拍图均可直接识别，无需准备 3D 模型。

整体流程解析

任何客户端的集成都可以分为三个标准步骤：

上传人物照片：调用 POST /images/upload。接口会返回一个 imageId，后续基于该照片的多次试穿均可直接复用此 ID。
创建试穿任务：调用 POST /try-on。在请求体中内联传入商品信息（图片地址、商品标题和描述）以及刚才获取的 imageId。无需提前同步庞大的商品目录。
获取生成结果：可以通过轮询 GET /generations/:id、调用 SDK 中的 waitFor() 方法，或者监听 generation.completed Webhook 回调获取结果。平均生成耗时约 8 秒。

如果你希望一次请求直接拿到结果，也可以使用 POST /try-on/sync 同步接口。该接口会保持 HTTP 连接挂起，生成完毕后直接返回图片地址，特别适合自动化脚本或 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 调用

即便暂时没有官方 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 秒。如果超时后图像仍未完成渲染，接口会返回 202 状态码与 generationId，你可以随后通过轮询获取最终图片。

适配眼镜、配饰、鞋履等多样化品类

调用接口时无需额外声明商品类型。API 底层模型会自动识别输入商品，并精准穿戴在人体对应的生理部位：眼镜贴合面部、耳环落在耳垂、项链环绕锁骨、鞋子穿在脚上。传参逻辑与试穿衬衫完全一致。

开发时只需留意两点规范：

整套搭配（Outfit）仅限服装品类：一次任务中最多支持组合 4 件衣物（例如上衣、裤子加外套）。眼镜、帽子、鞋履、包袋与饰品等品类需要单独创建试穿任务。
人物照片必须露出品类所对应的身体区域：例如半身近景肖像完全适合试戴眼镜或耳环，但无法用于鞋类试穿。

移动端开发指南（iOS、Android、Flutter、React Native）

鉴于 API Key 绝不能内嵌打包在客户端 App 中，移动端业务链路必须通过你的服务端进行中转：

App 引导用户拍照或从相册选图，并上传到你的业务服务器。
你的业务服务器将图片提交给 Genlook API 并发起试穿任务。
服务器拿到最终图片 URL 后返回给 App，或在收到 Webhook 通知后通过长链接/推送同步给客户端。
App 呈现合成后的试穿效果图。

只要你的后端具备发送 HTTP 请求的能力即可接入，无论 App 采用哪种客户端技术栈都能轻松兼容。

费用与计费机制

每次成功生成消耗 1 个点数，任务失败自动原路返还。按量付费模式折合每次试穿 0.04 美元，充值包 5 美元起且永久有效。月度订阅套餐更划算，Starter 套餐折合每次 0.02 美元（20 美元包含 1,000 点），Scale 套餐单价可降至 0.015 美元（300 美元包含 20,000 点）。你也可以前往开发者页面上的价格估算工具，根据实际预估业务量快速测算月度成本。

常见误区与避坑建议

从前端浏览器直接发起调用：这会导致你的 API Key 泄露。所有核心请求必须由后端代发。
商品标题填写过于简陋：标题和描述能帮助 AI 理解材质剪裁与版型特征。“宽松落肩羊毛开衫”的成图质量会显著优于类似“商品 4417”这样毫无语义的名称。
重复全量提交相同的商品信息：首次试穿某个商品时，模型需要耗费数秒进行深度解析。后续任务直接传该商品的 externalId 即可复用解析缓存，大幅提升出图速度。
无节制存储用户照片：上传图片时建议将 keepForDays 参数配置为 1、3 或 7 天自动过期。配合传入唯一的 externalUserId，当用户发起隐私清除请求时即可一键抹除全部关联数据。
开发调试期浪费生产点数：将商品标题命名为 mock 时，接口会迅速且完全免费地直接回传原始人物图，非常便于前后端联调 UI 流程。

常见问题

常见问题解答。

是否有成熟的 API 可以直接生成某人试穿特定衣物的效果图？↓

完全可以。虚拟试穿 API 专门解决这一场景：传入人物图与商品图，系统自动合成试穿后的真实照片。使用 Genlook 同步接口只需一次请求，或者通过异步轮询两步搞定，通常只需 8 秒左右。

接入前必须先给商品建模建 3D 资产吗？↓

不需要。接口直接利用你商品页现成的实拍平铺图、白底图或模特图即可运作。

生成的试穿图片可以用于商业用途吗？↓

可以。Genlook 是专为企业线上商城与数字化应用打造的商用级 API。学术开源模型（如 IDM-VTON、CatVTON 等）通常附带严格的非商用协议限制，而 Genlook 完全支持商用场景。

我的独立站基于 Shopify、WooCommerce 或 PrestaShop，还需要对接 API 吗？↓

不需要。针对这些主流电商平台，Genlook 提供了开箱即用的插件与应用，无需编写任何代码即可在商品详情页嵌入试穿组件。API 接口主要面向自研独立站架构、移动端 App 以及定制化系统集成。