博客

教程

如何通过 HiAPI API 使用 Google 虚拟试衣:curl 与 Python 指南

2026年11月10日
抽象扁平几何棱柱被分割成鼠尾草绿与松绿色平面,置于深绿色背景之上;一开发者教程的封面图。
本页内容

google-virtual-try-on 模型期望什么

在写任何代码之前,先理解输入契约会很有帮助。google-virtual-try-on 模型是一个双图合成任务:它接收一张人物/模特图和一张服装图,并生成人物穿着该服装的图像。

这意味着你的准备步骤始终是同样的形态:

  • 一张人物图,主体清晰可见且取景合理——全身或上半身照效果最好,因为模型需要理解身体几何结构。
  • 一张服装图,最好在干净或纯色背景上,展示你想转移到人物身上的单品。

两个输入都以图片 URL 的形式提供,而非请求体中的原始二进制数据。这能让请求负载保持较小,并让你自己的存储层(S3、GCS、CDN)继续作为事实来源。因此,你的工作是确保每个 URL 在发起调用前都可公开访问——或已签名且有效期足够长。

有几个需要提前规划的实际约束:

  • 分辨率和宽高比会影响输出质量。极小的缩略图或裁剪过度的输入往往会产生较差的结果。
  • 每次调用只处理一件服装。如果你的商品页有多种配色,请发起多次调用,而不是试图把多件单品塞进一个请求。
  • 配对是你的责任。模型不会验证服装是否“适合”该人物;它只是合成你提供的内容。良好的配对(全身照配连衣裙、上半身照配夹克)会明显带来更好的输出。

把这一步视为资产契约:如果你能为每个任务可靠地生成两个优质 URL,其余集成工作就是直截了当的管道搭建。

设置你的 HiAPI 请求

所有 HiAPI 模型调用都遵循同样的形态,因此一旦你有一个能跑通,其他的只需替换参数。以下是 google-virtual-try-on 所需的内容。

端点与方法

请求以 POST 发送到 google-virtual-try-on 的 HiAPI 模型调用端点。你在所有模型间使用同一个基础 URL 和同一套凭据,这也是选择通过 HiAPI 路由而非逐一接入各提供商的主要原因。

认证

在 Authorization 头中使用 HiAPI API key 认证,采用标准 bearer token 格式:

Authorization: Bearer $HIAPI_API_KEY

将密钥保留在服务端。绝不要在浏览器打包产物或移动应用中分发它——通过你自己的后端代理既更安全,也为你提供了一个添加限流和日志的位置。

内容类型

以 JSON 发送请求体:

Content-Type: application/json

请求体

请求体携带你的模型标识符以及上一节中的两个图片 URL——人物图和服装图——再加上模型暴露的任何可选参数。确切的参数名以模型旁边文档中记录的为准;请逐字复制而非猜测,因为字段名拼写错误通常表现为校验错误,而非有用的提示信息。

保存你的配置

将基础 URL、模型标识符和密钥放入环境变量,这样同一脚本无需修改即可在预发和生产环境使用:

export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

设置就这么多。无需 SDK,无需逐提供商接入。

一个可用的 curl 请求

确认密钥和负载是否正确最快的方式是单次 curl 调用。以下是对 google-virtual-try-on 请求的解剖:

curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-virtual-try-on",
    "input": {
      "model_image": "https://your-cdn.example.com/person-001.jpg",
      "garment_image": "https://your-cdn.example.com/jacket-front.jpg"
    }
  }'

有几点需要注意:

  • 两个图片字段位于 input 对象内,使模型特定参数保持命名空间隔离,并与路由字段分离。
  • URL 必须能从服务端访问,而非从你的笔记本电脑。一个 localhost 或仅 VPN 可访问的地址会失败。
  • 此调用中没有文件上传步骤。如果你的资产尚未在 CDN 上,请先上传并使用生成的 URL。

先运行一次并检查返回的原始 JSON,再在其上构建任何东西。将输出通过格式化器管道传递更易阅读:

curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

将请求体保存在 request.json 文件中也能在负载增长后避免 shell 引号错误。

同样的请求用 Python 实现

对于一次性测试之外的任何场景,请转向 Python。下面的示例仅使用标准库加上 requests,因此可直接放入脚本、Lambda 或小型服务,无需额外框架。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")


def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
    payload = {
        "model": "google-virtual-try-on",
        "input": {
            "model_image": person_url,
            "garment_image": garment_url,
        },
    }
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/google-virtual-try-on",
        json=payload,
        headers=headers,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = try_on(
        "https://your-cdn.example.com/person-001.jpg",
        "https://your-cdn.example.com/jacket-front.jpg",
    )
    print(result)

关于适配的说明:

  • 设置明确的超时。图像生成并非瞬时完成;requests 的默认超时对此类调用来说过于激进。请选择一个舒适高于你 p99 延迟的值。
  • 使用 json=payload,而非 data=json.dumps(payload)。它会为你设置内容类型,并避免双重编码的 bug。
  • 返回解析后的 JSON,而非响应对象,这样调用方不会意外依赖 HTTP 内部细节。如果你需要状态码用于指标,请在返回前捕获它们。
  • 将客户端与工作流分离。在真实服务中,上述函数属于一个轻量客户端模块;队列、存储和重试位于其上一层。

如果你已经在使用 httpx 或异步框架,转换是机械性的——负载和头完全一致。

读取响应

