image.segment_at
[paid: $0.01] Segment the object at pixel (x, y) via SAM 2 and return its mask image. 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 with reason SIMPLER_EDIT_TOOL_ARGS_INVALID when x or y is missing or outside 0..16384 (take the point from the user, in the image's pixels), INSUFFICIENT_CREDITS (add credits). SIMPLER_EDIT_RESULT_UNDELIVERED means the charge was refunded: retry. NEXT: pass images[0].asset_key as mask_asset_key to image.inpaint, image.replace_sky or image.replace_background.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | Pixel X of a point on the object (0..16384). | |
| y | Yes | Pixel Y of a point on the object (0..16384). | |
| 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. | |
| 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). |