Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

Pricing: $0.005/image. Endpoint: POST /v1/models/meta/sam-3/image/runs.
SAM 3 is a unified foundation model for promptable segmentation in images and videos.

​
Overview

​
Pricing

  • Base price: $0.005/image
  • Note: Usage-based, per image

​
SAM 3 API

Endpoint: POST /v1/models/meta/sam-3/image/runs

​
Run the model

​
Python

import requests

response = requests.post(
    "https://api.runflow.io/v1/models/meta/sam-3/image/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "prompt": "keyboard",
            "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
            "apply_mask": False,
            "return_multiple_masks": True
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)

​
Node.js

const response = await fetch(
  "https://api.runflow.io/v1/models/meta/sam-3/image/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "prompt": "keyboard",
            "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
            "apply_mask": false,
            "return_multiple_masks": true
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);

​
cURL

curl -X POST https://api.runflow.io/v1/models/meta/sam-3/image/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "prompt": "keyboard",
        "image_url": "https://v3b.fal.media/files/b/0a92a995/fV5oYdcCV3NAmgWJISpIP_tmpdddcks4v.png",
        "apply_mask": false,
        "return_multiple_masks": true
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON

​
Request parameters

ParameterTypeRequiredDescription
inputobjectrequiredModel input parameters. See “Input schema” below.
callback_urlstring | nulloptionalWebhook URL - POSTed when the run reaches a terminal state.
metadataobject | nulloptionalArbitrary key-value pairs attached to the run.

​
Input schema

FieldTypeRequiredAllowed valuesDescription
promptstringoptionalAnyText prompt for segmentation
include_boxesbooleanoptionalAnyWhether to include bounding boxes for each mask (when available).
include_scoresbooleanoptionalAnyWhether to include mask confidence scores.
return_multiple_masksbooleanoptionalAnyIf True, upload and return multiple generated masks as defined by max_masks.
image_urlimagerequiredAnyURL of the image to be segmented
sync_modebooleanoptionalAnyIf True, the media will be returned as a data URI.
point_promptsjsonoptionalAnyList of point prompts
output_formatstringoptionaljpeg, png, webpThe format of the generated image.
max_masksintegeroptionalAnyMaximum number of masks to return when return_multiple_masks is enabled.
box_promptsjsonoptionalAnyBox 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.
apply_maskbooleanoptionalAnyApply the mask on the image.
text_promptstringoptionalAny[DEPRECATED] Use ‘prompt’ instead. Kept for backward compatibility.

​
Output schema

FieldTypeDescription
outputsjsonUnified output array - one entry per generated artifact with url/type/width/height/duration/etc.
model_datajsonModel-specific extra fields (prompt, description, actual_prompt, masks, etc.) keyed by field name.
nsfw_detectedjsontrue if the provider flagged output as NSFW, false if cleared, null if not checked.
seedjsonDeterministic seed used for generation, or null if the provider doesn’t return one.
timingjsonProvider timing info (inference_ms etc.), or null.

​
Callback payload

When you provide a callback_url, Runflow POSTs to it once the run reaches a terminal state.
FieldTypeDescription
eventstringEvent type: “run.completed”, “run.failed”, or “run.cancelled”.
run_idstringThe unique identifier of the run.
statusstringTerminal status: “succeeded”, “failed”, or “cancelled”.
outputobject | nullThe run output. Null if the run failed or was cancelled.
duration_msnumber | nullTotal run duration in milliseconds.
created_atstring | nullISO 8601 timestamp when the run was created.
completed_atstring | nullISO 8601 timestamp when the run reached terminal state.
metadataobject | nullThe metadata object passed at run creation, if any.
  • Retries: 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
  • Headers: Runflow-Request-Id is always sent. Runflow-Signature is sent if a signing secret is configured.

​
Additional Resources

Browse all models

Browse the catalog.

Run lifecycle

Callbacks, polling, statuses.

Callbacks

Handle async results.

Pricing

How requests bill out.