响应是 JSON。将其视为一个关注两件事的小信封:任务是否成功,以及输出在哪里?

大体上,你应检查:

  1. 传输状态。2xx 表示请求已被接受并处理。4xx 表示你的请求有误;5xx 表示服务端出了问题。在每次调用时记录状态码——这是你能添加的最廉价的观测手段。
  2. 响应体字段。负载携带生成结果。图像结果以指向生成资产的 URL 形式返回。确切的字段名以模型的响应 schema 为准;请防御性解析,而非假设是单个字符串。
  3. 元数据。响应中的任何用量或耗时字段都值得捕获。计费由平台计量,因此持久化每请求元数据可让你日后将自己的日志与仪表盘对账。

一个健壮的解析如下:

data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
    raise RuntimeError(f"No image in response: {data}")

如何处理结果

返回的 URL 是生成资产,而非永久资产。不要直接交给前端然后置之不理。相反:

  • 下载并重新托管。立即获取字节,并以内容寻址的键写入你自己的存储桶。这将你的产品与生成器的保留策略解耦。
  • 记录来源。将输入 URL、模型标识符和时间戳与输出一起存储。当商家问为什么某个试衣效果看起来是这样时,你会需要复现确切的任务。
  • 规范化格式。在摄入时一次性调整尺寸并转换为店铺前台的标准格式,而不是在每次页面浏览时处理。

将响应视为短暂交接——解析、下载、存储、丢弃——是可扩展的模式。

失败模式与重试策略

并非所有失败都值得重试。盲目重试会把上游的小 hiccup 变成满队列的重复任务和一张令人惊讶的账单。

重试前先分类

不要重试——修复请求:

  • 400 类校验错误:JSON 格式错误、字段缺失或名称错误、请求体不符合模型期望的结构。
  • 401/403:API key 错误或缺失,或 key 无权访问该模型。重试永远无济于事。
  • 404:模型标识符或端点路径错误。
  • 无法访问的图片 URL。如果人物或服装 URL 在获取时返回 404 或超时,生成无法继续。提交前验证 URL。

带退避重试:

  • 429:你被限流了。退避并尊重该信号。
  • 5xx:瞬时服务或上游错误。
  • 网络级故障:连接重置、读取超时。

带抖动的有界重试

限制尝试次数——三次是常见上限——并使用带随机抖动的指数退避,以免一群 worker 同步重试:

import random, time

def with_retry(fn, attempts=3, base=1.0):
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise  # client error: do not retry
            if i == attempts - 1:
                raise
            time.sleep(base * (2 ** i) + random.uniform(0, 0.5))

生产防护措施

  • 任务级幂等性。将输入 URL 对哈希为任务键。如果同一键已在执行中或已完成,返回已存储的结果而非重新提交。
  • 死信队列。重试耗尽后,将任务及其完整上下文停放,而非静默丢弃。
  • 熔断。如果错误率超过阈值,在冷却期内停止提交,而非持续冲击一个挣扎中的服务。
  • 按形态而非仅按数量告警。部署后 4xx 激增通常意味着有人重命名了字段。

尽早验证输入

大多数“模型故障”实际上是糟糕的输入。做一次廉价的预检:对每个 URL 发 HEAD 请求,检查内容类型和大致尺寸,并在花费一次计量调用之前拒绝明显不可用的资产。这一个习惯就能消除你大部分的重试流量。

将其融入真实流水线

一个成功的 curl 调用只是演示。可靠的产品功能需要在其周围多一点结构。

将流程结构化为阶段

一个可行的分解:

  1. 摄入。商家或内部用户提交人物图和服装图。将两者存入你的对象存储,并生成稳定、签名的 URL。
  2. 验证。检查可达性、格式和尺寸。以清晰的提示尽早拒绝。
  3. 提交。通过客户端模块调用 google-virtual-try-on。在数据库中记录任务键、模型标识符和输入 URL。
  4. 物化。成功后,下载生成的图像,转换为你的标准格式,并以确定性键写入你的 CDN。
  5. 发布。更新任务记录以指向你托管的资产,并让店铺前台只从你自己的存储读取。

每个阶段都可独立重试,这正是整个系统可调试的原因。如果第 4 步失败,你无需重新运行生成。

保持客户端轻量

将 HTTP 调用放在一个小模块中,并将策略(重试、并发、超时、日志)围绕其放置。当 HiAPI 为模型添加参数,或你想 A/B 测试不同的图像生成路线时,你只需改一个文件。

值得采纳的运维习惯

  • 默认异步。生成需要数秒,有时更长。从 worker 提交,而非从用户正在等待的请求处理器中提交。
  • 积极缓存。同一人物加服装对绝不应生成两次。对输出进行内容寻址,并在提交前检查。
  • 有可见性地做预算。由于用量由平台计量,请记录每请求元数据并定期与你的 HiAPI 仪表盘对账。在数小时内而非月底发现失控的重试循环。
  • 对提示词和参数进行版本化。将参数对象与每个任务一起存储,以便在变更后复现结果。
  • 向用户可见地失败。一个永远不消失的加载动画比诚实的“我们无法生成这个,请换一张照片试试”更糟。

下一步

同样的请求形态适用于其他 HiAPI 图像模型,因此你在此构建的客户端将成为你流水线其余部分的模板。一旦双图调用稳定,浏览模型目录,看看还有什么适合你的工作流——认证、错误处理和存储模式都原样沿用。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档