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

# 서버리스 호스팅 API

## 소개

Roboflow에 배포된 모델에는 이미지에 대해 추론을 실행할 수 있는 REST API가 제공됩니다. 이 배포 방식은 배포 장치에 지속적인 인터넷 연결이 있는 환경에 이상적입니다.

Serverless Hosted API를 사용할 수 있습니다:

* [워크플로우에서](/deployment/ko/roboflow-cloud/serverless-api/use-in-a-workflow.md)
* [REST API와 함께](#http-api)
* 가 필요하며 [Inference Python SDK](#python-sdk)

### Inference 서버

당사의 Serverless Hosted API는 [Inference Server](https://docs.roboflow.com/reference/platform/rest-api/inference-server-openapi)에 의해 구동됩니다. 즉, 아래와 같이 Serverless Hosted API와 자체 호스팅 옵션을 손쉽게 오갈 수 있습니다:

```python
from inference_sdk import InferenceHTTPClient

CLIENT = InferenceHTTPClient(
    # api_url="http://localhost:9001" # 자체 호스팅 추론 서버
    api_url="https://serverless.roboflow.com", # 당사의 Serverless 호스팅 API
    api_key="API_KEY" # 비공개 모델과 데이터에 접근하기 위한 선택 사항
)

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

### 제한

당사의 Serverless Hosted API는 최대 20MB까지의 파일 업로드를 지원합니다. 고해상도 이미지에서는 제한에 걸릴 수 있습니다. 문제가 발생하면 엔터프라이즈 지원 담당자에게 문의하거나 [포럼](https://discuss.roboflow.com).

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

***

다음을 참조하세요 [Serverless Hosted API v1](/deployment/ko/legacy/legacy-serverless.md) 레거시 API 문서를 확인하세요.

## HTTP API

### REST API와 함께 사용

Serverless Hosted API에는 모든 모델과 워크플로우에 대한 단일 엔드포인트가 있습니다:

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

#### HTTP 엔드포인트

## Legacy Infer From Request

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

```json
{"openapi":"3.1.0","info":{"title":"Roboflow Inference Server","version":"1.3.8"},"paths":{"/{dataset_id}/{version_id}":{"post":{"summary":"Legacy Infer From Request","description":"Legacy inference endpoint for object detection, instance segmentation, and classification.\n\nArgs:\n    background_tasks: (BackgroundTasks) pool of fastapi background tasks\n    dataset_id (str): ID of a Roboflow dataset corresponding to the model to use for inference OR workspace ID\n    version_id (str): ID of a Roboflow dataset version corresponding to the model to use for inference OR model ID\n    api_key (Optional[str], default None): Roboflow API Key passed to the model during initialization for artifact retrieval.\n    # Other parameters described in the function signature...\n\nReturns:\n    Union[InstanceSegmentationInferenceResponse, KeypointsDetectionInferenceRequest, ObjectDetectionInferenceResponse, ClassificationInferenceResponse, MultiLabelClassificationInferenceResponse, SemanticSegmentationInferenceResponse, Any]: The response containing the inference results.","operationId":"legacy_infer_from_request__dataset_id___version_id__post","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","description":"ID of a Roboflow dataset corresponding to the model to use for inference OR workspace ID","title":"Dataset Id"},"description":"ID of a Roboflow dataset corresponding to the model to use for inference OR workspace ID"},{"name":"version_id","in":"path","required":true,"schema":{"type":"string","description":"ID of a Roboflow dataset version corresponding to the model to use for inference OR model ID","title":"Version Id"},"description":"ID of a Roboflow dataset version corresponding to the model to use for inference OR model ID"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Roboflow API Key that will be passed to the model during initialization for artifact retrieval","title":"Api Key"},"description":"Roboflow API Key that will be passed to the model during initialization for artifact retrieval"},{"name":"confidence","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"enum":["best","default"],"type":"string"}],"description":"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,"title":"Confidence"},"description":"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."},{"name":"keypoint_confidence","in":"query","required":false,"schema":{"type":"number","description":"The confidence threshold used to filter out keypoints that are not visible based on model confidence","default":0,"title":"Keypoint Confidence"},"description":"The confidence threshold used to filter out keypoints that are not visible based on model confidence"},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"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","title":"Format"},"description":"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."},{"name":"image","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The publically accessible URL of an image to use for inference.","title":"Image"},"description":"The publically accessible URL of an image to use for inference."},{"name":"image_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One of base64 or numpy. Note, numpy input is not supported for Roboflow Hosted Inference.","default":"base64","title":"Image Type"},"description":"One of base64 or numpy. Note, numpy input is not supported for Roboflow Hosted Inference."},{"name":"labels","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, labels will be include in any inference visualization.","default":false,"title":"Labels"},"description":"If true, labels will be include in any inference visualization."},{"name":"mask_decode_mode","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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","title":"Mask Decode Mode"},"description":"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."},{"name":"tradeoff_factor","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The amount to tradeoff between 0='fast' and 1='accurate'","default":0,"title":"Tradeoff Factor"},"description":"The amount to tradeoff between 0='fast' and 1='accurate'"},{"name":"max_detections","in":"query","required":false,"schema":{"type":"integer","description":"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,"title":"Max Detections"},"description":"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."},{"name":"overlap","in":"query","required":false,"schema":{"type":"number","description":"The IoU threhsold that must be met for a box pair to be considered duplicate during NMS","default":0.3,"title":"Overlap"},"description":"The IoU threhsold that must be met for a box pair to be considered duplicate during NMS"},{"name":"stroke","in":"query","required":false,"schema":{"type":"integer","description":"The stroke width used when visualizing predictions","default":1,"title":"Stroke"},"description":"The stroke width used when visualizing predictions"},{"name":"disable_preproc_auto_orient","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, disables automatic image orientation","default":false,"title":"Disable Preproc Auto Orient"},"description":"If true, disables automatic image orientation"},{"name":"disable_preproc_contrast","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, disables automatic contrast adjustment","default":false,"title":"Disable Preproc Contrast"},"description":"If true, disables automatic contrast adjustment"},{"name":"disable_preproc_grayscale","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, disables automatic grayscale conversion","default":false,"title":"Disable Preproc Grayscale"},"description":"If true, disables automatic grayscale conversion"},{"name":"disable_preproc_static_crop","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, disables automatic static crop","default":false,"title":"Disable Preproc Static Crop"},"description":"If true, disables automatic static crop"},{"name":"disable_active_learning","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"If true, the predictions will be prevented from registration by Active Learning (if the functionality is enabled)","default":false,"title":"Disable Active Learning"},"description":"If true, the predictions will be prevented from registration by Active Learning (if the functionality is enabled)"},{"name":"active_learning_target_dataset","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Parameter to be used when Active Learning data registration should happen against different dataset than the one pointed by model_id","title":"Active Learning Target Dataset"},"description":"Parameter to be used when Active Learning data registration should happen against different dataset than the one pointed by model_id"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The source of the inference request","default":"external","title":"Source"},"description":"The source of the inference request"},{"name":"source_info","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The detailed source information of the inference request","default":"external","title":"Source Info"},"description":"The detailed source information of the inference request"},{"name":"response_mask_format","in":"query","required":false,"schema":{"anyOf":[{"enum":["polygon","rle"],"type":"string"},{"type":"null"}],"description":"The format of the prediction mask - polygon (default) or rle - applicable for instance segmentation models.","default":"polygon","title":"Response Mask Format"},"description":"The format of the prediction mask - polygon (default) or rle - applicable for instance segmentation models."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InstanceSegmentationInferenceResponse"},{"$ref":"#/components/schemas/KeypointsDetectionInferenceResponse"},{"$ref":"#/components/schemas/ObjectDetectionInferenceResponse"},{"$ref":"#/components/schemas/ClassificationInferenceResponse"},{"$ref":"#/components/schemas/MultiLabelClassificationInferenceResponse"},{"$ref":"#/components/schemas/SemanticSegmentationInferenceResponse"},{"$ref":"#/components/schemas/StubResponse"},{}],"title":"Response Legacy Infer From Request  Dataset Id   Version Id  Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"InstanceSegmentationInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"items":{"anyOf":[{"$ref":"#/components/schemas/InstanceSegmentationPrediction"},{"$ref":"#/components/schemas/InstanceSegmentationRLEPrediction"}]},"type":"array","title":"Predictions"}},"type":"object","required":["image","predictions"],"title":"InstanceSegmentationInferenceResponse","description":"Instance Segmentation inference response.\n\nAttributes:\n    predictions (List[Union[\n        inference.core.entities.responses.inference.InstanceSegmentationPrediction,\n        inference.core.entities.responses.inference.InstanceSegmentationRLEPrediction\n    ]]): List of instance segmentation predictions."},"InferenceResponseImage":{"properties":{"width":{"type":"integer","title":"Width","description":"The original width of the image used in inference"},"height":{"type":"integer","title":"Height","description":"The original height of the image used in inference"}},"type":"object","required":["width","height"],"title":"InferenceResponseImage","description":"Inference response image information.\n\nAttributes:\n    width (int): The original width of the image used in inference.\n    height (int): The original height of the image used in inference."},"InstanceSegmentationPrediction":{"properties":{"x":{"type":"number","title":"X","description":"The center x-axis pixel coordinate of the prediction"},"y":{"type":"number","title":"Y","description":"The center y-axis pixel coordinate of the prediction"},"width":{"type":"number","title":"Width","description":"The width of the prediction bounding box in number of pixels"},"height":{"type":"number","title":"Height","description":"The height of the prediction bounding box in number of pixels"},"confidence":{"type":"number","title":"Confidence","description":"The detection confidence as a fraction between 0 and 1"},"class":{"type":"string","title":"Class","description":"The predicted class label"},"class_id":{"type":"integer","title":"Class Id","description":"The class id of the prediction"},"detection_id":{"type":"string","title":"Detection Id","description":"Unique identifier of detection"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region"},"class_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Class Confidence","description":"The class label confidence as a fraction between 0 and 1"},"points":{"items":{"$ref":"#/components/schemas/Point-Output"},"type":"array","title":"Points","description":"The list of points that make up the instance polygon"},"mask_format":{"type":"string","const":"polygon","title":"Mask Format","description":"Type of mask format","default":"polygon"}},"type":"object","required":["x","y","width","height","confidence","class","class_id","points"],"title":"InstanceSegmentationPrediction"},"Point-Output":{"properties":{"x":{"type":"number","title":"X","description":"The x-axis pixel coordinate of the point"},"y":{"type":"number","title":"Y","description":"The y-axis pixel coordinate of the point"}},"type":"object","required":["x","y"],"title":"Point","description":"Point coordinates.\n\nAttributes:\n    x (float): The x-axis pixel coordinate of the point.\n    y (float): The y-axis pixel coordinate of the point."},"InstanceSegmentationRLEPrediction":{"properties":{"x":{"type":"number","title":"X","description":"The center x-axis pixel coordinate of the prediction"},"y":{"type":"number","title":"Y","description":"The center y-axis pixel coordinate of the prediction"},"width":{"type":"number","title":"Width","description":"The width of the prediction bounding box in number of pixels"},"height":{"type":"number","title":"Height","description":"The height of the prediction bounding box in number of pixels"},"confidence":{"type":"number","title":"Confidence","description":"The detection confidence as a fraction between 0 and 1"},"class":{"type":"string","title":"Class","description":"The predicted class label"},"class_id":{"type":"integer","title":"Class Id","description":"The class id of the prediction"},"detection_id":{"type":"string","title":"Detection Id","description":"Unique identifier of detection"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region"},"rle":{"additionalProperties":true,"type":"object","title":"Rle","description":"RLE-encoded mask in COCO format: {'size': [H, W], 'counts': '...'}"},"mask_format":{"type":"string","const":"rle","title":"Mask Format","description":"Type of mask format","default":"rle"}},"type":"object","required":["x","y","width","height","confidence","class","class_id","rle"],"title":"InstanceSegmentationRLEPrediction"},"KeypointsDetectionInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"items":{"$ref":"#/components/schemas/KeypointsPrediction"},"type":"array","title":"Predictions"}},"type":"object","required":["image","predictions"],"title":"KeypointsDetectionInferenceResponse"},"KeypointsPrediction":{"properties":{"x":{"type":"number","title":"X","description":"The center x-axis pixel coordinate of the prediction"},"y":{"type":"number","title":"Y","description":"The center y-axis pixel coordinate of the prediction"},"width":{"type":"number","title":"Width","description":"The width of the prediction bounding box in number of pixels"},"height":{"type":"number","title":"Height","description":"The height of the prediction bounding box in number of pixels"},"confidence":{"type":"number","title":"Confidence","description":"The detection confidence as a fraction between 0 and 1"},"class":{"type":"string","title":"Class","description":"The predicted class label"},"class_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Class Confidence","description":"The class label confidence as a fraction between 0 and 1"},"class_id":{"type":"integer","title":"Class Id","description":"The class id of the prediction"},"tracker_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tracker Id","description":"The tracker id of the prediction if tracking is enabled"},"detection_id":{"type":"string","title":"Detection Id","description":"Unique identifier of detection"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region. Useful when stack of detection-models is in use to refer the RoI being the input to inference"},"keypoints":{"items":{"$ref":"#/components/schemas/Keypoint"},"type":"array","title":"Keypoints"}},"type":"object","required":["x","y","width","height","confidence","class","class_id","keypoints"],"title":"KeypointsPrediction"},"Keypoint":{"properties":{"x":{"type":"number","title":"X","description":"The x-axis pixel coordinate of the point"},"y":{"type":"number","title":"Y","description":"The y-axis pixel coordinate of the point"},"confidence":{"type":"number","title":"Confidence","description":"Model confidence regarding keypoint visibility."},"class_id":{"type":"integer","title":"Class Id","description":"Identifier of keypoint."},"class":{"type":"string","title":"Class","description":"Type of keypoint."}},"type":"object","required":["x","y","confidence","class_id","class"],"title":"Keypoint"},"ObjectDetectionInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"items":{"$ref":"#/components/schemas/ObjectDetectionPrediction"},"type":"array","title":"Predictions"}},"type":"object","required":["image","predictions"],"title":"ObjectDetectionInferenceResponse","description":"Object Detection inference response.\n\nAttributes:\n    predictions (List[inference.core.entities.responses.inference.ObjectDetectionPrediction]): List of object detection predictions."},"ObjectDetectionPrediction":{"properties":{"x":{"type":"number","title":"X","description":"The center x-axis pixel coordinate of the prediction"},"y":{"type":"number","title":"Y","description":"The center y-axis pixel coordinate of the prediction"},"width":{"type":"number","title":"Width","description":"The width of the prediction bounding box in number of pixels"},"height":{"type":"number","title":"Height","description":"The height of the prediction bounding box in number of pixels"},"confidence":{"type":"number","title":"Confidence","description":"The detection confidence as a fraction between 0 and 1"},"class":{"type":"string","title":"Class","description":"The predicted class label"},"class_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Class Confidence","description":"The class label confidence as a fraction between 0 and 1"},"class_id":{"type":"integer","title":"Class Id","description":"The class id of the prediction"},"tracker_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tracker Id","description":"The tracker id of the prediction if tracking is enabled"},"detection_id":{"type":"string","title":"Detection Id","description":"Unique identifier of detection"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region. Useful when stack of detection-models is in use to refer the RoI being the input to inference"}},"type":"object","required":["x","y","width","height","confidence","class","class_id"],"title":"ObjectDetectionPrediction","description":"Object Detection prediction.\n\nAttributes:\n    x (float): The center x-axis pixel coordinate of the prediction.\n    y (float): The center y-axis pixel coordinate of the prediction.\n    width (float): The width of the prediction bounding box in number of pixels.\n    height (float): The height of the prediction bounding box in number of pixels.\n    confidence (float): The detection confidence as a fraction between 0 and 1.\n    class_name (str): The predicted class label.\n    class_confidence (Union[float, None]): The class label confidence as a fraction between 0 and 1.\n    class_id (int): The class id of the prediction"},"ClassificationInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"items":{"$ref":"#/components/schemas/ClassificationPrediction"},"type":"array","title":"Predictions"},"top":{"type":"string","title":"Top","description":"The top predicted class label","default":""},"confidence":{"type":"number","title":"Confidence","description":"The confidence of the top predicted class label","default":0},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region. Useful when stack of detection-models is in use to refer the RoI being the input to inference"}},"type":"object","required":["image","predictions"],"title":"ClassificationInferenceResponse","description":"Classification inference response.\n\nAttributes:\n    predictions (List[inference.core.entities.responses.inference.ClassificationPrediction]): List of classification predictions.\n    top (str): The top predicted class label.\n    confidence (float): The confidence of the top predicted class label."},"ClassificationPrediction":{"properties":{"class":{"type":"string","title":"Class","description":"The predicted class label"},"class_id":{"type":"integer","title":"Class Id","description":"Numeric ID associated with the class label"},"confidence":{"type":"number","title":"Confidence","description":"The class label confidence as a fraction between 0 and 1"}},"type":"object","required":["class","class_id","confidence"],"title":"ClassificationPrediction","description":"Classification prediction.\n\nAttributes:\n    class_name (str): The predicted class label.\n    class_id (int): Numeric ID associated with the class label.\n    confidence (float): The class label confidence as a fraction between 0 and 1."},"MultiLabelClassificationInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"additionalProperties":{"$ref":"#/components/schemas/MultiLabelClassificationPrediction"},"type":"object","title":"Predictions"},"predicted_classes":{"items":{"type":"string"},"type":"array","title":"Predicted Classes","description":"The list of predicted classes"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id","description":"Identifier of parent image region. Useful when stack of detection-models is in use to refer the RoI being the input to inference"}},"type":"object","required":["image","predictions","predicted_classes"],"title":"MultiLabelClassificationInferenceResponse","description":"Multi-label Classification inference response.\n\nAttributes:\n    predictions (Dict[str, inference.core.entities.responses.inference.MultiLabelClassificationPrediction]): Dictionary of multi-label classification predictions.\n    predicted_classes (List[str]): The list of predicted classes."},"MultiLabelClassificationPrediction":{"properties":{"confidence":{"type":"number","title":"Confidence","description":"The class label confidence as a fraction between 0 and 1"},"class_id":{"type":"integer","title":"Class Id","description":"Numeric ID associated with the class label"}},"type":"object","required":["confidence","class_id"],"title":"MultiLabelClassificationPrediction","description":"Multi-label Classification prediction.\n\nAttributes:\n    confidence (float): The class label confidence as a fraction between 0 and 1."},"SemanticSegmentationInferenceResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"image":{"anyOf":[{"items":{"$ref":"#/components/schemas/InferenceResponseImage"},"type":"array"},{"$ref":"#/components/schemas/InferenceResponseImage"}],"title":"Image"},"predictions":{"$ref":"#/components/schemas/SemanticSegmentationPrediction"}},"type":"object","required":["image","predictions"],"title":"SemanticSegmentationInferenceResponse","description":"Semantic Segmentation inference response.\n\nAttributes:\n    predictions (inference.core.entities.responses.inference.SemanticSegmentationPrediction): Semantic segmentation predictions."},"SemanticSegmentationPrediction":{"properties":{"segmentation_mask":{"type":"string","title":"Segmentation Mask","description":"base64-encoded PNG of predicted class label at each pixel"},"class_map":{"additionalProperties":{"type":"string"},"type":"object","title":"Class Map","description":"Map of pixel intensity value to class label"},"confidence_mask":{"type":"string","title":"Confidence Mask","description":"base64-encoded PNG of predicted class confidence at each pixel"}},"type":"object","required":["segmentation_mask","class_map","confidence_mask"],"title":"SemanticSegmentationPrediction"},"StubResponse":{"properties":{"visualization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visualization","description":"Base64 encoded string containing prediction visualization image data"},"inference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inference Id","description":"Unique identifier of inference"},"frame_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Frame Id","description":"The frame id of the image used in inference if the input was a video"},"time":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Time","description":"The time in seconds it took to produce the predictions including image preprocessing"},"is_stub":{"type":"boolean","title":"Is Stub","description":"Field to mark prediction type as stub"},"model_id":{"type":"string","title":"Model Id","description":"Identifier of a model stub that was called"},"task_type":{"type":"string","title":"Task Type","description":"Task type of the project"}},"type":"object","required":["is_stub","model_id","task_type"],"title":"StubResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

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

Roboflow는 여러 런타임을 통해 추론을 제공합니다. 올바른 선택은 단일 모델을 호출하는지 워크플로우를 호출하는지, 필요한 처리량이 어느 정도인지, 그리고 작업 부하가 어디에서 실행되는지에 따라 달라집니다.

이 페이지는 간단한 개요입니다. 자세한 추론 참조는 [제품 문서](/deployment/ko/readme.md)에 있으며, 이는 같은 문서 사이트의 일부입니다. 더 깊은 내용이 있는 곳에는 상호 링크가 제공됩니다.

#### 추론 런타임

| 런타임                                          | 다음 경우 사용                                                      | 참조                                                                                                                                         |
| -------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **서버리스 호스팅 API** (`serverless.roboflow.com`) | 기본값. 호스팅됨, 자동 확장, 모델 및 워크플로우 지원.                              | [서버리스 호스팅 API](/deployment/ko/roboflow-cloud/serverless-api.md)                                                                            |
| **전용 배포**                                    | 예측 가능한 지연 시간, 높은 처리량, 또는 고정된 GPU 유형이 필요합니다. Roboflow에서 관리합니다. | [전용 배포](/deployment/ko/roboflow-cloud/dedicated-deployments.md#http-api) 및 [제품 개요](/deployment/ko/roboflow-cloud/dedicated-deployments.md) |
| **Roboflow Inference** (자체 호스팅)              | 온프레미스, 엣지 장치, 에어갭 환경, 또는 VPC 밖으로 나갈 수 없는 작업 부하. 오픈 소스.        | [자체 호스팅 배포](/deployment/ko/self-hosted/self-hosted.md)                                                                                     |

#### Serverless Hosted API 호출하기

모델 실행:

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

워크플로우 실행:

```bash
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" } }
  }'
```

라이브 비디오는 [서버리스 비디오 스트리밍 API](/deployment/ko/roboflow-cloud/serverless-api/serverless-video-streaming-api.md)를 참조하세요. 대용량 이미지 및 비디오 세트의 비동기 처리는 [배치 처리](/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 Hosted API 형식으로 변환하세요.

## Python SDK

### Python SDK와 함께 사용

Python에서 작업 중이라면 Serverless API와 상호작용하는 가장 편리한 방법은 Inference Python SDK를 사용하는 것입니다.

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

```
pip install inference-sdk
```

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

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

위에서, 여러분의 [모델 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 API는 Roboflow [Instant Model](https://docs.roboflow.com/models/train/roboflow-instant)도 실행을 지원합니다. Instant Model은 다른 모델과 마찬가지로 실행할 수 있지만, 신뢰도 임계값은 Instant Model에서 민감할 수 있다는 점을 유의하세요.

{% hint style="info" %}
최적의 신뢰도는 모델이 학습된 이미지 수에 따라 달라집니다. 최적의 신뢰도 임계값은 일반적으로 0.85에서 0.99 사이입니다.
{% endhint %}

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

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

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

Inference SDK WebRTC 클라이언트를 사용해 비디오에서 객체 탐지 모델을 실행하세요. Serverless Video Streaming API는 Roboflow Cloud에서 비디오를 처리하고 각 프레임에 대한 예측을 반환합니다.

SDK를 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("예측", annotated)

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

session.run()
cv2.destroyAllWindows()
```

다음으로 바꾸세요 `API_KEY` 및 `model-id/1` 을 API 키와 모델 ID와 함께 사용하세요. 웹캠 및 RTSP 카메라에서 스트리밍하는 방법, 모든 프레임을 처리하는 방법, 또는 다음에서 워크플로우를 실행하는 방법을 알아보세요 [Serverless Video Streaming API 가이드](/deployment/ko/roboflow-cloud/serverless-api/serverless-video-streaming-api.md).

## CLI

Roboflow에서 학습한 모델이나, 다음에서 제공되는 오픈 소스 모델을 실행하려면 Roboflow CLI를 사용할 수 있습니다 [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`       | 모델 유형(자동 감지 건너뛰기): `객체 탐지`, `분류`, `인스턴스 분할`, `semantic-segmentation`, `keypoint-detection` |

### 예시

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

```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": "가위",
      "class_id": 2
    }
  ]
}
```

다음에서 지원되는 모든 매개변수를 확인하세요 `roboflow infer --help`.