spicyapi/object-eraser-v1/editにimage_urlと、短いprompt、mask_url、またはその両方を渡します。マスクでは白が除去、黒が保持を表し、ピクセル寸法は元画像と一致させる必要があります。料金は、1回のリクエストで何個の物を除去しても出力画像1枚あたり0.03ドルです。結果は元のキャンバスサイズのままで、選択した領域は周囲の場面の内容で埋められます。
プロンプトかマスクかを選ぶ
周囲に余白があり、はっきり区別できる物なら、短い説明から始めます。
手前右の椅子の脚のそばの床にある白い紙コップ
名詞、見える色や素材、位置を書きます。「場面をきれいに高級感のある雰囲気に」では、何を消すのか特定できません。プロンプトは1〜1000文字まで入力できますが、長くしても選択が正確になるわけではありません。
| 状況 | 使う入力 |
|---|---|
| 何もない床にあるはっきりした紙コップ1個 | そのコップを指すprompt |
| 似たコップが2個あり、消したいのは1個だけ | 対象のコップに重ねたmask_url |
| 細いケーブル、またはフレーム端に接する物 | mask_url。説明では外れやすい |
| 説明が別の物を指すおそれがある | 両方を送り、同じ対象を説明しつつ印を付ける |
| 椅子を透過背景で切り抜きたい | 背景除去 |
| 写真の周りに余白を足したい | 整理後にアウトペインティング |
説明がどこにも当てはまらない場合、画像は変更されずに返り、タスク自体は成功扱いになります。除去できたと判断する前に、出力を元画像と見比べてください。
選択対象の例を描いたイラスト。印を付けた物はすべて残っており、APIの出力ではありません。
まずPlaygroundで試す
- Object Eraserのページを開き、PlaygroundタブのForm表示のまま、残高のあるアカウントでサインインして実行します。
- Input imageに写真を追加します（JPG、PNG、WebP、10 MBまで）。ファイルをドロップするか、Asset URLとAdd URLでリンクを貼るか、参照して選びます。
- Promptに対象を説明するか、Maskに白黒画像を追加するか、両方を入力します。フォームはどちらか一方以上を必要とします。
- Output formatはPNGのままにして（JPEGとWebPはファイルが小さくなります）実行します。料金は1枚0.03ドルです。
- 結果を元画像とマスクの隣に開き、何か残っていたら下の失敗表を使います。
Request bodyパネルにはAPIが受け取るのと同じJSONが表示されるので、ここで動いたプロンプトやマスクはそのままコードに写せます。ここで失敗するなら、コードを書く前にプロンプトかマスクを直してください。
送信する画像そのものに合わせてマスクを作る
領域がすでに分かっている場合（検出器のボックスやUIでの選択など）は、コードでマスクを生成します。サイズは元画像から取るので、常に一致します。
from PIL import Image, ImageDraw
src = Image.open("source.jpg") # apply EXIF rotation and crop first
mask = Image.new("L", src.size, 0) # black = keep
bbox = (src.width // 4, src.height // 3, src.width // 2, src.height // 2)
# Example coordinates only: adjust this box to the unwanted object in your photo.
ImageDraw.Draw(mask).rectangle(bbox, fill=255) # white = remove
mask.save("mask.png")2400×1600の元画像で不規則な形を扱うなら、画像エディタで2400×1600のマスクを用意します。
- 先に元画像の回転とトリミングを終え、その作業用画像を保存します。
- キャンバス全体の黒いレイヤーを追加し、描く間は不透明度を下げて対象が見えるようにします。
- コップを白く塗ります。不要な縁と接地の影も含め、余白がある所では少し広めにします。椅子の脚は黒のままにします。
- レイヤーの不透明度を元に戻し、単独で不透明な白黒のPNGとして書き出します。暗くした写真や色付きの注釈は不可です。
- 書き出したマスクを作業用画像に重ね、白い領域を確認します。
縦横比が同じだけでは足りません。両ファイルの幅、高さ、トリミング、向きを一致させます。近くに他の物がない場所なら、少し大きめの形でも問題ありません。モデルページの例では、フレーム端のラックに使うマスクは、写真と同じサイズの黒いキャンバスに、ラックの上へ単純な白い長方形を1つ置いたものです。
影や反射は、物の輪郭の外側にあることがあります。不要な反射は、別の白い領域として塗ります。コップの影が椅子の接地の影と重なる場所では、暗い部分を丸ごと白くしないでください。椅子が浮いて見えることがあります。マスクは除去する範囲を示すだけで、隠れた床や商品の形状は与えません。
大きな除去や重なる除去は別々のパスで行い、各マスクは直前に採用した出力を基に作ります。小さな物2個を1回のリクエストで処理すると0.03ドル、別々の2回なら0.06ドルです。古い選択が新しい写真を黙って編集しないよう、マスクと画像のファイル名は対にして管理します。
コードから実行する
Python SDKをインストールし（pip install spicyapi）、サーバー環境にSPICY_API_KEYを設定して、以下のリクエストを実行します。モデルページの例の写真を使うので、そのまま動きます。手元のファイルはclient.upload_fileを通すとspicy://アドレスで返ります。マスクを使うときは、写真と同じピクセルサイズの自分のファイルで"mask_url"を追加します。
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
task = client.create_task(
model="spicyapi/object-eraser-v1/edit",
input_data={
"image_url": "https://cdn.spicyapi.ai/models/examples/inputs/fbc8d531c80e6d0d.jpeg",
"prompt": "the wooden ladle lying across the sauna stones at the left",
"output_format": "png",
},
idempotency_key=str(uuid.uuid4()),
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"]) # copy the image to your own storage nowアップロード、作成、待機、ダウンロード、再試行、エラーコードはタスクガイドとPython SDKリファレンスで説明しています。生成ファイルの保存期間は最長14日なので、結果は自分のストレージにコピーしてください。
エージェントに実行させる
アシスタントに編集を任せる場合、公式の3つのツールはいずれも料金を表示し、有料の呼び出しの前に確認を求めます。
- CLI。 写真とマスクをアップロードしてから、タスクを作成します。
``bash spicyapi files upload photo.jpg spicyapi tasks create --model spicyapi/object-eraser-v1/edit --input-file input.json --wait ``
返ってきたspicy://アドレスを、input.jsonのimage_urlとmask_urlに入れます。CLIドキュメントを参照してください。npx @spicyapi/cliならインストール不要です。
- MCPサーバー。 アシスタントにMCPサーバーを追加し、「Object Eraserでこの写真から白い紙コップを消して。ファイルは/path/to/photo.jpgにある」と依頼します。
spicyapi_upload_fileでファイルをアップロードし、料金の確認で止まるspicyapi_task_createを呼び、続いてspicyapi_task_waitを呼びます。 - スキル。
npx skills add spicyapi-ai/spicy-skillでAgent Skillをインストールすると、コーディングアシスタントがフィールドを推測せず、最新のモデルスキーマを読みます。
目の前の失敗に合わせて直す
erased.pngを元画像とマスクの隣に開きます。まず選択範囲が保持する内容と接する部分を、次に補完の中央を確認します。
| 結果 | 変更すること |
|---|---|
| プロンプトだけのリクエストでコップが残っている | そのコップに重ねたマスクに切り替える。 |
| ケーブルが端に残る | フル解像度のマスクで、見える長さ全体を白く塗る。 |
| うっすら輪郭が残る | 隣り合う商品の縁を覆わない範囲で、選択を物の縁より少し外へ広げる。 |
| コップは消えたが暗い楕円が残る | コップの接地の影を、椅子の影とは別にマスクへ加える。 |
| 椅子の脚の一部が誤って再構成される | 脚を覆っている部分のマスクを縮める。コップが脚そのものを隠しているなら、別の元写真を使う。 |
| 差分チェックで画像全体が変わって見える | 先に回転とサイズをそろえる。圧縮ノイズだけでは編集とは言えない。動かない目印を確認する。 |
| リクエストが400を返す | プロンプトとマスクの両方が欠けていないか、strength、mask_blur、transparent_backgroundのようにモデルにないフィールドを送っていないか確認する。拒否されたリクエストには課金されない。 |
影と反射の確認を描いたイラスト。除去が完了した状態は示していません。
モデルは隠れた背景を再構成しますが、物の後ろに実際に何があったかを明らかにすることはできません。商品ページでは、床がきれいに見えるからといって、作り出された椅子の接合部や変わった張地の縫い目を受け入れないでください。除去した物が、商品ページで正確に見せるべき細部を隠していた場合は、撮り直します。
SpicyAPIはこのモデルに安全性チェックを実行しません。何を返すかはモデル自身が決めます。
採用した出力と一緒に元画像とマスクを保管し、特定の残った物がある場合に限って追加のパスを行います。モデルページのExamplesタブには、実際のビフォー・アフターの結果が載っています。
