> 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 Hosted 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. You can use Serverless Hosted 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 Our Serverless Hosted API is powered by the [Inference Server](https://inference.roboflow.com/api/). This means you can easily switch between our Serverless Hosted API and self-hosting option and vice versa, as shown below: ```python from inference_sdk import InferenceHTTPClient CLIENT = InferenceHTTPClient( # api_url="http://localhost:9001" # Self-hosted Inference server api_url="https://serverless.roboflow.com", # Our Serverless hosted 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 Hosted 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 Hosted API v1](/deployment/legacy/legacy-serverless.md) for the legacy API documentation. ## HTTP API ### Use with the REST API The Serverless Hosted API has one endpoint for all models and Workflows: ``` https://serverless.roboflow.com ``` #### HTTP endpoints ## 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.6"},"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"}}}} ``` ### 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](https://docs.roboflow.com/deployment), which is part of the same docs site. Cross-links are provided where the deeper material lives. #### Inference runtimes | Runtime | Use when | Reference | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Serverless Hosted API** (`serverless.roboflow.com`) | Default. Hosted, auto-scaling, supports models and Workflows. | [Serverless Hosted API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api) | | **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](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) | | **Roboflow Inference** (self-hosted) | On-prem, edge devices, air-gapped environments, or workloads that can't leave your VPC. Open source. | [inference.roboflow.com](https://inference.roboflow.com) | #### Calling the Serverless Hosted API Run a model: ```bash curl -F "file=@photo.jpg" \ "https://serverless.roboflow.com//?api_key=$ROBOFLOW_API_KEY&confidence=0.5" ``` Run a Workflow: ```bash curl -X POST "https://serverless.roboflow.com/infer/workflows//" \ -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](/deployment/roboflow-cloud/serverless-api/serverless-video-streaming-api.md). For asynchronous processing of large image and video sets, see [Batch Processing](/deployment/roboflow-cloud/batch-processing.md). Per-task response shapes are documented alongside the [Python SDK](#python-sdk) examples below. #### 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 Hosted API form above. #### SDK and CLI shortcuts If you're not building a non-Python integration, the SDK and CLI wrap these calls with proper authentication and JSON parsing: * SDK - see [Run a Model on an Image (SDK)](#python-sdk). * CLI - see [Run a Model on an Image (CLI)](#cli). Both ultimately hit the same Serverless Hosted API endpoint described above. ## Python SDK ### Use with Python SDK If you are working in Python, the most convenient way to interact with the Serverless API is to use the Inference Python SDK. To use the [Inference SDK](https://inference.roboflow.com/inference_helpers/inference_sdk/), first install it: ``` pip install inference-sdk ``` To make a request to the Serverless Hosted API, use the following code: 
from inference_sdk import InferenceHTTPClient

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

result = CLIENT.infer("image.jpg", model_id="model-id/1")
print(result)
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 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 ) CLIENT.configure(configuration) result = CLIENT.infer("image.jpg", model_id="roboflow-instant-model-id/1") ``` ### Run a Model on an Image Once a `Version` is trained, its `.model` property returns a task-specific model object you can call `.predict()` on. The SDK handles authentication, image preprocessing, and JSON response parsing. The model class returned depends on the project type - object detection, classification, segmentation, keypoint detection, or VLM. The `.predict()` signature is similar across all of them; differences are noted below. #### Object detection ```python import roboflow rf = roboflow.Roboflow(api_key="YOUR_API_KEY") project = rf.workspace().project("my-detector") version = project.version(3) model = version.model predictions = model.predict( "photo.jpg", confidence=40, # 0–100 overlap=30, # 0–100, NMS IoU threshold ).json() for p in predictions["predictions"]: print(p["class"], p["confidence"], p["x"], p["y"], p["width"], p["height"]) ``` Save a visualization (full `roboflow` package only - not `roboflow-slim`): ```python model.predict("photo.jpg", confidence=40, overlap=30).save("prediction.jpg") ``` #### Classification ```python project = rf.workspace().project("my-classifier") model = project.version(2).model predictions = model.predict("photo.jpg").json() print(predictions["top"], predictions["confidence"]) ``` Classification's `predict()` doesn't take `overlap`. Pass `hosted=True` if you're providing a URL rather than a local path. #### Instance segmentation ```python project = rf.workspace().project("my-instance-seg") model = project.version(1).model predictions = model.predict("photo.jpg", confidence=40).json() for p in predictions["predictions"]: print(p["class"], len(p["points"])) # polygon vertices ``` #### Semantic segmentation ```python project = rf.workspace().project("my-semantic-seg") model = project.version(1).model predictions = model.predict("photo.jpg").json() # Returns per-pixel class predictions (run-length encoded). ``` #### Keypoint detection ```python project = rf.workspace().project("my-keypoint") model = project.version(1).model predictions = model.predict("photo.jpg", confidence=40).json() for p in predictions["predictions"]: for kp in p["keypoints"]: print(kp["class"], kp["x"], kp["y"], kp["confidence"]) ``` #### Vision-language (VLM) ```python project = rf.workspace().project("my-vlm-project") model = project.version(1).model predictions = model.predict("photo.jpg", text="What is in this image?") print(predictions) ``` VLM models accept a `text` prompt in addition to (or sometimes instead of) the image, depending on the underlying base model. Unlike the other model classes (which return a `PredictionGroup`), `VLMModel.predict()` returns the raw serverless JSON as a plain `dict` - do not call `.json()` on it. The exact shape is free-form and depends on the base model (a caption, VQA answer, OCR text, or tokenized detections), so inspect the response for your specific model. #### Hosted images Pass `hosted=True` and a URL to skip the local upload - the inference server fetches the image directly: ```python model.predict("https://example.com/photo.jpg", hosted=True) ``` #### Where inference runs By default `model.predict()` calls the Roboflow-hosted Serverless API at `serverless.roboflow.com`. For higher throughput or on-prem use cases: * **Self-hosted Inference** - install [Roboflow Inference](https://inference.roboflow.com) and point the SDK at it via `version.model = version.model_for(local="http://localhost:9001")` (or call `inference-sdk` directly for streaming and batched calls). * **Dedicated Deployments** - see [Manage Dedicated Deployments](/deployment/roboflow-cloud/dedicated-deployments.md#python-sdk) and the [product docs deployment overview](https://docs.roboflow.com/deployment). The legacy `detect.roboflow.com` and other task-specific endpoints are deprecated - new code should use the Serverless Hosted API. #### REST and CLI equivalents * REST: see [Run a Model on an Image (REST)](#http-api). * CLI: see [Run a Model on an Image (CLI)](#cli). ### Two-Stage and CLIP Inference `Workspace` exposes three convenience methods that combine multiple models or modalities in one call: * `two_stage()` - run an object-detection model, then run a second model on each crop. * `two_stage_ocr()` - run an object-detection model, then OCR each crop. * `clip_compare()` - embed every image in a directory with [CLIP](https://openai.com/research/clip) and rank them against a target image. These helpers are useful for prototypes (license plates, badge readers, similar-image search) before you build the equivalent in a [Workflow](https://docs.roboflow.com/workflows/manage/manage-workflows#python-sdk). #### Two-stage detection + classification The first stage detects regions of interest. The second stage classifies (or runs another detector on) each cropped region. ```python import roboflow rf = roboflow.Roboflow(api_key="YOUR_API_KEY") ws = rf.workspace() results = ws.two_stage( image="photo.jpg", first_stage_model_name="cars-or-trucks", first_stage_model_version=2, second_stage_model_name="vehicle-make", second_stage_model_version=4, ) for r in results: print(r) ``` Each entry in `results` is the top second-stage prediction for one first-stage crop (the first element of the second model's `PredictionGroup`). The parent detection is used internally to crop each region but is not attached to the returned entries. #### Two-stage detection + OCR ```python results = ws.two_stage_ocr( image="photo.jpg", first_stage_model_name="license-plates", first_stage_model_version=1, ) for r in results: print(r) ``` `results` is a list with one entry per first-stage detection, in detection order. Each entry is the raw `results` value returned by the OCR endpoint for that crop (its shape depends on the OCR service). The bounding boxes are used only to crop each region and are not returned, so pair the entries with the first-stage detections by index if you need coordinates. #### CLIP image comparison `clip_compare()` embeds every image in a directory and the supplied target, returns the cosine-similarity score for each pair, sorted by similarity. ```python results = ws.clip_compare( dir="./gallery", image_ext=".jpg", target_image="./query.jpg", ) for r in results: for image_path, similarity in r.items(): print(image_path, similarity) ``` `clip_compare()` returns a `list` of single-key dicts, each shaped `{image_path: similarity_score}`, sorted from most to least similar to the target. **Parameters** * `dir` (str) - directory to scan for candidate images. * `image_ext` (str, default `".png"`) - file extension to match. Note this includes the leading dot. * `target_image` (str) - path to the image you're searching for similarity against. #### When to graduate to Workflows These helpers run on the hosted inference endpoint and serially make one HTTP call per stage / per image. Once you need conditional branching, custom blocks, or a long-running pipeline, build the equivalent as a [Workflow](https://docs.roboflow.com/workflows/manage/manage-workflows#python-sdk) - the runtime is purpose-built for chained inference. For live video, use the [Serverless Video Streaming API](/deployment/roboflow-cloud/serverless-api/serverless-video-streaming-api.md); for batches of stored images and videos, use [Batch Processing](/deployment/roboflow-cloud/batch-processing.md). ## 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 -m ``` #### 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`.