Serverless Cloud API

About

Models deployed to Roboflow have a REST API available through which you can run inference on images. This deployment method is ideal for environments where you have a persistent internet connection on your deployment device.

In the app, this endpoint is labeled "Serverless Cloud API", or "Cloud API" where space is tight (ex: the Workflow editor runtime picker). A Dedicated Deployment endpoint (*.roboflow.cloud) is labeled "Dedicated Cloud API", and the older v1 endpoint is labeled "Hosted API (Legacy)". These labels replace the earlier "Serverless Hosted API" and "Serverless API V2" names.

You can use Serverless Cloud API:

• in Workflows
• with the REST API
• with the Inference Python SDK

Inference server

Our Serverless Cloud API is powered by the Inference Server. This means you can easily switch between our Serverless Cloud API and self-hosting option and vice versa, as shown below:

from inference_sdk import InferenceHTTPClient

CLIENT = InferenceHTTPClient(
    # api_url="http://localhost:9001" # Self-hosted Inference server
    api_url="https://serverless.roboflow.com", # Our Serverless Cloud API
    api_key="API_KEY" # optional to access your private models and data
)

result = CLIENT.infer("image.jpg", model_id="model-id/1")
print(result)

Limits

Our Serverless Cloud API supports file uploads up to 20MB. You may run into limitations with higher resolution images. Should you run into an issue, please reach out to your enterprise support contact or post a message to the forum.

See Serverless Cloud API v1 for the legacy API documentation.

HTTP API

Use with the REST API

The Serverless Cloud API has one endpoint for all models and Workflows:

https://serverless.roboflow.com

HTTP endpoints

POST /{dataset_id}/{version_id} HTTP/1.1
Host: api.example.com
Accept: application/json

curl -L \
  --request POST \
  --url '/{dataset_id}/{version_id}' \
  --header 'Accept: application/json'

const response = await fetch("/{dataset_id}/{version_id}", {
  method: "POST",
  headers: {
    "Accept": "application/json"
  }
});

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

import requests

url = "/{dataset_id}/{version_id}"
headers = {
    "Accept": "application/json"
}

response = requests.post(url, headers=headers)
print(response.json())

{
  "visualization": "text",
  "inference_id": "text",
  "frame_id": 1,
  "time": 1,
  "image": [
    {
      "width": 1,
      "height": 1
    }
  ],
  "predictions": [
    "anything"
  ]
}

{
  "detail": [
    {
      "loc": [
        "anything"
      ],
      "msg": "text",
      "type": "text",
      "input": "anything",
      "ctx": {}
    }
  ]
}

Run a Model on an Image

Roboflow exposes inference through several runtimes - the right choice depends on whether you're calling a single model or a Workflow, how much throughput you need, and where the workload runs.

This page is a brief overview. The detailed inference reference lives in the product documentation, which is part of the same docs site. Cross-links are provided where the deeper material lives.

Inference runtimes

Calling the Serverless Cloud API

Run a model:

curl -F "file=@photo.jpg" \
  "https://serverless.roboflow.com/<project>/<version>?api_key=$ROBOFLOW_API_KEY&confidence=0.5"

Run a Workflow:

curl -X POST "https://serverless.roboflow.com/infer/workflows/<workspace>/<workflow>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'$ROBOFLOW_API_KEY'",
    "inputs": { "image": { "type": "url", "value": "https://example.com/photo.jpg" } }
  }'

For live video, see the Serverless Video Streaming API. For asynchronous processing of large image and video sets, see Batch Processing.

Deprecated: Serverless v1

The legacy task-specific endpoints - detect.roboflow.com, classify.roboflow.com, outline.roboflow.com, segment.roboflow.com - are deprecated. They still respond for backwards compatibility but new code should use serverless.roboflow.com instead.

If you find a snippet pointing to a *.roboflow.com task host, treat it as legacy and translate it to the Serverless Cloud API form above.

Python SDK

Use with Python SDK

If you are working in Python, the most convenient way to interact with the Serverless Cloud API is to use the Inference Python SDK.

To use the Inference SDK, first install it:

pip install inference-sdk

To make a request to the Serverless Cloud API, use the following code:

<pre class="language-python"><code class="lang-python"><strong>from inference_sdk import InferenceHTTPClient </strong> CLIENT = InferenceHTTPClient( api_url="https://serverless.roboflow.com", api_key="API_KEY" )

result = CLIENT.infer("image.jpg", model_id="model-id/1") print(result) </code></pre>

Above, specify your model ID and API key. This code will run your model and return the results.

Roboflow Instant Model

Serverless Cloud API also supports running Roboflow Instant Model. You can run Instant Model just like any other model, just note that the confidence threshold can be sensitive for Instant Models.

configuration = InferenceConfiguration(
    confidence_threshold=0.95
)
CLIENT.configure(configuration)

result = CLIENT.infer("image.jpg", model_id="roboflow-instant-model-id/1")

Stream video with Python SDK

Use the Inference SDK WebRTC client to run an object detection model on a video. The Serverless Video Streaming API processes the video in the Roboflow Cloud and returns predictions for each frame.

Install the SDK with its WebRTC dependencies and supervision:

pip install "inference-sdk[webrtc]" supervision

import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient
from inference_sdk.webrtc import VideoFileSource

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="API_KEY",
)

session = client.webrtc.stream(
    source=VideoFileSource("video.mp4"),
    model_id="model-id/1",
)

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

@session.on_frame
def show(frame, data):
    if data is None:
        return

    detections = sv.Detections.from_inference(data)
    annotated = box_annotator.annotate(frame.copy(), detections)
    annotated = label_annotator.annotate(annotated, detections)
    cv2.imshow("Predictions", annotated)

    if cv2.waitKey(1) & 0xFF == ord("q"):
        session.close()

session.run()
cv2.destroyAllWindows()

Replace API_KEY and model-id/1 with your API key and model ID. Learn how to stream from webcams and RTSP cameras, process every frame, or run a Workflow in the Serverless Video Streaming API guide.

CLI

You can use the Roboflow CLI to run a model trained on Roboflow, or with open source models available on Roboflow Universe.

By running roboflow infer in the command line, the CLI sends the image to the Roboflow API and prints the predictions.

Command

roboflow infer <image-path> -m <project/version>

Options

Examples

Run inference using an open source model from Roboflow Universe - for example, the poker-cards dataset:

roboflow infer ~/Downloads/ace.jpg -m poker-cards-cxcvz/1 -c 0.7

The workspace defaults to your configured workspace. To use a model from a different workspace:

roboflow infer photo.jpg -m poker-cards-cxcvz/1 -w roboflow-100

Specify the model type to skip the auto-detection API call:

roboflow infer photo.jpg -m my-project/3 -t object-detection

JSON Output

Use --json to get structured prediction data for scripting and automation:

roboflow infer photo.jpg -m my-project/3 --json

{
  "predictions": [
    {
      "x": 1230.0,
      "y": 814.5,
      "width": 840.0,
      "height": 1273.0,
      "confidence": 0.882,
      "class": "Scissors",
      "class_id": 2
    }
  ]
}

See all supported parameters with roboflow infer --help.

MCP Server

Connect your AI agent to the MCP Server and it can run a model on an image with these tools: