> 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/ko/roboflow-cloud/serverless-api.md).

# Serverless Cloud API

Roboflow 클라우드의 GPU 가속 자동 확장 인프라에서 워크플로와 모델 추론을 실행합니다.

## 개요

Roboflow에 배포된 모델은 이미지 추론을 위한 REST API를 제공합니다. 인터넷 연결을 통해 요청별 이미지 및 Workflow 추론을 수행하려면 이 페이지를 사용하세요. 관리형 라이브 카메라에는 [Cloud Streaming](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming.md)을, 저장된 이미지 및 비디오 작업에는 [Batch Processing](https://docs.roboflow.com/deployment/ko/roboflow-cloud/batch-processing.md).

을 사용하세요. 앱에서 이 엔드포인트는 "서버리스 클라우드 API"로 표시되며, 공간이 부족한 경우(예: Workflow 편집기의 런타임 선택기)에는 "클라우드 API"로 표시됩니다.  [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md)  엔드포인트(`*.roboflow.cloud`)는 "전용 클라우드 API"로 표시되고, 이전 v1 엔드포인트는 "호스팅 API(레거시)"로 표시됩니다. 이러한 이름은 이전에 사용된 "서버리스 호스팅 API" 및 "서버리스 API V2"를 대체합니다.

다음에서 서버리스 클라우드 API를 사용할 수 있습니다.

* [Workflows에서](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api/use-in-a-workflow.md)
* [REST API로](#http-api)
* 다음과 함께 [Inference Python SDK](#python-sdk)

### Inference 서버

서버리스 클라우드 API는 [Inference Server](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server.md) 요청 인터페이스를 사용합니다. 지원되는 이미지 추론 메서드의 런타임을 전환하려면 아래 예시처럼 `api_url`을 변경하세요. 이렇게 해도 비디오 통합이 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)
```

api\_key\_transport="header" `설정을 사용하면 키가` Authorization: Bearer `헤더로만 전송되어 URL과 로그에 노출되지 않습니다. 새 코드에서는 이 방식을 권장합니다. Inference 1.5.0보다 이전 버전의 서버는 이 헤더를 읽지 않습니다. 해당 서버를 계속 호출해야 한다면` api\_key\_transport="both" `를 사용하세요. 자세한 내용은` API 키 전송 방식 [을 참조하세요.](https://docs.roboflow.com/reference/inference/inference-sdk/configuration#api-key-transport).

### 제한 사항

이미지 추론은 모델별로 정해진 요율에 따라 이미지당 크레딧으로 청구됩니다. 자세한 내용은 [서버리스 요금](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api/model-pricing.md).

을 참조하세요. 서버리스 클라우드 API는 최대 20MB까지 파일 업로드를 지원합니다. 해상도가 더 높은 이미지는 제한에 걸릴 수 있습니다. 문제가 발생하면 기업 고객 지원 담당자에게 문의하거나 [포럼](https://discuss.roboflow.com).

{% hint style="info" %}
요청 크기가 너무 큰 경우 첨부 이미지를 축소하는 것이 좋습니다. 이미지가 서버에 도착한 후 모델 아키텍처가 허용하는 입력 크기로 어차피 축소되므로, 보통 이미지 축소로 인해 성능이 저하되지는 않습니다.\
\
Python SDK와 같은 일부 SDK는 이미지를 API로 전송하기 전에 모델 아키텍처의 입력 크기에 맞게 자동으로 축소합니다.
{% endhint %}

***

에 글을 남겨 주세요. 레거시 API 문서는 [서버리스 클라우드 API v1](https://docs.roboflow.com/deployment/ko/legacy/legacy-serverless.md) 을 참조하세요.

## HTTP API

### REST API와 함께 사용

서버리스 클라우드 API에는 모든 모델과 Workflow에 사용할 수 있는 단일 엔드포인트가 있습니다.

```
https://serverless.roboflow.com
```

#### HTTP 엔드포인트

{% openapi src="/files/43170b71137bf2ef841f870f1ed7f60e9f0d669c" path="/{dataset\_id}/{version\_id}" method="post" %}
[serverless-api.json](https://1826078061-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/43170b71137bf2ef841f870f1ed7f60e9f0d669c" path="/{workspace\_name}/workflows/{workflow\_id}" method="post" %}
[serverless-api.json](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-6960e5f5b0f490b735257ca7203facdf44a31965%2Fserverless-api.json?alt=media)
{% endopenapi %}

### 이미지에서 모델 실행

Roboflow는 여러 런타임을 통해 추론을 제공합니다. 적절한 런타임은 단일 모델과 Workflow 중 무엇을 호출하는지, 필요한 처리량이 어느 정도인지, 작업이 어디서 실행되는지에 따라 달라집니다.

이 페이지는 간략한 개요입니다. 자세한 추론 참고 자료는 같은 문서 사이트의 [제품 문서](https://docs.roboflow.com/deployment/ko/readme.md)에서 확인할 수 있습니다. 더 상세한 내용이 있는 곳에는 상호 링크가 제공됩니다.

#### 추론 런타임

| 런타임                                                  | 사용 시점                                                                | 참고 자료                                                                                                                                                                                        |
| ---------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Serverless Cloud API** (`serverless.roboflow.com`) | 기본 옵션입니다. 호스팅되며 자동으로 확장되고, 모델과 Workflow를 지원합니다.                      | [서버리스 클라우드 API](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api.md)                                                                                                    |
| **Dedicated Deployments**                            | 예측 가능한 지연 시간, 높은 처리량 또는 고정된 GPU 유형이 필요한 경우에 사용합니다. Roboflow에서 관리합니다. | [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md#http-api) 및 [제품 개요](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md) |
| **Roboflow Inference** (자체 호스팅)                      | 온프레미스, 엣지 디바이스, 망 분리 환경 또는 VPC 외부로 전송할 수 없는 워크로드에 사용합니다. 오픈 소스입니다.   | [자체 호스팅 배포](https://docs.roboflow.com/deployment/ko/self-hosted/self-hosted.md)                                                                                                              |

{% hint style="info" %}
키를 다음과 같이 전달하는 방식은 `?api_key=` 쿼리 매개변수나 `api_key` 본문 필드로 전달하는 레거시 방식입니다. 여전히 작동하지만, `Authorization: Bearer` 헤더를 사용하면 URL과 로그에 키가 노출되지 않습니다. 자세한 내용은 [REST API 인증](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api).
{% endhint %}

관리형 실시간 동영상에는  [Cloud Streaming](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming.md)을 사용하고, 저장된 이미지 및 동영상 세트의 비동기 처리에는 다음을 사용하세요:  [Batch Processing](https://docs.roboflow.com/deployment/ko/roboflow-cloud/batch-processing.md).

#### 지원 중단 예정: Serverless v1

기존 작업별 엔드포인트인  `detect.roboflow.com`, `classify.roboflow.com`, `outline.roboflow.com`, `segment.roboflow.com` 은  **지원 중단 예정입니다**. 이전 버전과의 호환성을 위해 여전히 응답하지만, 새 코드에서는  `serverless.roboflow.com` 를 사용해야 합니다.

코드 스니펫이  `*.roboflow.com`  작업 호스트를 가리킨다면, 이를 기존 코드로 간주하고 위의 Serverless Cloud API 형식으로 변환하세요.

## Python SDK

### Python SDK와 함께 사용하기

Python을 사용하는 경우 Serverless Cloud API와 상호작용하는 가장 편리한 방법은 Inference Python SDK를 사용하는 것입니다.

먼저  [Inference SDK](https://docs.roboflow.com/reference/inference/inference-sdk)를 설치하세요:

```
pip install inference-sdk
```

Serverless Cloud API에 요청을 보내려면 다음 코드를 사용하세요:

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

위 코드에  [모델 ID](https://docs.roboflow.com/reference/authentication/authentication/workspace-and-project-ids) 와  [API 키](https://docs.roboflow.com/reference/authentication/authentication/find-your-roboflow-api-key)를 지정하세요. 이 코드는 모델을 실행하고 결과를 반환합니다.

#### Roboflow Instant Model

Serverless Cloud API는 Roboflow의  [Instant Model](https://docs.roboflow.com/models/train/roboflow-instant) 실행도 지원합니다. Instant Model은 다른 모델과 동일하게 실행할 수 있지만, 신뢰도 임곗값에 민감할 수 있다는 점에 유의하세요.

{% hint style="info" %}
최적의 신뢰도는 모델을 학습하는 데 사용한 이미지 수에 따라 달라집니다. 최적의 신뢰도 임곗값은 일반적으로 0.85에서 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(...)` 전체 구성을 대체하므로 `api_key_transport` 를 적용하는 모든 구성에 포함하세요.

### Python SDK로 비디오 스트리밍하기

{% hint style="info" %}
다음 예제는 더 이상 사용되지 않는 [Serverless Video Streaming API](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api/serverless-video-streaming-api.md) 를 사용하며, 기존 통합을 위해 이곳에 남겨 두었습니다. 새로운 관리형 실시간 카메라 처리를 위해서는 [Cloud Streaming](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming.md)을 사용하세요. 저장된 파일을 대상으로 하는 개별 작업에는 [Batch Processing](https://docs.roboflow.com/deployment/ko/roboflow-cloud/batch-processing.md).
{% endhint %}

이 레거시 WebRTC 예제는 비디오에서 객체 감지 모델을 실행하고 처리된 프레임과 예측 결과를 반환합니다.

WebRTC 종속성과 `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()
```

다음으로 바꾸세요: `API_KEY` 및 `model-id/1` 를 본인의 API 키와 모델 ID로 바꾸세요. 레거시 구성은 [사용 중단된 API 참조 및 마이그레이션 가이드](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api/serverless-video-streaming-api.md) 를 참고하고, 자체 서버에서 실행하려면 [자체 호스팅 WebRTC](https://docs.roboflow.com/reference/inference/inference-sdk/webrtc) 를 참고하세요.

## CLI

Roboflow CLI를 사용하면 Roboflow에서 학습한 모델이나 다음에서 제공하는 오픈 소스 모델을 실행할 수 있습니다: [Roboflow Universe](https://universe.roboflow.com).

명령줄에서 `roboflow infer` 를 실행하면 CLI가 이미지를 Roboflow API로 전송하고 예측 결과를 출력합니다.

### 명령

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

#### 옵션

| 플래그                  | 설명                                                                                                                               |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `-m`, `--model`      | 모델 ID 형식: `project/version` (필수)                                                                                                 |
| `-c`, `--confidence` | 신뢰도 임계값, 0.0–1.0 (기본값: 0.5)                                                                                                      |
| `-o`, `--overlap`    | 중복/NMS 임계값, 0.0–1.0 (기본값: 0.5)                                                                                                   |
| `-t`, `--type`       | 모델 유형 (자동 감지 건너뛰기): `object-detection`, `classification`, `instance-segmentation`, `semantic-segmentation`, `keypoint-detection` |

### 예시

예를 들어 [poker-cards](https://universe.roboflow.com/roboflow-100/poker-cards-cxcvz/model/1) 데이터 세트와 같은 Roboflow Universe의 오픈 소스 모델을 사용해 추론을 실행합니다:

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

기본적으로 구성된 워크스페이스가 사용됩니다. 다른 워크스페이스의 모델을 사용하려면 다음과 같이 실행하세요:

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

자동 감지 API 호출을 건너뛰려면 모델 유형을 지정하세요:

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

### JSON 출력

스크립팅 및 자동화에 사용할 구조화된 예측 데이터를 가져오려면 `--json` 을 사용하세요:

```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
    }
  ]
}
```

지원되는 모든 매개변수를 확인하려면 다음을 실행하세요: `roboflow infer --help`.

## MCP 서버

AI 에이전트를 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 에 연결하면 다음 도구를 사용해 이미지에서 모델을 실행할 수 있습니다:

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>models_infer</code></td><td>학습된 모델을 사용해 이미지에 호스팅 추론을 실행합니다.</td></tr><tr><td><code>workflows_run</code></td><td>하나 이상의 이미지에 저장된 Workflow를 실행합니다.</td></tr><tr><td><code>project_deployment_run</code></td><td>프로젝트의 안정적인 라이브 엔드포인트를 통해 추론을 실행합니다.</td></tr></tbody></table>
