## Basic model info - Model name: meta/meta sam-3.1 - Model description: Meta Segment Anything Model 3.1 provides upgraded prompted image and video segmentation with rendered-mask and RLE outputs. - Endpoint name: image-rle ## Model schema The model schema is defined in the OpenAPI schema: [OpenAPI Schema](https://oapi.sunra.ai/main/meta/sam-3.1/a5de3f0ac9fefd6e6d291f0105d486b4f8b7970e.json) ### Model input schema The model input schema is: ```json { "additionalProperties": false, "properties": { "prompt": { "default": "wheel", "title": "Prompt", "type": "string" }, "image_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "string" } ], "description": "Image to segment.", "title": "Image Url" }, "apply_mask": { "default": true, "title": "Apply Mask", "type": "boolean" }, "box_prompts": { "items": { "additionalProperties": false, "properties": { "object_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Object Id" }, "x_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X Max" }, "x_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X Min" }, "y_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Y Max" }, "y_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Y Min" } }, "title": "BoxPrompt", "type": "object" }, "title": "Box Prompts", "type": "array" }, "include_boxes": { "default": false, "title": "Include Boxes", "type": "boolean" }, "include_scores": { "default": false, "title": "Include Scores", "type": "boolean" }, "max_masks": { "default": 3, "maximum": 32, "minimum": 1, "title": "Max Masks", "type": "integer" }, "output_format": { "default": "png", "enum": [ "jpeg", "png", "webp" ], "title": "Output Format", "type": "string" }, "point_prompts": { "items": { "additionalProperties": false, "properties": { "label": { "anyOf": [ { "enum": [ 0, 1 ], "type": "integer" }, { "type": "null" } ], "title": "Label" }, "object_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Object Id" }, "x": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X" }, "y": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Y" } }, "title": "PointPrompt", "type": "object" }, "title": "Point Prompts", "type": "array" }, "return_multiple_masks": { "default": false, "title": "Return Multiple Masks", "type": "boolean" }, "sync_mode": { "default": false, "title": "Sync Mode", "type": "boolean" } }, "required": [ "image_url" ], "title": "Sam31ImageInput", "type": "object" } ``` ### Model output schema The model output schema is: ```json { "anyOf": [ { "additionalProperties": false, "properties": { "boxes": { "title": "Boxes" }, "image": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] }, "masks": { "items": { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, "title": "Masks", "type": "array" }, "metadata": { "title": "Metadata" }, "scores": { "title": "Scores" } }, "required": [ "masks" ], "title": "ImageOutput", "type": "object" }, { "additionalProperties": false, "properties": { "boundingbox_frames_zip": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] }, "boxes": { "title": "Boxes" }, "metadata": { "title": "Metadata" }, "objects": { "title": "Objects" }, "rle": { "description": "Complete inline RLE data for small results. Exactly one of rle and rle_json is returned; large results use rle_json and are never truncated.", "title": "Rle" }, "rle_json": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ], "description": "JSON asset containing the complete rle, boxes, metadata, scores, and objects values for large results. Its content_type is application/json. Exactly one of rle and rle_json is returned." }, "rle_summary": { "anyOf": [ { "additionalProperties": false, "properties": { "delivery": { "const": "file", "description": "The complete structured RLE result is stored in rle_json.", "title": "Delivery", "type": "string" }, "json_bytes": { "description": "Exact UTF-8 byte size of the JSON artifact.", "minimum": 1, "title": "Json Bytes", "type": "integer" }, "object_entries": { "description": "Top-level object-track entry count.", "minimum": 0, "title": "Object Entries", "type": "integer" }, "rle_entries": { "description": "Top-level RLE entry count.", "minimum": 0, "title": "Rle Entries", "type": "integer" } }, "required": [ "delivery", "json_bytes", "rle_entries", "object_entries" ], "title": "RleSummary", "type": "object" }, { "type": "null" } ], "description": "Delivery metadata present exactly when rle_json is returned." }, "scores": { "title": "Scores" }, "units": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Units" } }, "title": "RleOutput", "type": "object" }, { "additionalProperties": false, "properties": { "boundingbox_frames_zip": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] }, "units": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Units" }, "video": { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" } }, "required": [ "video" ], "title": "VideoOutput", "type": "object" } ], "title": "Response Get Request Result Requests Request Id Get" } ``` ## Example inputs and outputs Use the following example inputs and outputs to understand the model. ### Input example ```json { "prompt": "wheel", "image_url": "", "apply_mask": true, "box_prompts": [ ], "include_boxes": false, "include_scores": false, "max_masks": 3, "output_format": "png", "point_prompts": [ ], "return_multiple_masks": false, "sync_mode": false } ``` ### Output example ```json { } ``` ## Model code examples ### JavaScript ```javascript import { sunra } from "@sunra/client"; const result = await sunra.subscribe("meta/sam-3.1/image-rle", { input: { image_url: '', output_format: 'png', include_boxes: false, max_masks: 3, prompt: 'wheel', point_prompts: [], box_prompts: [], sync_mode: false, return_multiple_masks: false, include_scores: false, apply_mask: true }, logs: true, onQueueUpdate: (update) => { console.log(`Status Update: ${update.status}, Request ID: ${update.request_id}`); }, }); console.log(result.data); console.log(result.requestId); ``` ### Python ```python import sunra_client result = sunra_client.subscribe( "meta/sam-3.1/image-rle", arguments={ "image_url": "", "output_format": "png", "include_boxes": False, "max_masks": 3, "prompt": "wheel", "point_prompts": [], "box_prompts": [], "sync_mode": False, "return_multiple_masks": False, "include_scores": False, "apply_mask": True }, with_logs=True, on_enqueue=print, on_queue_update=print, ) print(result) ``` ### Java ```java import ai.sunra.client.*; import java.util.Map; import com.google.gson.JsonObject; var client = SunraClient.withEnvCredentials(); var response = client.subscribe( "meta/sam-3.1/image-rle", SubscribeOptions.builder() .input(Map.of( "image_url", "", "output_format", "png", "include_boxes", false, "max_masks", 3, "prompt", "wheel", "point_prompts", , "box_prompts", , "sync_mode", false, "return_multiple_masks", false, "include_scores", false, "apply_mask", true)) .resultType(JsonObject.class) .onQueueUpdate(update -> System.out.printf( "\nStatus Update: %s, Request ID: %s%n", update.getStatus(), update.getRequestId() )) .logs(true) .build() ); System.out.println("Completed!"); System.out.println(response.getData()); ``` ### Kotlin ```kotlin import ai.sunra.client.kt.* import com.google.gson.JsonObject val client = createSunraClient() val response = client.subscribe( endpointId = "meta/sam-3.1/image-rle", input = mapOf( "image_url" to "", "output_format" to "png", "include_boxes" to false, "max_masks" to 3, "prompt" to "wheel", "point_prompts" to , "box_prompts" to , "sync_mode" to false, "return_multiple_masks" to false, "include_scores" to false, "apply_mask" to true), options = ai.sunra.client.kt.SubscribeOptions(logs = true), onUpdate = { update -> println("\nStatus Update: ${update.status}, Request ID: ${update.requestId}") } ) println("Completed!") println(response.data) ``` ### Curl ```bash curl --request POST \ --url https://api.sunra.ai/v1/queue/meta/sam-3.1/image-rle \ --header "Authorization: Key $SUNRA_KEY" \ --header "Content-Type: application/json" \ --data '{"image_url":"","output_format":"png","include_boxes":false,"max_masks":3,"prompt":"wheel","point_prompts":[],"box_prompts":[],"sync_mode":false,"return_multiple_masks":false,"include_scores":false,"apply_mask":true}' ``` ## Model readme > SAM 3.1 segments objects from text, point, or box prompts. Image and video endpoints return rendered masks; the RLE variants expose compact masks and optional object-level RLE data. > > Videos are limited to 10 seconds and 240 counted input frames. Video billing uses one unit per started block of 16 input frames.