Start building
SandBase

Appearance

Sam 3

POST/v1/run

Sam 3 Image Rle is Meta's intelligent image editing model. Transform, retouch, and reimagine existing images using text prompts - from background replacement to artistic style conversion.

Request body

Submit an async generation request. The model field selects the model; other fields are model-specific input parameters.

stringmodelrequired

Model identifier. Set to meta/sam-3/image-rle.

Default: meta/sam-3/image-rle

stringpromptrequired

Text prompt for segmentation

Default: wheel

stringimagerequired

URL of the image to be segmented

Optional<string>output_format

The format of the generated image.

Allowed values: jpeg, png

Default: png

Optional<boolean>apply_mask

Apply the mask on the image.

Default: true

Optional<integer>max_masks

Maximum number of masks to return when `return_multiple_masks` is enabled.

Range: 1 to 32

Default: 3

Optional<boolean>include_scores

Whether to include mask confidence scores.

Default: false

Optional<array<object>>box_prompts

Box prompt coordinates (x_min, y_min, x_max, y_max). Multiple boxes supported - use object_id to group boxes for the same object or leave empty for separate objects.

Default:

Optional<boolean>return_multiple_masks

If True, upload and return multiple generated masks as defined by `max_masks`.

Default: false

Optional<string>text_prompt

[DEPRECATED] Use 'prompt' instead. Kept for backward compatibility.

Optional<array<object>>point_prompts

List of point prompts

Default:

Optional<boolean>include_boxes

Whether to include bounding boxes for each mask (when available).

Default: false

Response Schema

The submit endpoint returns a run response. If its status is pending or running, poll GET /v1/run/{id} with the returned opaque ID until it reaches a terminal state.

stringidrequired

Opaque SandBase run identifier. Use it exactly as returned; no prefix is guaranteed.

stringstatusrequired

Current public run status.

Allowed values: pending, running, completed, failed, timeout

Optional<string>model

Public SandBase model name used for this run.

Optional<array<object>>outputs

Present only for completed runs. Each object is capability-specific; inspect the selected model schema for its fields.

Optional<object>error

Present only for failed or timeout runs. Contains a public error type and sanitized message.

Optional<string>error.type

Stable public error category.

Optional<string>error.message

Sanitized error message safe to show to clients.

Optional<object>usage

Usage details when available.

Model capabilities

array<string>capability_tagsrequired

Capabilities declared by the model registry.

Default: image-to-image

stringexecution_moderequired

Execution mode declared by the model registry.

Default: async