Bria Eraser API の使い方：curl、Python、そして実際に動く1回のリクエスト

bria-eraser は写真からオブジェクトを除去します。画像と白黒マスクを送信すると、マスク領域を一致する背景で埋めます。prompt フィールドはありません。本ガイドでは、完全に動作する1回のリクエスト、それを実行する Python コード、そして自分のマスクが機能するかどうかを決める詳細を紹介します。HiAPI キーはダッシュボードから取得してください。

最小リクエスト（curl）

このモデルは統一された非同期エンドポイント POST /v1/tasks を使用します。以下の2つの URL はどちらも公開されており、執筆時点でアクセス可能です：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-eraser",
    "input": {
      "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
      "mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
      "mask_type": "manual"
    }
  }'

この呼び出しは画像ではなく、タスク id を即座に返します：

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

data.status が success になるまで GET /v1/tasks/<taskId> をポーリングし、その後 data.output[0].url を読み取ります。

Python：送信、ポーリング、ダウンロード

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

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

def erase(image_url: str, mask_url: str, out_path: str) -> str:
    r = requests.post(API, headers=HEADERS, timeout=30, json={
        "model": "bria-eraser",
        "input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: poll the SAME task id again
        if d["status"] == "success":
            img = requests.get(d["output"][0]["url"], timeout=60)
            img.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(img.content)
            return task_id
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(task_id)

タスク id を保持してください。あるポーリングが失敗した場合は、同じ id をもう一度ポーリングします。再送信はしないでください。各送信は個別に課金されるタスクだからです。

リクエストフィールド

フィールド	必須	説明
input.image_url	はい	公開された http/https URL。JPEG、PNG、または WEBP。
input.mask_url	はい	元画像と同じアスペクト比の白黒画像。白い部分は消去され、黒い部分は保持されます。
input.mask_type	いいえ	manual（デフォルト）はブラシで描いたマスク用、automatic はセグメンテーションツールが生成したマスク用です。
input.preserve_alpha	いいえ	デフォルトは false。true に設定すると、アルファチャンネル付き入力の透明度を保持します。

本番環境：コールバックを使用する

ポーリングはテストに適しています。サービスでは、トップレベルの callback を渡して、タスク完了時に HiAPI から通知を受け取ります：

{
  "model": "bria-eraser",
  "input": { "image_url": "...", "mask_url": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

コールバックが失われる場合に備えて、ポーリングをフォールバックとして残してください。出力 URL は期限切れになるため、タスク成功後はできるだけ早くファイルを自分のストレージにコピーしてください。

実際に実行して確認した結果

執筆当日に curl セクションのリクエストを1回実行し、完了までポーリングしました。

• ステータスの順序：handling → archiving → success。archiving は処理完了後、output が現れる前に発生します。「まだ完了していない」とみなして、ポーリングを続けてください。
• 所要時間：タスクは作成から完了まで16秒かかりました。output URL はその数秒後に現れました。
• 出力：temp.hiapi.ai 上の PNG、1360 × 768、アルファチャンネル付き。これは元画像と同じサイズで、元の解像度を保持するというドキュメントの説明と一致します。
• 課金：私が確認した時点で、公開されている価格データではこのモデルの価格は1枚あたり $0.0575 でした。最新の価格は価格をご覧ください。
• 検証エラー：故意に mask_type: "bogus" を送信してテストしました。API は HTTP 400 で拒否しました：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}

私は1枚の画像で1回のリクエストしか確認していません。他のマスクスタイル、極端に大きな画像、画像とアスペクト比が一致しないマスクはテストしていません。以下に示すこれらのケースに関する説明は、私のテストではなくモデルのドキュメントに基づいています。

マスクのヒント（ドキュメントより）

• オブジェクトの輪郭から少しはみ出して塗ってください。輪郭にぴったり合わせたマスクは、元のオブジェクトの周囲に光輪を残すことがよくあります。
• マスクは写真と同じアスペクト比を保ってください。ドキュメントはそう要求していますが、そうしない場合にどうなるかは説明していません。
• automatic はセグメンテーションや切り抜きツールのマスクにのみ使用してください。ブラシのマスクには manual を使用します。

どのページを読むべきですか？

本ガイドは専用エンドポイントを使用したマスクベースの除去について説明しています。汎用の画像編集モデルを使ったプロンプト駆動の編集については、画像インペインティングとオブジェクト除去をご覧ください。単一のオブジェクトではなく背景全体を除去する場合は、背景除去ガイドをご覧ください。モデルページは bria-eraser、フィールドリファレンスは API ドキュメントにあります。

よくある質問

bria-eraser にプロンプトは必要ですか？

いいえ。ドキュメントにはプロンプトが不要と記載されており、私が実行したリクエストには画像、マスク、mask_type のみが含まれていました。

マスク内のどの色が除去されますか？

白は消去され、黒は保持されます。

出力は入力より小さくなりますか？

私の実行では、出力は 1360 × 768 で、元画像とまったく同じでした。

ポーリングとコールバックのどちらを使うべきですか？

テスト時はポーリングです。本番環境では callback.url と when: "final" を使用し、ポーリングをフォールバックとして併用してください。