Google Virtual Try-On API 接入：人物图与服装图

两张图各自放对字段，接入就有了清楚的起点。人物照放到 person_image_url，服装图放到 product_image_url；把人物照填进服装字段，会改变任务的输入含义。

TL;DR

Google Virtual Try-On 每张 $0.1075；查看价格和预算。使用 HiAPI /v1/tasks 接口：提交任务拿 taskId，再查询结果。无需提示词。

输入准备与字段

选一张单人正面照，尽量让身体轮廓清楚；服装使用背景干净、边缘完整的平铺图或悬挂图。下面示例中的两个永久图片地址分别对应人物 A 和红白条纹 T 恤，可替换成你自己的公开图片地址。

字段	填写方式
person_image_url	必填；人物照片的公开 HTTP(S) URL
product_image_url	必填；服装商品图的公开 HTTP(S) URL
num_images	整数；显式填 1，当前只支持一张

把业务组合映射到请求

同一人物试不同服装时，固定 person_image_url，逐件替换 product_image_url；同一件服装展示不同人物时，固定商品图并替换人物图。同一组图要多个候选时，保留两张输入、分别提交，每次仍填 num_images: 1。建议在自己的任务记录里保存商品编号与人物图片版本，不能只凭结果文件名猜测对应关系。

人物和服装都要提供能公开读取的 HTTP(S) 图片地址，不支持把本地磁盘路径或 data URI 当成图片 URL。浏览器已登录时能看到图片，不等于其他服务能读取；提交前应在不依赖登录会话的条件下检查链接。建议确认返回的是图片本身，而不是相册页面或权限提示页，并让图片在任务读取期间保持可访问。

如果人物照遮住了衣摆或手部与衣服大面积重叠，先考虑换一张边界更清楚的照片。服装图优先选单件、边缘完整的平铺或挂拍图，避免把人物穿搭结果再次误当作独立商品图。公开字段没有提供局部保护、袖口调整或鞋子锁定设置，不能靠添加自定义字段表达这些要求。

选择清楚的图片是工作方法，接口是否接收图片与商品表达是否准确要分别检查。本文不为 Try-On 添加没有证据的文件大小、像素上限或输出尺寸承诺；也不能把其他图片模型的输入限制直接套过来。

提交任务：cURL

下面是 Bash/cURL 示例。先在运行环境配置 HIAPI_API_KEY；请求中的图片 URL 可以替换，密钥保留在服务端环境中。

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

成功提交会返回 data.taskId。保存这个值，供后续查询使用。

查询任务与保存结果

把任务编号放入 TASK_ID，再查询：

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

当任务 data.status=success 时，从 data.output[0].url 获取图片并保存。面向持续运行的业务，可在提交请求的顶层设置 callback.url 和 callback.when: "final" 接收结束通知，并按 taskId 去重；成功和失败都可能触发通知。查询方式适合调试和补查。

轮询、回调与超时处理

提交和查询是两件事。拿到 data.taskId 后，把它和本次输入一起记录，再查询 GET /v1/tasks/:id。没有进入结束状态时继续等待，不要把查询动作换成再次 POST。轮询间隔和业务等待上限由你的应用安排，本文没有可据以承诺的平均耗时或固定完成时限；示例里的网络超时也不构成服务时长保证。

查询请求超时，只能说明这次读取没有及时完成。保留任务编号，稍后补查同一个任务。若提交请求本身超时且没有拿到编号，服务器是否已经受理就存在不确定性：保留提交时间和请求内容，先核对任务记录，再决定是否重提。不要把客户端的异常直接解释成任务失败，也不要承诺重复请求会自动合并。

回调配置放在请求体顶层，与 model、input 同级，不能塞进模型输入中。配置 callback.url 时同时使用 callback.when: "final"。结束通知可能对应成功，也可能对应失败，所以接收通知后仍要检查状态。查询与回调可能处理到同一个任务，业务侧应按 taskId 去重，避免重复下载或重复触发后续工作。这里说明的是应用处理方法，没有假定回调一定在某个时间内送达。

data.status=success 后，确认 data.output 中确实有可读取的结果地址，再下载图片。若返回 fail，保存错误信息并根据内容修正请求；不要只根据一个状态猜测是图片过大、网络故障或其他具体原因。未预期的状态或缺少输出时，保留响应并补查，不把空结果当作成功交付。

下载失败和生成失败也要分开。任务已经成功但文件没保存好时，应先重新读取或下载已有结果，避免直接重做图片。归档时保留任务编号、输入对应关系和最终文件位置，之后才能准确找到某张图来自哪次请求。给用户显示的“等待超时”应表示当前界面停止等待，而不是擅自宣布服务端任务已取消。

Python 提交示例

环境需要安装 requests。这里的 timeout=60 是客户端网络请求等待上限，不是图片生成耗时。

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

提交前与结果检查

接口不需要 prompt。num_images 不要填 2 或 4；需要候选图时分别发起请求。先核对两张图片能公开读取、字段没有对调，再提交。收到失败状态时阅读返回信息并修正输入，不要原样反复提交。

按商品用途验收返回图片

先把结果与人物图并排看，检查脸部、发型、姿态、背景以及不应改变的裤子和鞋子。再对照服装图核对颜色、领型、袖长、图案与下摆。条纹 T 恤需要看横条纹在胸口和袖子处的衔接；连衣裙要看吊带、垂坠领口及手部附近的褶皱；衬衫要看袖口有没有卷起、下摆有没有扎进裤腰。这些检查来自案例里能看到的变化，不保证其他输入只会出现这些变化。

“文件已下载”和“图片可以用于商品页面”应分别记录。结果返回成功后仍可能出现衣服以外的变化，不能让接口状态自动代替人工验收。若缺陷来自输入遮挡，先更换输入再尝试；若商品必须展示特定袖长或固定配饰，先判断当前结果是否满足该约束，不能因为整体穿搭自然就忽略商品细节。

同一组输入追加候选时，保留之前的结果供比较，不用新文件覆盖旧文件。选择时写明接受或拒绝的原因，便于以后处理相似商品。图片只用于观察外观，真实尺码和穿着感受还需要服装尺寸及真人试穿信息。

常见问题

人物照与服装图能共用一个字段吗？

不能。人物照用 person_image_url，服装图用 product_image_url。

需要增加 prompt 参数吗？

不需要。接口没有提示词字段，试穿由两张输入图决定。

为什么显式写 num_images: 1？

当前只支持一张结果；显式写出可以让请求张数与每张 $0.1075 的预算直接对应。

拿到 taskId 就可以读取图片吗？

还需要查询任务或接收通知；任务 data.status=success 后，从 data.output[0].url 获取图片。

继续阅读

价格与预算 · API 接入 · 案例与选图 · Google Virtual Try-On

需要选择试衣或通用改图方式时，可看 Google Virtual Try-On 与 Seedream 5.0 Lite 的对比，逐项检查衣服、鞋子与人物外观。