はじめに
このエンドポイントの機能
prompt の対象を見つけ、それ以外を除去し、透明な背景の PNG を返します。
主な入力
image_url は写真、prompt は残す対象の説明です。autocrop は対象に合わせてキャンバスを切り詰め、refine_edges は輪郭を追加補正します。初期設定は両方オフです。
返される結果
透明 PNG を 1 枚返します。autocrop がオンでなければ元の写真サイズです。
| 項目 | 値 |
|---|---|
| 入力 | 画像 |
| 出力 | 画像 |
| エンドポイント | 画像編集 |
| キャンバス | 写真全体のサイズ、または autocrop でトリミング |
| 輪郭の補正 | 任意の追加処理 ( |
主な機能とハイライト
2 人のうち 1 人を説明で選択
2 人がいるバーで "the woman in the cream sweater" を指定しました。男性とボトル棚は除去され、女性は髪とセーターの輪郭を保ったまま、全体サイズの 1536×864 の透明なキャンバスで返りました。
ワイングラス 1 脚をぴったり切り抜き
autocrop をオンにした "the wine glass in front of the man" は、グラスだけの 130×307 PNG になりました。グラス越しのバーの照明は残るため、新しい背景に置く前に確認してください。
マスクを描く必要なし
ブラシや枠を配置する必要はありません。色、位置、服装を含む短いフレーズで、似た対象を区別できます。
リクエストパラメーター
| パラメーター | 必須 | 説明 |
|---|---|---|
image_url | はい | 対象を含む写真。JPEG、PNG、WebP のアップロードか直接リンクを指定します。 1 文字以上 |
prompt | はい | 必須です。残す対象 1 つの短い説明で、"the red car" や "the woman in the cream sweater" などを指定します。 1 文字以上 · 500 文字以内 |
refine_edges | いいえ | 初期設定はオフです。オンにすると背景除去を追加で行い、残った背景ピクセルや輪郭の透明度を整えます。 デフォルト値: |
autocrop | いいえ | 初期設定はオフで、写真全体のサイズで返します。オンにすると対象の周囲にぴったり合わせて切り詰めます。 デフォルト値: |
料金
$0.024 / 枚
抽出ごとの定額です。説明、輪郭補正、トリミングで料金は変わりません。失敗したリクエストには課金されません。
ユースケース
要素の多い写真から商品を抽出
ライフスタイル写真からボトル、バッグ、靴を 1 つ切り抜き、カタログに使えます。周囲を手作業でレタッチする必要はありません。
集合写真から 1 人を選択
通常の背景除去は手前の人物全員を残しますが、ここでは残す人物を指定し、他の人物は背景と一緒に除去します。
コラージュやサムネイルの素材
対象の周囲で切り詰め、新しい背景、動画のサムネイル、スライドに配置します。
プロンプトガイドと実践のヒント
対象を 1 つ説明します
prompt に "the red car" や "the woman on the right" のような短い名詞句を書きます。似た対象が複数ある場合は色、位置、服装の特徴を加えます。
キャンバスを選びます
autocrop をオフにすると写真全体のサイズで返り、元の位置に重ねられます。オンにすると対象に合わせた PNG になり、商品カードやステッカーに使えます。
必要に応じて輪郭を整えます
refine_edgesをオンにすると背景除去を追加で実行し、残ったピクセルや輪郭の透明度を整えます。髪や柔らかい輪郭に役立ちます。
はじめに
Object Extractor はテキストの説明で写真から対象を 1 つ抽出し、透明な背景で返します。通常の背景除去が手前の被写体をすべて残すのに対し、指定した対象だけを残します。
リクエスト
{
"image_url": "https://example.com/bar.jpg",
"prompt": "the woman in the cream sweater",
"refine_edges": true,
"autocrop": false
}
必須項目は image_url と prompt の 2 つです。refine_edges は背景除去を追加で行い、輪郭に残ったピクセルを整えます。autocrop は写真全体のサイズを保つ代わりに、対象に合わせてキャンバスを切り詰めます。
テストで確認した結果
1536×864 のバーで "the woman in the cream sweater" を指定すると、約 17 秒後に女性だけが 1536×864 で返り、髪やセーターの輪郭もきれいでした。手のワイングラスと、寄りかかっていたテーブルの細い部分も残りました。autocrop をオンにした "the wine glass in front of the man" は 130×307 PNG になり、グラス越しの背景は内部に残りました。両手で持つマグカップは指の部分が欠けて返りました。説明なしでは写真はそのまま返りました。
タスクの流れ
対象の切り抜き処理は非同期です。タスクを作成して完了を待ち、透過 PNG を SpicyAPI ストレージからダウンロードします。抽出ごとの定額で、失敗したリクエストには課金されません。
ヒント
- 似た対象は具体的に指定します。"the bottle" より "the taller bottle on the left" が適切です。
- 後で元の位置に戻す場合は
autocropをオフにします。 - すべての被写体を一度に残すなら Background Remover (
/models/background-remover-v1) のほうが簡単です。
API クイックスタート
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/object-extractor-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
認証、完全なスキーマ、ポーリング、エラー処理は API リファレンスを参照してください。




