APIで画像の背景を除去する：プロンプトベースの編集

従来の背景除去ツールは1つの操作しか提供しません：被写体を切り抜き、透明領域（または単色塗りつぶし）を残すだけです。一方、image-to-imageモデルによるプロンプトベースの背景除去では、1回の呼び出しで切り抜き結果と置換後の背景を同時に得られます——継ぎ目のない白いスタジオ背景、ライフスタイルシーン、ブランドカラー一色など——モデルは単にアルファマスクを計算するのではなく、保持された被写体の周囲の背景をピクセル単位で再生成するからです。

本ガイドでは、hiapi上でこれを実現する方法を正確に示します：どのimage-to-imageモデルが背景除去を本当に得意とするのか、それに基づいてコーディングすべきリクエスト/レスポンス構造、そしてバッチタスクが商品カタログを静かに汚染するのを防ぐ本番環境のパターン（コールバック、リトライ、エラー処理）です。

前提条件：

• ダッシュボードからhiapi APIキーを取得する
• Python 3.9+ と requests のインストール（pip install requests）
• ソース画像が公開URLでホストされていること——hiapiのタスクAPIはファイルアップロードではなくURLで画像を取得するため、ローカルファイルパスは使用できません。任意のオブジェクトストレージやCDNで構いません。

image-to-imageタスクとしての背景除去の仕組み

hiapi上のすべての生成——画像、動画、音声——は同じ非同期タスクのライフサイクルを経ます：タスクを送信して taskId を取得し、その後は結果をポーリングするか、コールバックURLで結果を受け取ります。完全な契約は非同期タスクAPIリファレンスを参照してください。背景除去に関して重要な部分は次のとおりです：

1. model と input（プロンプト、ソース画像URL、出力形状）を伴う POST /v1/tasks は {"code":200,"data":{"taskId":"tk-hiapi-..."}} を返します。この時点ではまだ status フィールドはありません。
2. GET /v1/tasks/{taskId} は data.status を返し、値は queued、handling、archiving、success、fail のいずれかです。success と fail のみが終端状態です。
3. ステータスが success のとき、data.output は {"url","type","expireAt"} の配列です。url は署名付きの短寿命リンク（expireAt はUnixタイムスタンプ）です——すぐにダウンロードし、そのホットリンクを保存しないでください。

モデルについては、image-to-imageエンドポイントを使用し、プロンプトには「背景を除去する」と単独で書くのではなく、置換後の背景を記述してください——これらのモデルは否定的な指示よりも具体的な目標に対してはるかに良く応答します：

Remove the background completely and replace it with a seamless, pure white
studio background. Keep the subject's shape, edges, lighting, and colors
exactly unchanged. Do not add shadows, reflections, or any other objects
that were not in the original image.

最小例：1枚の画像を入力し背景を置換する

seedream-5.0-lite/image-to-image はこの用途で最も安価かつ十分な選択肢です——prompt、image_urls、aspect_ratio、resolution を受け付けます（2Kまたは4Kのみ対応。このエンドポイントに1Kのティアはなく、n や seed のような未知のフィールドは400で直接拒否されます）。

import os
import time
import requests

API = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

BACKGROUND_PROMPT = (
    "Remove the background completely and replace it with a seamless, pure "
    "white studio background. Keep the subject's shape, edges, lighting, and "
    "colors exactly unchanged. Do not add shadows, reflections, or any other "
    "objects that were not in the original image."
)

