> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api.md).

# 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 for inference on images. Use this page for per-request image and Workflow inference over an internet connection. For managed live cameras, use [Cloud Streaming](/deployment/roboflow-cloud/cloud-streaming.md); for stored image and video jobs, use [Batch Processing](/deployment/roboflow-cloud/batch-processing.md).

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](/deployment/roboflow-cloud/dedicated-deployments.md) 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](/deployment/roboflow-cloud/serverless-api/use-in-a-workflow.md)
* [with the REST API](#http-api)
* with the [Inference Python SDK](#python-sdk)

### Inference server

The Serverless Cloud API uses the [Inference Server](/deployment/self-hosted/inference-server.md) request interface. For supported image-inference methods, switch the runtime by changing `api_url`, as shown below. This does not migrate a video integration to Cloud Streaming.

```python
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](https://docs.roboflow.com/reference/inference/inference-sdk/configuration#api-key-transport).

### Limits

Image inference is billed in credits per image, at a rate set by the model. See [Pricing](/deployment/roboflow-cloud/serverless-api/pricing.md) and [Model pricing](/deployment/roboflow-cloud/serverless-api/model-pricing.md).

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](https://discuss.roboflow.com).

{% hint style="info" %}
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.
{% endhint %}

***

See [Serverless Cloud API v1](/deployment/legacy/legacy-serverless.md) 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

{% openapi src="/files/MlDAyBpMk9MJoFuP6zXr" path="/{dataset\_id}/{version\_id}" method="post" %}
[serverless-api.json](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-6960e5f5b0f490b735257ca7203facdf44a31965%2Fserverless-api.json?alt=media)
{% endopenapi %}

{% openapi src="/files/MlDAyBpMk9MJoFuP6zXr" path="/{workspace\_name}/workflows/{workflow\_id}" method="post" %}
[serverless-api.json](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-6960e5f5b0f490b735257ca7203facdf44a31965%2Fserverless-api.json?alt=media)
{% endopenapi %}

### 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](/deployment/readme.md), 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](/deployment/roboflow-cloud/serverless-api.md)                                                                                              |
| **Dedicated Deployments**                            | You need predictable latency, high throughput, or pinned GPU type. Managed by Roboflow.              | [Dedicated Deployments](/deployment/roboflow-cloud/dedicated-deployments.md#http-api) and [product overview](/deployment/roboflow-cloud/dedicated-deployments.md) |
| **Roboflow Inference** (self-hosted)                 | On-prem, edge devices, air-gapped environments, or workloads that can't leave your VPC. Open source. | [Self-Hosted Deployment](/deployment/self-hosted/self-hosted.md)                                                                                                  |

{% hint style="info" %}
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](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api).
{% endhint %}

For managed live video, use [Cloud Streaming](/deployment/roboflow-cloud/cloud-streaming.md). For asynchronous processing of stored image and video sets, use [Batch Processing](/deployment/roboflow-cloud/batch-processing.md).

#### 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](https://docs.roboflow.com/reference/inference/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, InferenceConfiguration
</strong>
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)
</code></pre>

Above, specify your [model ID](https://docs.roboflow.com/reference/authentication/authentication/workspace-and-project-ids) and [API key](https://docs.roboflow.com/reference/authentication/authentication/find-your-roboflow-api-key). This code will run your model and return the results.

#### Roboflow Instant Model

Serverless Cloud API also supports running Roboflow [Instant Model](https://docs.roboflow.com/models/train/roboflow-instant). You can run Instant Model just like any other model, just note that the confidence threshold can be sensitive for Instant Models.

{% hint style="info" %}
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.
{% endhint %}

```python
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

{% hint style="info" %}
The following example uses the deprecated [Serverless Video Streaming API](/deployment/roboflow-cloud/serverless-api/serverless-video-streaming-api.md) and remains here for existing integrations. For new managed live-camera processing, use [Cloud Streaming](/deployment/roboflow-cloud/cloud-streaming.md). For finite stored-file jobs, use [Batch Processing](/deployment/roboflow-cloud/batch-processing.md).
{% endhint %}

This legacy WebRTC example runs an object detection model on a video and returns processed frames and predictions.

Install the SDK with its WebRTC dependencies and `supervision`:

```bash
pip install "inference-sdk[webrtc]" supervision
```

```python
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. See the [deprecated API reference and migration guide](/deployment/roboflow-cloud/serverless-api/serverless-video-streaming-api.md) for legacy configuration, or [self-hosted WebRTC](https://docs.roboflow.com/reference/inference/inference-sdk/webrtc) to run on your own server.

## CLI

You can use the Roboflow CLI to run a model trained on Roboflow, or with open source models available on [Roboflow Universe](https://universe.roboflow.com).

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

### Command

```bash
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](https://universe.roboflow.com/roboflow-100/poker-cards-cxcvz/model/1) dataset:

```bash
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:

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

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

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

### JSON Output

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

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

```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](https://docs.roboflow.com/agents/mcp-server) and it can run a model on an image with these tools:

<table data-search="false"><thead><tr><th width="290">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>models_infer</code></td><td>Run hosted inference on an image using a trained model.</td></tr><tr><td><code>workflows_run</code></td><td>Execute a saved Workflow on one or more images.</td></tr><tr><td><code>project_deployment_run</code></td><td>Run inference through the project's stable live endpoint.</td></tr></tbody></table>