image.replace_background
[paid: $0.03] Replace a photo's background with a generated scene (Bria FIBO Edit). With no mask, the subject is cut out first (plus [paid: $0.0005]) and the original subject is laid back over the new scene; or pass a mask covering the background (white = background). Returns JSON {images:[{url, asset_key, download_url?, width, height}], price, next} plus a preview; images are stored in this workspace, never provider links, and a result with no download_url says why in download_url_unavailable. Refuses: SIMPLER_MEDIA_INPUT_MISSING (pass the url or the asset_key), SIMPLER_MEDIA_FOREIGN_KEY (use this workspace's asset_key), SIMPLER_MEDIA_URL_REFUSED (use https, data:image or an asset_key), SIMPLER_MEDIA_PIN_TOO_LARGE (under 20MB), VALIDATION_ERROR on an empty prompt (describe the scene), SIMPLER_EDIT_BACKDROP_NO_SUBJECT (no mask and no clear subject: pass a background mask), SIMPLER_IMAGE_PROMPT_REFUSED names the label (sexual, minor, real_person or other_unsafe): rewrite the prompt without it, for example no real person's name or likeness; SIMPLER_IMAGE_PROMPT_CHECK_UNAVAILABLE (the safety check is down, nothing charged: retry later); SIMPLER_IMAGE_OUTPUT_FLAGGED (the output failed the content check and was refunded: change the prompt); SIMPLER_IMAGE_OUTPUT_SCAN_UNAVAILABLE (outputs cannot be checked right now, nothing charged: retry later), INSUFFICIENT_CREDITS (add credits). SIMPLER_EDIT_RESULT_UNDELIVERED means the charge was refunded: retry. NEXT: pass images[0].asset_key as image_asset_key to the next image.* tool, or open download_url when the result carries one.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>"
},
"name": "image.replace_background"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Scene description. | |
| mask_url | No | Optional background mask (white = background); omit it to cut the subject out automatically: a public https URL, a data:image/...;base64 URL, or the url/url_path of an earlier image result (max 20MB; PNG, JPEG, WebP or GIF; SVG is refused). Pass this or the matching *_asset_key, not both. | |
| image_url | No | Source photo: a public https URL, a data:image/...;base64 URL, or the url/url_path of an earlier image result (max 20MB; PNG, JPEG, WebP or GIF; SVG is refused). Pass this or the matching *_asset_key, not both. | |
| request_ref | No | Optional idempotency key (1-64 chars: letters, digits, . _ : -). Retrying with the same request_ref and the same arguments within 24 hours returns the first result at $0 with replayed: true; the same request_ref with different arguments is refused (SIMPLER_IMAGE_REQUEST_REF_CONFLICT), and so is a retry whose first result was deleted since (SIMPLER_IMAGE_REQUEST_REF_RESULT_DELETED): send a new request_ref to run it again. | |
| mask_asset_key | No | Optional background mask (white = background); omit it to cut the subject out automatically, as the asset_key of an earlier image result for this workspace (edit-projects/<tenant>/... or images/<tenant>/...). A key from another workspace is refused (SIMPLER_MEDIA_FOREIGN_KEY). | |
| preview_format | No | Preview block after the JSON, at most 384px on the long edge and never charged: png, jpeg or none. Left out, a PNG result gets a png preview and a JPEG or WebP result a jpeg one. A result with no preview says why in preview_unavailable. | |
| image_asset_key | No | Source photo, as the asset_key of an earlier image result for this workspace (edit-projects/<tenant>/... or images/<tenant>/...). A key from another workspace is refused (SIMPLER_MEDIA_FOREIGN_KEY). |