def create_task(model: str, task_input: dict) -> str:
    resp = requests.post(f"{API}/tasks", headers=HEADERS,
                          json={"model": model, "input": task_input}, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 180, poll_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task {task_id} failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still {task['status']} after {timeout_s}s")

task_id = create_task("seedream-5.0-lite/image-to-image", {
    "prompt": BACKGROUND_PROMPT,
    "image_urls": ["https://your-cdn.example.com/product-photo.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "2K",
})
task = wait_task(task_id)
image_bytes = requests.get(task["output"][0]["url"], timeout=60).content

with open("product-no-bg.png", "wb") as f:
    f.write(image_bytes)

これがループ全体です：送信、ポーリング、ダウンロード。パイプラインに組み込む前に、素早くノーコードで検証したい場合は、AIプロダクトフォトラボがブラウザ上で同種の背景置換を実行できます。

商品カタログのバッチ処理

実際の商品カタログには数十〜数百枚の画像があり、タスクAPIにはネイティブのバッチエンドポイントがありません——個々のタスク送信を自分で展開し、それらを並行してポーリングする必要があります：

from concurrent.futures import ThreadPoolExecutor, as_completed

def remove_background(image_url: str, aspect_ratio: str = "1:1") -> str:
    task_id = create_task("seedream-5.0-lite/image-to-image", {
        "prompt": BACKGROUND_PROMPT,
        "image_urls": [image_url],
        "aspect_ratio": aspect_ratio,
        "resolution": "2K",
    })
    task = wait_task(task_id)
    return task["output"][0]["url"]

source_urls = [
    "https://your-cdn.example.com/sku-1001.jpg",
    "https://your-cdn.example.com/sku-1002.jpg",
    # ...
]

results = {}
with ThreadPoolExecutor(max_workers=5) as pool:
    futures = {pool.submit(remove_background, url): url for url in source_urls}
    for future in as_completed(futures):
        url = futures[future]
        try:
            results[url] = future.result()
        except Exception as exc:
            results[url] = None
            print(f"failed: {url}: {exc}")

max_workers は適度に保ってください——多数の同時タスクに対して頻繁にポーリングしすぎてもリクエスト枠を消費するだけで、生成は速くなりません。各タスクの実時間は主にモデルの推論によって決まり、ポーリング頻度によるものではないからです。

本番環境の堅牢化：正確な構図、コールバック、冪等性、エラー

正確な商品構図を保つ。カタログ作業では、モデルが構図を変えたり被写体をわずかに切り取ったりすることは通常許容できません——入力で中央に配置された靴は、出力でも中央に保たれる必要があります。seedream-5.0-pro/image-to-image はliteティアがサポートしない aspect_ratio 値 match_input_image をサポートし、出力キャンバスを固定比率に強制するのではなく入力画像自身のサイズに固定します。また1回の呼び出しで最大10個の image_urls を受け付け、resolution は 1K/2K に制限されます（liteとは異なる解像度セット——seedreamの各エンドポイントが同じschemaを持つと仮定しないでください。各エンドポイントには独自のenumがあります）。構図を正確に一致させる必要がある純粋な背景除去・置換作業にはこれが選ぶべきティアで、1枚あたりのコストは高くなります——現在の料金は料金を参照してください。

1回の呼び出しで1枚の画像を処理するのではなく、複数のソースアングル（例えば同じ商品の正面図と側面図）を一度に参照する必要がある場合、nano-banana-2 が妥当な代替案です——image_urls ではなく image_input で参照画像を受け付け、resolution は 1K/2K/4K を取れます。

ポーリングの代わりにコールバックを使う。実際の規模のバッチタスクでは、webhookがポーリングより優れています：input の兄弟として callback オブジェクトを追加してください——その内部にネストしてはいけません。POST /v1/tasks はそのような構造を拒否します：

task_input = {
    "prompt": BACKGROUND_PROMPT,
    "image_urls": [image_url],
    "aspect_ratio": "1:1",
    "resolution": "2K",
}
resp = requests.post(f"{API}/tasks", headers=HEADERS, json={
    "model": "seedream-5.0-lite/image-to-image",
    "input": task_input,
    "callback": {"url": "https://your-service.example.com/hooks/hiapi", "when": "final"},
}, timeout=60)

タスクが終端状態に達すると、hiapiは GET /v1/tasks/{taskId} が返すのと同じ data オブジェクトをコールバックURLにPOSTします。サーバー側でコールバックの真正性を検証したい場合は、非同期タスクリファレンスにあるオプションの X-HiAPI-Signature HMACヘッダーを参照してください。

冪等性。POST /v1/tasks には文書化された idempotency_key フィールドはありません——アプリケーション層で冪等性を構築してください。小さなストレージ（データベースの行、Redisキー、あるいはワンオフスクリプトならローカルファイル）を使い、(image_url, prompt, model) のハッシュをキーとして、新しいタスクを送信する前にそのキーに保存済みの taskId または出力URLがあるか確認します。バッチタスクが途中でクラッシュして再実行された場合、処理済み画像の二重課金をスキップでき、静かにコストを増やすことを避けられます。

エラー処理——3つの異なる形態を同じように扱わないでください：

• リクエスト検証（作成時の不正な入力）——HTTP 400、フラット構造：{"code":400,"error_code":"INVALID_REQUEST","message":"...","data":null}。これは input 辞書がモデルschemaと一致していないことを意味します——フィールド名の綴り間違いや誤ったenum値を確認してください。
• 認証失敗——HTTP 401、ネスト方法が異なります：{"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}。APIキーの欠落/期限切れであり、リクエストの誤りではありません——リトライせず、キーを修正してください。
• タスクレベルの失敗（リクエストは有効だが生成自体が失敗）——ポーリング時に現れます：data.status == "fail"、data.error が失敗理由を説明します。これはリトライ可能です。一時的な上流エラーは再送信で成功する可能性があります。

if task["status"] == "fail":
    err = task.get("error") or {}
    # log err["code"] / err["message"], then decide: retry, skip, or alert

3つすべてを1つの except Exception にまとめないでください——401をループでリトライしてもレート制限を消費するだけで決して成功せず、タスクレベルの fail は2回目の試行で本当に成功する可能性があります。

次のステップ

• 非同期タスクAPIリファレンス——完全なライフサイクル、コールバック署名、すべての状態値
• seedream-5.0-lite/image-to-image と seedream-5.0-pro/image-to-image のモデルページ——ライブschemaと例
• 非同期タスクパイプラインの構築——背景除去がより大きな生成パイプラインの一段階である場合
• hiapiタスクのコールバックが発火しない問題の修正——webhookが沈黙している場合のデバッグチェックリスト
• Flux 2 Klein 9B image-to-imageプロンプト——別のi2iモデルのプロンプトパターンで、比較に利用可能
• AIプロダクトフォトラボ——同じワークフローのノーコード版

よくある質問

これは本当に背景を除去しますか、それとも単に上書きするだけですか？機能的にはどちらも同じです——モデルは保持された被写体の周囲のキャンバス全体を再生成するため、エッジ検出の切り抜きツールのように残留マスクやギザギザの縁が残りません。代償として、「それ以外はすべて変更しない」とプロンプトで明示する必要があります。そうしないと、モデルは被写体ごと喜んで再スタイル化してしまいます。

単色背景ではなく透明PNGを取得できますか？プロンプトで直接要求し（例：「背景を透明に置き換える」または「透明背景で被写体を分離する」）、モデルが output_format フィールドをサポートする場合はPNG出力を要求してください——サポート状況はモデルによって異なるため、利用可能と仮定する前に特定のモデルのページを確認してください。

なぜ画像が元画像と一致せず、再構図されて返ってくるのですか？aspect_ratio のenumに match_input_image が含まれないティアを使用している可能性が高いです——lite/4.5ティアでは固定比率を選択するため、ソース画像に対して切り取られたり黒帯が付いたりする可能性があります。seedream-5.0-pro/image-to-image に切り替え、aspect_ratio を match_input_image に設定してください。

1枚あたりのコストはいくらですか？料金はモデルと解像度ティアによって異なり、時間とともに変化します——自分のコードやドキュメントに数値をハードコードせず、料金を確認してください。

画像URLがまだ公開されていない場合はどうすればよいですか？タスクAPIはサーバー側でURLによって画像を取得するため、認証なしでアクセスできる必要があります。先に任意の公開バケットやCDNパスにアップロードしてください——署名付き/プライベートURLや localhost パスはタスク作成時に失敗するか、（さらに悪いことに）処理中に静かに失敗します。