Keypoint Detection

Run inference on your object detection models hosted on Roboflow.

To run inference through our hosted API using Python, use the roboflow Python package:

from roboflow import Roboflow
rf = Roboflow(api_key="API_KEY")
project = rf.workspace().project("MODEL_ENDPOINT")
model = project.version(VERSION).model

# infer on a local image
print(model.predict("your_image.jpg", confidence=40, overlap=30).json())

# visualize your prediction
# model.predict("your_image.jpg", confidence=40, overlap=30).save("prediction.jpg")

# infer on an image hosted elsewhere
# print(model.predict("URL_OF_YOUR_IMAGE", hosted=True, confidence=40, overlap=30).json())

Response Object Format

The hosted API inference route returns a JSON object containing an array of predictions. Each prediction has the following properties:

  • x = the horizontal center point of the detected object

  • y = the vertical center point of the detected object

  • width = the width of the bounding box

  • height = the height of the bounding box

  • class = the class label of the detected object

  • confidence = the model's confidence that the detected object has the correct label and position coordinates

  • keypoints = an array of keypoint predictions

    • x = horizontal center of keypoint (relative to image top-left corner)

    • y = vertical center of keypoint (relative to image top-left corner)

    • class_name = name of keypoint

    • class_id = id of keypoint, maps to skeleton vertices in version record, to map vertex color and skeleton edges, View your Project Version

    • confidence = confidence that the keypoint has correct position, and is visible (not occluded or deleted)

Here is an example response object from the REST API:

    "predictions": [
            "x": 189.5,
            "y": 100,
            "width": 163,
            "height": 186,
            "class": "helmet",
            "confidence": 0.544,
            "keypoints": [
                    "x": 189, 
                    "y": 20,
                    "class_name": "top",
                    "class_id": 0,
                    "confidence": 0.91
                    "x": 188, 
                    "y": 180,
                    "class_name": "bottom",
                    "class_id": 1,
                    "confidence": 0.93
    "image": {
        "width": 2048,
        "height": 1371

The image attribute contains the height and width of the image sent for inference. You may need to use these values for bounding box calculations.

Inference API Parameters

Using the Inference API


You can POST a base64 encoded image directly to your model endpoint. Or you can pass a URL as the image parameter in the query string if your image is already hosted elsewhere.

Path Parameters




The url-safe version of the dataset name. You can find it in the web UI by looking at the URL on the main project view or by clicking the "Get curl command" button in the train results section of your dataset version after training your model.



The version number identifying the version of of your dataset

Query Parameters




URL of the image to add. Use if your image is hosted elsewhere. (Required when you don't POST a base64 encoded image in the request body.) Note: don't forget to URL-encode it.



Restrict the predictions to only those of certain classes. Provide as a comma-separated string. Example: dog,cat Default: not present (show all classes)



The maximum percentage (on a scale of 0-100) that bounding box predictions of the same class are allowed to overlap before being combined into a single box. Default: 30



A threshold for the returned predictions on a scale of 0-100. A lower number will return more predictions. A higher number will return fewer high-certainty predictions. Default: 40



The width (in pixels) of the bounding box displayed around predictions (only has an effect when format is image). Default: 1



Whether or not to display text labels on the predictions (only has an effect when format is image). Default: false



json - returns an array of JSON predictions. (See response format tab). image - returns an image with annotated predictions as a binary blob with a Content-Type of image/jpeg. image_and_json - returns an array of JSON predictions, including a visualization field in base64. Default: json



Your API key (obtained via your workspace API settings page)

Request Body



A base64 encoded image. (Required when you don't pass an image URL in the query parameters).

    "predictions": [{
        "x": 234.0,
        "y": 363.5,
        "width": 160,
        "height": 197,
        "class": "hand",
        "confidence": 0.943
    }, {
        "x": 504.5,
        "y": 363.0,
        "width": 215,
        "height": 172,
        "class": "hand",
        "confidence": 0.917
    }, {
        "x": 1112.5,
        "y": 691.0,
        "width": 139,
        "height": 52,
        "class": "hand",
        "confidence": 0.87
    }, {
        "x": 78.5,
        "y": 700.0,
        "width": 139,
        "height": 34,
        "class": "hand",
        "confidence": 0.404

Last updated