Google Virtual Try-On API 接入：人物画像と衣装画像

2 枚の画像をそれぞれ正しいフィールドに置けば、接続の出発点が明確になります。人物写真は person_image_url に、衣装画像は product_image_url に入れます。人物写真を衣装フィールドに記入すると、タスクの入力の意味が変わってしまいます。

TL;DR

Google Virtual Try-On は 1 枚あたり $0.1075 です。価格と予算を確認する。HiAPI の /v1/tasks インターフェースを使用します。タスクを送信して taskId を取得し、その後結果を照会します。プロンプトは不要です。

入力の準備とフィールド

体の輪郭がはっきり見える 1 人の正面写真を選んでください。衣装は背景がきれいで、輪郭が完全な平置き画像またはハンガー掛け画像を使用します。以下の例にある 2 つの永続画像アドレスは、それぞれ人物 A と赤白ストライプの T シャツに対応しており、ご自身の公開画像アドレスに置き換えられます。

フィールド	記入方法
person_image_url	必須。人物写真の公開 HTTP(S) URL
product_image_url	必須。衣装商品画像の公開 HTTP(S) URL
num_images	整数。明示的に 1 を記入。現在は 1 枚のみ対応

業務の組み合わせをリクエストにマッピングする

同じ人物に異なる衣装を試す場合は、person_image_url を固定し、product_image_url を 1 着ずつ置き換えます。同じ衣装を異なる人物に着せる場合は、商品画像を固定し、人物画像を置き換えます。同じ画像セットで複数の候補が欲しい場合は、2 枚の入力を保持したまま個別に送信し、毎回 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 が返された場合は、エラー情報を保存し、その内容に基づいてリクエストを修正してください。1 つのステータスだけで画像が大きすぎる、ネットワーク障害、その他の具体的な原因を推測してはいけません。予期しないステータスや出力の欠落がある場合は、レスポンスを保持して再照会し、空の結果を成功した納品として扱わないでください。

ダウンロードの失敗と生成の失敗も分けて扱います。タスクは成功したがファイルがうまく保存できなかった場合は、まず既存の結果を再読み取りまたは再ダウンロードし、画像をすぐに作り直すことを避けてください。アーカイブ時にはタスク番号、入力の対応関係、最終ファイルの場所を保持しておけば、後から特定の画像がどのリクエストに由来するかを正確にたどれます。ユーザーに表示する「待機タイムアウト」は、現在の画面が待機を停止したことを意味するべきであり、サーバー側のタスクがキャンセルされたと勝手に宣言してはいけません。

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 を記入しないでください。候補画像が必要な場合は個別にリクエストを送信します。まず 2 枚の画像が公開読み取り可能であること、フィールドが入れ替わっていないことを確認してから送信してください。失敗ステータスを受け取った場合は、返された情報を読んで入力を修正し、そのまま繰り返し送信しないでください。

商品用途に応じた返却画像の検収

まず結果と人物画像を並べて見て、顔、髪型、姿勢、背景、および変更されるべきでないパンツや靴を確認します。次に衣装画像と照らし合わせて、色、襟の形、袖丈、柄、裾を確認します。ストライプの T シャツでは胸元と袖での横縞のつながりを、ワンピースでは肩ひも、ドレープのある襟元、手の近くのしわを、シャツでは袖口がまくれていないか、裾がウエストに入っていないかを確認します。これらの確認は事例で見られる変化に基づくものであり、他の入力でこれらの変化だけが起こることを保証するものではありません。

「ファイルがダウンロード済み」と「画像が商品ページに使用可能」は別々に記録してください。結果が正常に返された後でも衣装以外の変化が現れる可能性があるため、インターフェースのステータスが人手による検収を自動的に代替してはいけません。欠陥が入力の遮蔽に由来する場合は、まず入力を交換してから再試行してください。商品が特定の袖丈や固定のアクセサリーを必ず示す必要がある場合は、現在の結果がその制約を満たすかどうかを先に判断し、全体の着こなしが自然だからといって商品の細部を無視してはいけません。

同じ入力セットで候補を追加する場合は、以前の結果を比較用に保持し、新しいファイルで古いファイルを上書きしないでください。選択時には受け入れまたは拒否の理由を書き留めておくと、後で類似商品を処理する際に役立ちます。画像は外観の観察にのみ使用し、実際のサイズや着用感には衣装の寸法および実際の試着情報が別途必要です。

よくある質問

人物写真と衣装画像は同じフィールドを共有できますか？

できません。人物写真は person_image_url、衣装画像は product_image_url を使用します。

prompt パラメータを追加する必要はありますか？

不要です。インターフェースにプロンプトフィールドはなく、試着は 2 枚の入力画像によって決まります。

なぜ num_images: 1 を明示的に書くのですか？

現在は 1 枚の結果のみ対応しています。明示的に書くことで、リクエスト枚数と 1 枚あたり $0.1075 の予算が直接対応します。

taskId を取得すれば画像を読み取れますか？

タスクの照会または通知の受信がさらに必要です。タスクが data.status=success になった後、data.output[0].url から画像を取得します。

続きを読む

価格と予算 · API 接入 · 事例と画像選び · Google Virtual Try-On

試着または汎用的な画像編集方法を選ぶ必要がある場合は、Google Virtual Try-On と Seedream 5.0 Lite の比較をご覧ください。衣装、靴、人物の外観を項目ごとに確認できます。