FASHN Try-On v1.6 API：動作する curl と Python のリクエスト例

FASHN Try-On v1.6 は hiapi 上のバーチャル試着（image-to-image）モデルです。人物写真と衣類写真の 2 枚を入力すると、合成された着用イメージを返します。本記事は開発者向けの fashn try-on api 実践ガイドです。実際に完走した /v1/tasks リクエスト、オンラインパラメータバリデーターで照合済みの完全な入力 schema、そしてパラメータ表には書かれていない本番環境の詳細を含みます。

モデルページとオンライン体験：FASHN Try-On v1.6。

1. 構築する内容 + 前提条件

全体の流れは標準的な非同期タスクパターンです。まず POST でタスクを作成し、タスクが終端状態になるまでポーリングし、その後出力画像をダウンロードします。

必要なもの：

• API key（sk-...）。hiapi クイックスタート から取得できます。
• 公開アクセス可能な 2 つの画像 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 が返ります——複数サンプルのオプションはありません。1 回のリクエストで 1 枚の画像が返ります。異なる結果が必要な場合は、複数回の呼び出しで 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. 実際に 1 回実行した結果

上記の最小リクエストを実行しました——768×1152 の人物写真と 768×1152 の衣類画像で、mode と category を省略しました：

• レイテンシ： タスクオブジェクト上で created から completed まで約 13 秒。
• 出力： 単一の PNG、サイズは 768×1152、つまり縦向きの画像です。モデルページには出力サイズは人物写真に従うと記載されており（検証済みの実行では 972×1296 と 768×1152 の 2 サイズが測定されています）、今回の実行もこれと一致しました——width/height/aspect_ratio フィールドはないため、人物写真のサイズが出力サイズを決めます。
• ステータスの経路： ポーリング中はまず archiving が表示され、その後 success に変わりました。storage は temp でした。
• デフォルト値は確かに有効です。 mode と category を省略しても成功したため、この 2 つの画像 URL が本当に唯一必須の入力です——モデルは衣類の種類を自動認識します。

課金は出力画像の枚数に基づいて計算され、選択した mode によって変わりません。現在の料金は 料金ページ を確認してください。

関連リンク

• FASHN Try-On v1.6 モデルページとオンライン体験
• 統一非同期（タスク）API リファレンスドキュメント
• クイックスタート——API key の取得
• 料金

よくある質問

どのフィールドが必須ですか？ model_image と garment_image のみで、どちらも公開アクセス可能な URL である必要があります。

1 回の呼び出しで複数のバリエーションを生成できますか？ いいえ——num_samples と num_images は schema によって拒否されます。1 回のリクエストで 1 枚の画像が返ります。異なる結果を得るには呼び出し間で seed を変えてください。

出力サイズを制御するには？ 直接設定することはできません。結果は人物写真のサイズに従います——入力した 768×1152 は 768×1152 の出力を生成しました。

結果 URL の有効期間はどれくらいですか？ 出力は一時ストレージに保存され、expireAt（約 7 日）が付きます。これらのバイトデータを直ちにダウンロードしてください。

品質モードで価格は変わりますか？ いいえ——performance、balanced、quality のいずれでも、出力画像の枚数に基づいて課金されます。