Use a Model API Endpoint

Run a model on Roboflow's cloud GPUs in five minutes, with no hardware to set up.

The Serverless Hosted API runs models and Workflows on GPUs in Roboflow's cloud. You send an image and get results back. There is no hardware to set up and no server to keep running.

This guide takes you from zero to running a model in five minutes. You will find objects in an image just by naming them, detect everyday objects with a ready-made model, and run your own models, all against the same Serverless API endpoint.

Find objects by naming them

Give the model a few words like "taxi", "blue bus", or "bush" and it outlines every matching object in the image. There is nothing to set up or train first. This runs SAM3.

Get your API Key

Create a Roboflow account, find your key on the Roboflow API settings page and make it available to your shell:

export ROBOFLOW_API_KEY="your-key-here"

Install the dependencies

supervision brings in cv2 and numpy:

pip install supervision

Run the model

Send a POST request to /sam3/concept_segment to run the model. sv.Detections.from_sam3 turns those results into a form supervision can draw:

import os
import base64
import cv2
import requests
import supervision as sv
import numpy as np

content = requests.get("https://media.roboflow.com/quickstart/traffic.jpg").content
image = cv2.imdecode(np.frombuffer(content, np.uint8), cv2.IMREAD_COLOR)
image_b64 = base64.b64encode(content).decode("utf-8")
h, w = image.shape[:2]

response = requests.post(
    "https://serverless.roboflow.com/sam3/concept_segment",
    params={"api_key": os.environ["ROBOFLOW_API_KEY"]},
    json={
        "image": {"type": "base64", "value": image_b64},
        "prompts": [
            {"type": "text", "text": "taxi"},
            {"type": "text", "text": "blue bus"},
            {"type": "text", "text": "bush"},
        ],
    },
)

detections = sv.Detections.from_sam3(response.json(), (w, h))
annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
cv2.imwrite("sam3.jpg", annotated)

Get your API Key

Create a Roboflow account, find your key on the Roboflow API settings page and make it available to your shell:

export ROBOFLOW_API_KEY="your-key-here"

Install the dependencies

These two packages call the model and draw its results:

pip install inference-sdk supervision

Run the model

The Inference SDK sends your image to the cloud and returns the results. sv.Detections.from_sam3 turns those results into a form supervision can draw:

import os
import cv2
import numpy as np
import requests
import supervision as sv
from inference_sdk import InferenceHTTPClient

content = requests.get("https://media.roboflow.com/quickstart/traffic.jpg").content
image = cv2.imdecode(np.frombuffer(content, np.uint8), cv2.IMREAD_COLOR)
h, w = image.shape[:2]

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
)

data = client.sam3_concept_segment(
    image,
    prompts=[
        {"type": "text", "text": "taxi"},
        {"type": "text", "text": "blue bus"},
        {"type": "text", "text": "bush"},
    ],
)

detections = sv.Detections.from_sam3(data, (w, h))
annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
annotated = sv.BoxAnnotator().annotate(annotated, detections)
cv2.imwrite("sam3.jpg", annotated)

The response lists the outlines found for each prompt, with a confidence score for each one. sv.Detections.from_sam3 reads all of that for you.

Outlines around taxis, a blue bus, and bushes from text prompts

For the full SAM3 API, including visual prompts, exemplar boxes, and RLE output, see the SAM3 documentation.

Detect everyday objects with a ready-made model

To draw boxes around common objects instead of outlining named ones, call POST /{project}/{version} with a model ID instead of POST /sam3/concept_segment. This example uses a ready-made RF-DETR model, which can detect common objects like vehicles, people, and pets:

result = requests.post(
    "https://serverless.roboflow.com/coco/40",  # coco/40 is the rfdetr-medium alias
    params={"api_key": os.environ["ROBOFLOW_API_KEY"]},
    data=image_b64,  # raw base64 in the body, not JSON
    headers={"Content-Type": "application/x-www-form-urlencoded"},
).json()
detections = sv.Detections.from_inference(result)

print(f"Found {len(detections)} objects")

annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)
cv2.imwrite("rf-detr.jpg", annotated)

To draw boxes around common objects instead of outlining named ones, call client.infer() with a model ID instead of client.sam3_concept_segment(). This example uses a ready-made RF-DETR model, which can detect common objects like vehicles, people, and pets:

result = client.infer(image, model_id="rfdetr-medium")
detections = sv.Detections.from_inference(result)

print(f"Found {len(detections)} objects")

annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)
cv2.imwrite("rf-detr.jpg", annotated)

RF-DETR bounding boxes for cars, buses, people, and motorcycles

Run your own or another model

The same client.infer() or POST /{project}/{version} call runs any model by its model_id:

A model you trained in Roboflow. Copy its model ID (formatted as {project}/{version}) from your project in the Roboflow app
A public model from Roboflow Universe
A ready-made pretrained model by alias, such as rfdetr-nano, rfdetr-seg-medium, or yolo26l-640 (only for inference SDK)

Where to go next

You are running a model in the cloud. From here you can:

Run the same models on your own hardware. See Run a Model Locally
Get a private, single-tenant endpoint for large models and steady traffic with Dedicated Deployments
Chain models and logic into an application with Workflows
Understand what each request costs on the Serverless pricing page

PreviousRoboflow Documentation NextRun a Model Locally

Last updated 10 days ago

Was this helpful?