Serverless Cloud API

Run Workflows and Model Inference on GPU-accelerated auto-scaling infrastructure in the Roboflow cloud.

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, InferenceConfiguration

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
).configure(InferenceConfiguration(api_key_transport="header"))

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

The api_key_transport="header" setting sends the key only as an Authorization: Bearer header, keeping it out of URLs and logs: recommended for all new code. Servers older than Inference 1.5.0 do not read the header; use api_key_transport="both" while you still call one. See API key transport.

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.

In the cases that requests are too large, we recommend downsizing any attached images. This usually will not result in poor performance as images are downsized regardless after they've been received on our servers to the input size that the model architecture accepts. Some of our SDKs, like the Python SDK, automatically downsize images to the model architecture's input size before they are sent to the API.

---

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

Legacy Infer From Request

post

Legacy inference endpoint for object detection, instance segmentation, and classification.

Args: background_tasks: (BackgroundTasks) pool of fastapi background tasks dataset_id (str): ID of a Roboflow dataset corresponding to the model to use for inference OR workspace ID version_id (str): ID of a Roboflow dataset version corresponding to the model to use for inference OR model ID api_key (Optional[str], default None): Roboflow API Key passed to the model during initialization for artifact retrieval. # Other parameters described in the function signature...

Returns: Union[InstanceSegmentationInferenceResponse, KeypointsDetectionInferenceRequest, ObjectDetectionInferenceResponse, ClassificationInferenceResponse, MultiLabelClassificationInferenceResponse, SemanticSegmentationInferenceResponse, Any]: The response containing the inference results.

Path parameters

dataset_idstringRequired

ID of a Roboflow dataset corresponding to the model to use for inference OR workspace ID

version_idstringRequired

ID of a Roboflow dataset version corresponding to the model to use for inference OR model ID

Query parameters

api_keystring · nullableOptional

Roboflow API Key that will be passed to the model during initialization for artifact retrieval

confidenceany ofOptional

The confidence threshold used to filter out predictions. Pass a float in [0, 1], or "best" to use F1-optimal thresholds from model evaluation, or "default" to use the model's built-in default.

Default: 0.4

numberOptional

or

string · enumOptionalPossible values:

keypoint_confidencenumberOptional

The confidence threshold used to filter out keypoints that are not visible based on model confidence

Default: 0

formatstringOptional

One of 'json' or 'image'. If 'json' prediction data is return as a JSON string. If 'image' prediction data is visualized and overlayed on the original input image.

Default: json

imagestring · nullableOptional

The publically accessible URL of an image to use for inference.

image_typestring · nullableOptional

One of base64 or numpy. Note, numpy input is not supported for Roboflow Hosted Inference.

Default: base64

class_filterstring · nullableOptional

Action recognition only: comma separated classes. The subset of a fine-tuned model's classes to report. A zero-shot model answers in its own words and ignores it.

labelsboolean · nullableOptional

If true, labels will be include in any inference visualization.

Default: false

mask_decode_modestring · nullableOptional

One of 'accurate' or 'fast'. If 'accurate' the mask will be decoded using the original image size. If 'fast' the mask will be decoded using the original mask size. 'accurate' is slower but more accurate.

Default: accurate

tradeoff_factornumber · nullableOptional

The amount to tradeoff between 0='fast' and 1='accurate'

Default: 0

max_detectionsintegerOptional

The maximum number of detections to return. This is used to limit the number of predictions returned by the model. The model may return more predictions than this number, but only the top max_detections predictions will be returned.

Default: 300

overlapnumberOptional

The IoU threhsold that must be met for a box pair to be considered duplicate during NMS

Default: 0.3

strokeintegerOptional

The stroke width used when visualizing predictions

Default: 1

disable_preproc_auto_orientboolean · nullableOptional

If true, disables automatic image orientation

Default: false

disable_preproc_contrastboolean · nullableOptional

If true, disables automatic contrast adjustment

Default: false

disable_preproc_grayscaleboolean · nullableOptional

If true, disables automatic grayscale conversion

Default: false

disable_preproc_static_cropboolean · nullableOptional

If true, disables automatic static crop

Default: false

disable_active_learningboolean · nullableOptional

If true, the predictions will be prevented from registration by Active Learning (if the functionality is enabled)

Default: false

active_learning_target_datasetstring · nullableOptional

Parameter to be used when Active Learning data registration should happen against different dataset than the one pointed by model_id

sourcestring · nullableOptional

The source of the inference request

Default: external

source_infostring · nullableOptional

The detailed source information of the inference request

Default: external

response_mask_formatstring · enum · nullableOptional

The format of the prediction mask - polygon (default) or rle - applicable for instance segmentation models.

Default: polygonPossible values:

Responses

200

Successful Response

application/json

or

or

or

or

or

or

or

anyOptional

422

Validation Error

application/json

post/{dataset_id}/{version_id}

POST /{dataset_id}/{version_id} HTTP/1.1
Accept: */*

{
  "visualization": "text",
  "inference_id": "text",
  "frame_id": 1,
  "time": 1,
  "image": [
    {
      "width": 1,
      "height": 1
    }
  ],
  "predictions": [
    {
      "x": 1,
      "y": 1,
      "width": 1,
      "height": 1,
      "confidence": 1,
      "class": "text",
      "class_id": 1,
      "detection_id": "text",
      "parent_id": "text",
      "class_confidence": 1,
      "points": [
        {
          "x": 1,
          "y": 1
        }
      ],
      "mask_format": "polygon"
    }
  ]
}

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

Runtime	Use when	Reference
Serverless Cloud API (serverless.roboflow.com)	Default. Hosted, auto-scaling, supports models and Workflows.	Serverless Cloud API
Dedicated Deployments	You need predictable latency, high throughput, or pinned GPU type. Managed by Roboflow.	Dedicated Deployments and product overview
Roboflow Inference (self-hosted)	On-prem, edge devices, air-gapped environments, or workloads that can't leave your VPC. Open source.	Self-Hosted Deployment

Calling the Serverless Cloud API

Run a model:

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

Run a Workflow:

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

Sending the key as an ?api_key= query parameter or api_key body field is the legacy channel. It still works, but the Authorization: Bearer header keeps your key out of URLs and logs. See Authenticate with the REST API.

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:

from inference_sdk import InferenceHTTPClient, InferenceConfiguration

CLIENT = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="API_KEY"
).configure(InferenceConfiguration(api_key_transport="header"))

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

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.

An optimal confidence depends on the number of images the model has been trained on. Optimal confidence thresholds usually range from 0.85 to 0.99.

configuration = InferenceConfiguration(
    confidence_threshold=0.95,
    api_key_transport="header",
)
CLIENT.configure(configuration)

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

configure(...) replaces the whole configuration, so keep api_key_transport in any configuration you apply.

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

Flag	Description
-m, --model	Model ID in project/version format (required)
-c, --confidence	Confidence threshold, 0.0–1.0 (default: 0.5)
-o, --overlap	Overlap/NMS threshold, 0.0–1.0 (default: 0.5)
-t, --type	Model type (skip auto-detection): object-detection, classification, instance-segmentation, semantic-segmentation, keypoint-detection

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:

Tool	Description
models_infer	Run hosted inference on an image using a trained model.
workflows_run	Execute a saved Workflow on one or more images.
project_deployment_run	Run inference through the project's stable live endpoint.