チュートリアル

hiapi API で 851-labs/background-remover を使う方法：curl、Python、実行可能なリクエスト

Sep 5, 2026

851-labs/background-remover は、API を 1 回呼び出すだけで、商品・ポートレート・ペットの写真を透明 PNG に変換できます —— プロンプト不要、マスク不要、アスペクト比の設定も不要です。本記事では、正確なリクエスト構造、実行可能な curl コマンド、バックエンドにそのまま組み込める Python スクリプト、そして最もつまずきやすい schema エラーを紹介します。

準備

hiapi アカウントと、コンソールから取得した API key。
パブリックな HTTPS URL でホストされた画像。タスク API が受け取るのは URL であり、ファイルアップロードではありません —— 元画像がローカルにしかない場合は、まず任意の CDN やオブジェクトストレージに配置してください。

すべてのリクエストは統一タスクエンドポイントに送信します：

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

リクエスト構造（そして唯一必ず覚えておくべきルール）

モデル id は 851-labs/background-remover で、そのまま渡します。その input schema にはフィールドが 1 つだけあります：

フィールド	型	必須	説明
`image_url`	string	はい	`^https?://[^\s]+$` に一致する必要があります —— 直接アクセス可能な http(s) URL。

これが schema のすべてです。コードを書く前に知っておくべき点が 2 つあります：

prompt、mask、background-color、aspect-ratio のフィールドはありません。このエンドポイントは 1 つのことだけを行います —— 前景/背景の分離 —— それ以外は何もしません。後で色を変更したりサイズを調整したりする必要がある場合は、別のモデルを呼び出す必要があります。
余分なフィールドは無視されるのではなく、拒否されます。他のモデルの payload から format や size フィールドを持ち込んだ場合、タスクが始まる前に 400 INVALID_REQUEST: <root>: additional properties 'format' not allowed が返されます。

最小限の実行可能な例：curl

タスクを作成：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "851-labs/background-remover",
    "input": {
      "image_url": "https://your-cdn.example.com/product-shot.jpg"
    }
  }'

送信に成功すると、data 内にタスク id が返されます：

{"code": 200, "data": {"taskId": "tk-hiapi-..."}}

結果をポーリング：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer sk-<your-key>"

実行中、data.status は queued → handling → archiving の順に変化します。完了すると "success" になり、透明 PNG が data.output に現れます：

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

出力 URL は短時間だけ有効です（expireAt に注意）。タスク成功後はすぐにファイルのバイト列をダウンロードしてください —— ホットリンクしたり、元の URL を永続保存したりしないでください。

本番で使える Python：送信、ポーリング、ダウンロード

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def remove_background(image_url: str) -> bytes:
    # 1. タスクを作成
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "851-labs/background-remover",
        "input": {"image_url": image_url},
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. 終状態になるまでポーリング
    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. すぐにダウンロード —— URL は期限切れになる
            png = requests.get(outputs[0]["url"], timeout=120)
            png.raise_for_status()
            return png.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(3)
    raise TimeoutError(f"task {task_id} still running after 300s")


if __name__ == "__main__":
    png = remove_background("https://your-cdn.example.com/product-shot.jpg")
    with open("cutout.png", "wb") as f:
        f.write(png)
    print(f"saved cutout.png ({len(png)} bytes)")

背景除去は軽量な画像タスクであり、通常は 300 秒の締め切りよりはるかに早く完了します —— このタイムアウトは安全網であり、想定実行時間ではありません。

ポーリングの代わりにコールバックを使う

Web バックエンドでは、リクエストハンドラ内でポーリングするのではなく、タスク作成時にコールバックを登録することをお勧めします。callback オブジェクトはトップレベルにあり、model と同じ階層です：

{
  "model": "851-labs/background-remover",
  "input": { "image_url": "https://your-cdn.example.com/product-shot.jpg" },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

callback.when は "final" のみをサポートします —— タスクが success または fail になったときに正確に 1 回 POST を受け取り、進捗イベントは受け取りません。ハンドラは taskId をキーにして、重複配信された webhook が二重に処理されないようにし、さらに GET /v1/tasks/<id> を定期的にスキャンして、エンドポイントが一度も確認していない id をチェックしてください。

エラー処理：本当に重要なエラー

作成時に 400 INVALID_REQUEST —— エラーメッセージが正確なフィールドを指し示します：

メッセージ	原因
`invalid input: image_url: missing required field "image_url"`	`input` が空、またはキー名の綴り間違い
`image_url: 'not-a-url' does not match pattern '^https?://[^\s]+$'`	値が正しい形式の http(s) URL ではない
`<root>: additional properties 'format' not allowed`	このモデルが受け付けないフィールドを送信した

これらのエラーは永続的です —— 同じ payload を再試行しても永遠に失敗します。フィールドを修正してから再送信してください。

作成時に 401 permission_denied —— 問題はリクエストボディではなく、key 自体にあります：

{"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}

コンソールでその key のモデル権限を確認してください。

タスクが status: "fail" を返す —— 作成は成功したが実行自体が失敗した場合（通常はバックエンドが image_url を取得できない）。data.error.code / message を読み取ってください。この種の失敗はバックオフして 1 回再試行しても安全です。

不明または期限切れのタスク id を GET すると 404 が返り、内容は {"code": 404, "data": null, "message": "task not found"} です —— 照合スキャンではこれを「まだ待機中」ではなく終状態として扱うべきです。

次のステップ

851-labs/background-remover モデルページ —— ライブサンプルと現在の価格。
プロンプトベースの編集で画像の背景を除去 —— Seedream ベースの代替案で、背景を除去するだけでなく背景を変更したい場合に適しています。
hiapi 非同期タスク API ドキュメント —— 作成/ポーリング/コールバックの完全なリファレンス。
hiapi 認証ドキュメント —— API key の設定とリクエストヘッダーの形式。
価格 —— 現在の 1 枚あたりの料金。

よくある質問

プロンプトは必要ですか？ いいえ。image_url を 1 つ提供するだけで、モデルが前景と背景を自動的に分離します。

出力は本当に透明ですか？ はい —— 結果はアルファチャンネル付きの PNG で、任意の背景にそのまま合成できます。

同じ呼び出しでアスペクト比、色、背景を変更できますか？ いいえ。このエンドポイントは背景を除去するだけです。色の変更、サイズ調整、背景の置き換えが必要な場合は、この透明 PNG を入力として、画像編集モデルをチェーンで呼び出してください。

なぜ「additional properties '...' not allowed」が返されるのですか？ この schema は image_url という 1 つのフィールドしか受け付けません。他のモデルの payload から持ち込んだあらゆるフィールド —— format、size、background_color、何であれ —— は、黙って無視されるのではなく、そのまま拒否されます。

結果はどう保存すればよいですか？ タスクが status: "success" に達したらすぐにダウンロードしてください。出力 URL は署名付き URL で expireAt があり、長期的なホットリンクには適していません。

料金はいくらですか？ 1 枚あたりの画像使用量に基づいて課金されます。現在の料金は価格ページでご確認ください。