FASHN Try-On v1.6 API：可用的 curl 与 Python 请求示例

FASHN Try-On v1.6 是 hiapi 上的一个虚拟试穿（image-to-image）模型。你给它两张图片——一张人物照片和一张服装照片——它会返回一张合成的、穿在身上的效果图。本文是一篇面向开发者的 fashn try-on api 实操指南：包含一个我完整跑通的真实 /v1/tasks 请求、对照在线参数校验器核对过的完整输入 schema，以及参数表里没有写出的生产环境细节。

模型页面与在线体验：FASHN Try-On v1.6。

1. 你将构建的内容 + 前置条件

整个流程就是标准的异步任务模式：一次 POST 创建任务，然后轮询直到任务进入终态，再下载输出的图片。

你需要：

• 一个 API key（sk-...），可从 hiapi 快速入门 获取。
• 两个可公开访问的图片 URL：用于 model_image 的人物照片，以及用于 garment_image 的服装照片。

2. 最小可运行示例

创建任务（curl）

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

响应——这是一个已接受的任务，而不是成品图片：

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image 和 garment_image 是仅有的必填字段；其他字段都有默认值。

轮询结果（curl）

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

任务完成后，你会得到 data.status: "success"，图片位于 data.output[0].url：

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

这里的 expireAt 很重要：输出保存在临时存储上（TTL 约 7 天）。请立即下载或转存这些字节数据——不要直接热链。

用 Python 端到端运行

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. 输入 schema（已对照在线校验器验证）

fashn-tryon-v1.6 使用封闭式 schema——任何未列在下面的字段都会被拒绝，所以你无法夹带 hiapi 并未暴露的 FASHN 原生额外参数。

字段	是否必填	类型	可接受的值
model_image	是	string (URL)	人物照片
garment_image	是	string (URL)	服装照片
category	否	enum	tops, bottoms, one-pieces, auto
mode	否	enum	performance, balanced, quality
garment_photo_type	否	enum	auto, model, flat-lay
output_format	否	enum	png, jpeg
seed	否	integer	用于可复现性
segmentation_free	否	boolean	—

我是怎么确认这些的：发送 {"model":"fashn-tryon-v1.6","input":{}} 会返回

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

上面每个枚举值都是通过发送无效值确认的，例如 mode: value must be one of 'performance', 'balanced', 'quality'。传入 num_samples、num_images 或表格之外的任何字段会返回 additional properties '...' not allowed——没有多样本选项。一次请求返回一张图片；想要不同结果，可跨多次调用改变 seed。

4. 生产环境实践

• 校验发生在计费之前。 无效输入返回 HTTP 400，响应体为 {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}，并且不会创建任务——格式错误的请求不会产生费用。有效请求返回 code:200 并附带 taskId。
• 重新轮询，而不是重新提交。 每次 POST /v1/tasks 都会创建一个新的（可计费的）任务。如果轮询请求超时，继续轮询你已经拥有的 taskId；响应丢失并不意味着任务失败。
• 用回调代替轮询。 对于批量场景，你可以注册回调，让 hiapi 在任务达到最终状态时通知你，而不必自己轮询——具体字段见 统一异步 API 参考文档。上面的示例使用的是轮询。

5. 一次真实运行的情况

我运行了上面的最小请求——一张 768×1152 的人物照片和一张 768×1152 的服装图片，并省略了 mode 和 category：

• 延迟： 在任务对象上，从 created 到 completed 约 13 秒。
• 输出： 单张 PNG，尺寸为 768×1152，即一张竖版图片。模型页面说明输出尺寸会跟随人物照片（其已验证的运行中测得 972×1296 和 768×1152 两种尺寸），本次运行与此一致——没有 width/height/aspect_ratio 字段，因此人物照片的尺寸决定输出尺寸。
• 状态路径： 轮询中先显示 archiving，随后变为 success；storage 为 temp。
• 默认值确实有效。 省略 mode 和 category 依然成功，所以这两个图片 URL 确实是唯一必须提供的输入——模型会自动识别服装类型。

计费按输出图片数量计算，不随你选择的 mode 变化；当前费率请查看 定价页面。

相关链接

• FASHN Try-On v1.6 模型页面与在线体验
• 统一异步（任务）API 参考文档
• 快速入门——获取 API key
• 定价

常见问题

哪些字段是必填的？ 只有 model_image 和 garment_image，且都必须是可公开访问的 URL。

一次调用能生成多个变体吗？ 不能——num_samples 和 num_images 会被 schema 拒绝。一次请求返回一张图片；多次调用之间改变 seed 以获得不同结果。

如何控制输出尺寸？ 你无法直接设置。结果会跟随人物照片的尺寸——我输入的 768×1152 产生了 768×1152 的输出。

结果 URL 的有效期是多久？ 输出位于临时存储，带有 expireAt（约 7 天）。请立即下载这些字节数据。

质量模式会改变价格吗？ 不会——无论 performance、balanced 还是 quality，都按输出图片数量计费。