hiapi API で bria-product-shot を使う方法：curl、Python、そして実際に動作するリクエスト

bria-product-shot は商品写真を 1 枚受け取り、商品をさまざまなシーンに配置した新しい画像を返します。シーンを英語で記述することも、参照画像を渡してその画像の背景スタイルに従わせることもできます。本ガイドでは、hiapi 上でエンドツーエンドで実際に動作したリクエストと、リクエストが受け入れられるかどうかを決めるパラメータのルールを紹介します。

ダッシュボードの API Keys ページ から hiapi API キーを取得し、さらに公開アクセス可能な商品写真の URL（JPEG、PNG、または WEBP、最大 12 MB）を用意してください。

最小限の動作例（curl）

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-product-shot",
    "input": {
      "image_url": "https://your-cdn.example.com/serum-bottle.png",
      "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
      "placement_type": "manual_placement",
      "manual_placement_selection": "bottom_center"
    }
  }'

作成呼び出しは即座にタスク ID を返します：

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

GET /v1/tasks/<taskId> を data.status が success または fail になるまでポーリングします。完了後のレスポンスは次のようになります（出力ホスト名は短縮しています）：

{
  "code": 200,
  "data": {
    "model": "bria-product-shot",
    "status": "success",
    "storage": "temp",
    "taskId": "tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW",
    "output": [{"artifactId": "287064", "type": "image", "expireAt": 1793325686,
                "url": "https://temp.hiapi.ai/.../...-0.png"}]
  },
  "message": "success"
}

Python バージョン

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def product_shot(image_url: str, scene: str, position: str = "bottom_center") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "bria-product-shot",
        "input": {
            "image_url": image_url,
            "prompt": scene,
            "placement_type": "manual_placement",
            "manual_placement_selection": position,
        },
    }, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d["status"] == "success":
            # output URLs expire (about 7 days): download immediately
            return requests.get(d["output"][0]["url"], timeout=60).content
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

open("shot.png", "wb").write(product_shot(
    "https://your-cdn.example.com/serum-bottle.png",
    "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
))

主要なパラメータ

フィールド	説明
image_url	必須。商品写真の公開 http(s) URL。
prompt	英語のシーン記述、1〜1000 文字。
reference_image_url	シーン参照画像。このパラメータか prompt のどちらか一方を使用し、決して同時に使用しないでください。
placement_type	manual_placement（デフォルト）は商品をプリセット位置に配置します。original は写真内の元の位置を維持します。
manual_placement_selection	bottom_center（デフォルト）、upper_left、upper_right、bottom_left、bottom_right、right_center、left_center、upper_center、center_vertical、center_horizontal。manual_placement を使用する場合にのみ有効です。
original_quality	original を使用する場合にのみ有効：入力サイズを維持し、約 1 MP にスケーリングしません。
fast	デフォルトは true。オフにすると標準モデルを使用します。価格は同じです。
optimize_description	デフォルトは true。シーンテキストを拡張します。prompt を使用する場合にのみ有効で、参照画像と一緒には使用できません。

このスキーマは閉じており（additionalProperties: false）、フィールド間のルールがあるため、prompt と reference_image_url、あるいは original とプリセット位置などの組み合わせは無効なリクエストになります。

テスト記録と注意事項

ライブ API に対して実行した内容：

• 上記のリクエストを使用して実際に 1 回生成し、fast はデフォルト値のままとしました。タスクは handling と archiving を経て、作成から約 26 秒後に success に達しました。
• 正方形の入力に対して、出力は 1024×1024 の PNG（約 1 MB）で、これはモデルページの説明と一致します：正方形の入力の場合、プリセット位置は 1024×1024 で測定されます。
• 意図的に設定した誤った値 "manual_placement_selection": "middle" は作成時に拒否され、HTTP 400 と error_code: INVALID_REQUEST が返されました。エラーメッセージには許可された 10 個の位置がすべて列挙されるため、タスクの失敗を待つことなく、そのままユーザーに見せることができます。

実用的なヒント：

• 出力はすぐにダウンロードしてください。 各出力には expireAt タイムスタンプ（完了後の Unix 時間、約 7 日間）が付いています。画像はご自身のストレージに保存してください。
• 画像ごとの固定価格です。 モデルページによると、シーンテキストと参照画像、配置位置、高速モードは価格を変えません。現在の数値はハードコードせず、料金ページ で確認してください。
• 本ガイドでは生成を 1 回しか実行していないため、さまざまな商品カテゴリの品質についての主張は行いません。一括使用の前に、ご自身のカタログ画像でテストしてください。

本番環境の推奨事項

• タスクを作成し、taskId を保存し、一時的なネットワークエラーが発生した場合は数回リトライしてポーリングします。新しいタスクを作成するのではなく、保存した ID を再度ポーリングしてください。新しいタスクは再度課金されるためです。
• キューを使用する場合は、クライアント側で上記の 10 個の値に基づいて manual_placement_selection を検証し、誤った入力が API に到達しないようにしてください。

関連ページ

• Bria Product Shot モデルページ：リアルタイム価格、入力フォーム、プレイグラウンド。
• Bria Eraser モデルページ：マスクを使用してオブジェクトを削除します。これは商品を新しいシーンに配置するのとは異なるタスクです。
• すべての画像モデルを閲覧
• 851-labs 背景除去 API ガイド：元の写真の背景が雑然としている場合は、まず商品を切り抜いてください。
• FLUX.2 画像から画像への API の使い方

よくある質問

テキストプロンプトの代わりに参照画像を使用できますか？ はい。reference_image_url を送信し、prompt を省略してください。両方を同時に送信しないでください。optimize_description を参照画像と一緒に送信しないでください。

1 回の呼び出しで何枚の画像が返されますか？ 1 枚です。モデルページには、実行ごとに 1 枚の画像が出力されると記載されています。

商品は写真の中の位置を維持しますか？ placement_type: "original" の場合のみです。デフォルトの manual_placement は、選択したプリセット位置に再配置します。