チュートリアル
HiAPI API で Google バーチャル試着を使う方法:curl と Python ガイド
このページの内容
google-virtual-try-on モデルが期待するもの
コードを書く前に、入力の契約を理解しておくと役立ちます。google-virtual-try-on モデルは二画像合成タスクです。人物/モデル画像と衣料品画像を受け取り、その人物がその衣料品を着ている画像を生成します。
つまり、準備手順は常に同じ形になります。
- 人物画像。被写体がはっきり見え、構図が適切であること。モデルは身体の幾何構造を理解する必要があるため、全身または上半身の写真が最適です。
- 衣料品画像。できれば清潔または無地の背景に、人物へ移したいアイテムが写っているもの。
両方の入力は、リクエスト本文中の生のバイナリデータではなく、画像 URL として提供されます。これによりリクエストペイロードを小さく保ち、あなた自身のストレージ層(S3、GCS、CDN)を引き続き信頼できる情報源として機能させられます。したがって、あなたの仕事は、呼び出し前に各 URL が公開アクセス可能であること、または十分に長い有効期限で署名済みであることを確認することです。
事前に計画すべき実務上の制約がいくつかあります。
- 解像度とアスペクト比は出力品質に影響します。極端に小さいサムネイルや過度にトリミングされた入力は、しばしば悪い結果を生みます。
- 1 回の呼び出しで処理できる衣料品は 1 点です。商品ページに複数のカラーバリエーションがある場合は、複数のアイテムを 1 リクエストに詰め込もうとせず、複数回呼び出してください。
- ペアリングはあなたの責任です。モデルは衣料品がその人物に「合う」かどうかを検証しません。提供された内容を合成するだけです。適切なペアリング(全身写真にドレス、上半身写真にジャケット)は明らかにより良い出力をもたらします。
このステップをアセット契約と見なしてください。各タスクに対して 2 つの高品質な URL を確実に生成できれば、残りの統合作業は素直なパイプライン構築です。
HiAPI リクエストを設定する
すべての HiAPI モデル呼び出しは同じ形に従うため、1 つ動くようになれば、他はパラメータを置き換えるだけです。以下は google-virtual-try-on に必要な内容です。
エンドポイントとメソッド
リクエストは google-virtual-try-on の HiAPI モデル呼び出しエンドポイントへ POST で送信されます。すべてのモデル間で同じベース URL と同じ認証情報を使います。これが、各プロバイダーを個別に接続するのではなく HiAPI 経由でルーティングする主な理由でもあります。
認証
Authorization ヘッダーで HiAPI API key を用いて認証します。標準の bearer token 形式です。
Authorization: Bearer $HIAPI_API_KEY
キーはサーバー側に保持してください。ブラウザのバンドルやモバイルアプリで配布してはいけません。自前のバックエンドプロキシ経由にすれば、より安全であるだけでなく、レート制限やログを追加する場所も得られます。
コンテンツタイプ
リクエスト本文は JSON で送信します。
Content-Type: application/json
リクエスト本文
本文にはモデル識別子と、前節で述べた 2 つの画像 URL(人物画像と衣料品画像)、さらにモデルが公開する任意のパラメータが含まれます。正確なパラメータ名はモデルの横にあるドキュメントに記載されているとおりに従ってください。推測せず逐語的にコピーしてください。フィールド名の綴り間違いは、有用なヒントではなく検証エラーとして現れるのが普通です。
設定を保存する
ベース URL、モデル識別子、キーを環境変数に入れておけば、同じスクリプトを変更なしでステージングと本番の両方で使えます。
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
設定はこれだけです。SDK も、プロバイダーごとの接続も不要です。
実際に動く curl リクエスト
キーとペイロードが正しいかを確認する最速の方法は、1 回の 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"
}
}'
注意すべき点がいくつかあります。
- 2 つの画像フィールドは
inputオブジェクト内にあり、モデル固有のパラメータを名前空間で分離し、ルーティング用フィールドと分けています。 - URL はノート PC からではなく、サーバー側からアクセス可能でなければなりません。
localhostや VPN 経由でのみアクセス可能なアドレスは失敗します。 - この呼び出しにファイルアップロードの手順はありません。アセットがまだ CDN 上にない場合は、先にアップロードして生成された URL を使ってください。
まず 1 回実行し、返ってきた生の 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 ファイルに保存しておけば、ペイロードが大きくなった後のシェルの引用符エラーも避けられます。
同じリクエストを 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 レイテンシより余裕を持って上回る値を選んでください。 data=json.dumps(payload)ではなくjson=payloadを使ってください。コンテンツタイプを設定してくれ、二重エンコードのバグも避けられます。- レスポンスオブジェクトではなくパース済みの JSON を返してください。呼び出し側が誤って HTTP の内部詳細に依存しないようにするためです。メトリクス用にステータスコードが必要なら、返す前に取得してください。
- クライアントとワークフローを分離してください。実際のサービスでは、上記の関数は軽量なクライアントモジュールに属し、キュー、ストレージ、リトライはその上の層に置かれます。
すでに httpx や非同期フレームワークを使っている場合、変換は機械的です。ペイロードとヘッダーはまったく同じです。
レスポンスを読む
レスポンスは JSON です。2 つのことだけに注目する小さな封筒として扱ってください。タスクが成功したか、そして出力はどこにあるか、です。
大まかに、以下を確認すべきです。
- トランスポートのステータス。2xx はリクエストが受理され処理されたことを意味します。4xx はリクエストに誤りがあること、5xx はサーバー側で問題が起きたことを意味します。呼び出しごとにステータスコードを記録してください。これは追加できる最も安価な観測手段です。
- レスポンス本文のフィールド。ペイロードには生成結果が含まれます。画像結果は生成されたアセットを指す URL として返されます。正確なフィールド名はモデルのレスポンス schema に従ってください。単一の文字列だと仮定せず、防御的にパースしてください。
- メタデータ。レスポンス中の使用量や所要時間のフィールドは記録する価値があります。課金はプラットフォームが計測するため、リクエストごとのメタデータを永続化しておけば、後で自分のログとダッシュボードを照合できます。
堅牢なパースは次のようになります。
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:一時的なサービスまたは上流のエラー。- ネットワークレベルの障害:接続リセット、読み取りタイムアウト。
ジッター付きの上限付きリトライ
試行回数を制限し(3 回が一般的な上限です)、ランダムなジッターを加えた指数バックオフを使って、ワーカー群が同期してリトライしないようにします。
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 リクエストでコンテンツタイプとおおよそのサイズを確認し、明らかに使えないアセットを課金対象の呼び出しを消費する前に拒否します。この習慣 1 つで、リトライトラフィックの大部分を排除できます。
実際のパイプラインに組み込む
成功する curl 呼び出しはデモにすぎません。信頼できる製品機能には、その周囲にもう少し構造が必要です。
フローを段階に構造化する
実用的な分解は次のとおりです。
- 取り込み。マーチャントまたは内部ユーザーが人物画像と衣料品画像を送信します。両方をオブジェクトストレージに保存し、安定した署名付き URL を生成します。
- 検証。到達可能性、形式、サイズを確認します。明確なメッセージで早期に拒否します。
- 送信。クライアントモジュール経由で
google-virtual-try-onを呼び出します。タスクキー、モデル識別子、入力 URL をデータベースに記録します。 - 実体化。成功後、生成画像をダウンロードし、標準形式に変換し、決定的なキーで自分の CDN に書き込みます。
- 公開。タスクレコードを自分がホストするアセットを指すよう更新し、店舗フロントは自分のストレージからのみ読み取るようにします。
各段階を独立してリトライできることが、システム全体をデバッグ可能にします。第 4 ステップが失敗しても、生成を再実行する必要はありません。
クライアントを軽量に保つ
HTTP 呼び出しは小さなモジュールに置き、その周囲にポリシー(リトライ、並行性、タイムアウト、ログ)を配置します。HiAPI がモデルにパラメータを追加したときや、異なる画像生成ルートを A/B テストしたいときも、変更するファイルは 1 つだけです。
採用する価値のある運用習慣
- デフォルトは非同期で。生成には数秒、時にはそれ以上かかります。ユーザーが待っているリクエストハンドラからではなく、ワーカーから送信してください。
- 積極的にキャッシュする。同じ人物と衣料品のペアを 2 回生成してはいけません。出力を内容アドレス指定し、送信前に確認してください。
- 可視性を持って予算管理する。使用量はプラットフォームが計測するため、リクエストごとのメタデータを記録し、定期的に HiAPI ダッシュボードと照合してください。暴走したリトライループは月末ではなく数時間で発見できます。
- プロンプトとパラメータをバージョン管理する。パラメータオブジェクトを各タスクと一緒に保存し、変更後も結果を再現できるようにします。
- ユーザーに見える形で失敗する。決して消えないローディングアニメーションは、正直な「これを生成できませんでした。別の写真で試してください」よりも悪い対応です。
次のステップ
同じリクエストの形は他の HiAPI 画像モデルにも当てはまるため、ここで構築したクライアントはパイプラインの残りの部分のテンプレートになります。二画像呼び出しが安定したら、モデルカタログを閲覧して、自分のワークフローに合うものを見つけてください。認証、エラー処理、ストレージのパターンはそのまま流用できます。