Recraft 背景除去 API：実行可能なサンプル

ほとんどの背景除去 API では、汎用の画像編集モデルを選び、適切なプロンプトで被写体を切り抜くよう誘導する必要があります。recraft/remove-background はこのステップを省きます。これは専用モデルで、画像 URL を受け取り、髪の毛や毛皮レベルのエッジディテールを保持した透過 PNG を返します。プロンプトもネガティブプロンプトも強度パラメータも不要 —— ソース画像を入力するだけで、切り抜きが出力されます。

このガイドでは、完全かつテスト済みの呼び出しを一通り解説します。リクエスト構造、実際に受け取るレスポンス、そしてバッチ処理タスクがあるエッジケースで止まらないようにするための本番向けパターン（コールバック、冪等性、エラー処理）です。

前提条件：

• あなたのコンソールから hiapi API キーを取得する
• Python 3.9 以上で requests をインストール（pip install requests）、または curl を直接使用
• ソース画像が公開 URL 上にあること —— hiapi のタスク API はファイルアップロードではなく URL 経由で画像を取得します。形式は PNG、JPG、WEBP で、最大 5MB、最大 1600 万ピクセル、両方の次元が 256 から 4096 ピクセルの間である必要があります。

リクエスト

hiapi 上のすべての生成モデルと同様に、recraft/remove-background は共有の非同期タスク API を通じて動作します。POST /v1/tasks に model と input を付けて送信すると、すぐに taskId が返され、切り抜きはバックグラウンドで実行されます。完全な契約 —— リクエストヘッダー、冪等キー、ステータスコード —— はタスクの作成にまとめて記載されています。モデル固有の部分は input で、このモデルの場合はフィールドが 1 つだけです：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url はこのモデルが受け付ける唯一のフィールドです —— format、response_format、サイズパラメータはありません。それ以外の内容を送信すると、API はモデルに到達する前にスキーマエラーでリクエスト全体を拒否します（下記のエラーを参照）。出力は常に透過 PNG です。

結果のポーリング

上記のレスポンスから taskId を取得し、GET /v1/tasks/{taskId} を data.status が終態に達するまでポーリングします。ステータス列挙はプラットフォーム上のすべてのモデルで一貫しています：queued → handling → archiving → success（または fail）。このモデルの実際の実行は通常 10 秒未満で完了します：

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

ステータスが success のとき、data.output は要素を 1 つだけ含む配列です：

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url は一時リンクです —— expireAt はおよそ 1 週間後の Unix タイムスタンプであり、永続的な CDN アドレスではありません。タスクが成功したらすぐにバイトをダウンロードして、自分のストレージに保存してください：

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

本番向けパターン

ループポーリングの代わりにコールバックを使用する。 作成時に callback.url を指定すると、hiapi はタスク完了時に最終結果を POST してくれます。ポーリングループでリクエストを消費する必要はありません：

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" は、終態（success または fail）のときに 1 回だけコールバックを受け取ることを意味し、各中間ステータスごとに 1 回ではありません。商品写真のバッチ処理にはこれが適切なデフォルトであり、画像ごとにポーリングループを維持する必要がありません。

冪等性。 リクエストが手元でタイムアウトしたものの、実際には hiapi に到達していた場合、同じ Idempotency-Key リクエストヘッダー（タスクの作成に記載）で再試行すると、元のタスクが返され、2 回目の切り抜きに対して課金されることはありません。ネットワークエラー時に再試行するバッチ処理タスクには設定する価値があります。

エラー —— 1 つではなく 2 つの形態。 不正な形式のリクエストと認証失敗は異なるエンベロープで返されるため、片方だけをチェックするコードはもう片方を静かに見逃してしまいます：

// 入力エラー（スキーマ検証）—— HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API キーが無効または期限切れ —— HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

まず error_code をチェックし、次に error.code にフォールバックしてください —— すべての失敗が同じトップレベルキーを持つと仮定しないでください。

価格。 1 画像あたり $0.01（20 credits）で、入力解像度に関係なく一律で計算されます。現在の価格は常に価格ページに記載されています。

切り抜きだけでなく、背景の置き換えが必要な場合

recraft/remove-background は透過切り抜きのみを生成します —— 塗りつぶしもシーンも含まれません。同じ呼び出しでスタジオ背景やライフスタイルシーンに置き換えることが目的なら、それは別のタスクです：被写体を保持しつつ周囲の背景を再生成するよう指示する image-to-image モデルを使用します。その方法と、通常の切り抜きより高いコストを払う価値がある場合については、API で画像の背景を除去する：プロンプトベースの編集をご覧ください。

よくある質問

recraft/remove-background はプロンプトや強度パラメータを受け付けますか？ いいえ。スキーマは厳格です —— image_url が受け付ける唯一のフィールドです。format や response_format などの余分なフィールドを送信すると、400 が返され、「additional properties not allowed」というメッセージが付きます。

どの画像形式とサイズがサポートされていますか？ 入力：PNG、JPG、WEBP、最大 5MB、最大 1600 万ピクセル、両方の次元が 256 から 4096 ピクセルの間。出力は常にアルファチャネル付き PNG です。

URL ではなくローカルファイルをアップロードできますか？ いいえ —— image_url は hiapi サーバーが取得できる公開 http(s):// URL である必要があります。先にオブジェクトストレージや CDN にアップロードしてください。

出力 URL の有効期限はどれくらいですか？ 各出力エントリの expireAt フィールドは Unix タイムスタンプで、通常はおよそ 1 週間後です。一時リンクとして扱い、タスク成功後すぐにバイトを自分のストレージにコピーしてください —— temp.hiapi.ai リンクを長期間保存しないでください。

これは数百枚の商品写真のバッチ処理に使えますか？ はい —— 各画像に対して 1 つのタスクを送信し、callback.url を共有して、hiapi に結果をプッシュバックさせます。1 つずつポーリングする必要はありません。1 画像 $0.01 の計算で、1,000 枚のカタログ処理は生成に $10 かかります。