Hosted API (Remote Server)

Leverage your custom trained model for cloud-hosted inference.
Overview
Each model trained with Roboflow Train is deployed as a custom API you can use to make predictions from any device that has an internet connection. Inference is done on the server so you don't need to worry about the edge device's hardware capabilities.
We automatically scale this API up and down and do load balancing for you so that you can rest assured that your application will be able to handle sudden spikes in traffic without having to pay for GPU time you're not using. Our hosted prediction API has been battle-hardened to handle even the most demanding production applications (including concurrently surviving through the famous Hacker News and Reddit "hugs of death" without so much as batting an eye).
Single-Label Classification
Response Object Format
The hosted API inference route returns a JSON object containing an array of predictions. Each prediction has the following properties:
time = total time, in seconds, to process the image and return predictions
image = an object that holds information about the image width and height
width the height of the predicted image
height = the height of the predicted image
predictions = collection of all predicted classes and their associated confidence values for the prediction
class = the label of the classification
confidence = the model's confidence that the image contains objects of the detected classification
top = highest confidence predicted class
confidence = highest predicted confidence score
image_path = path of the predicted image
prediction_type = the model type used to perform inference, ClassificationModel in this case
// an example JSON object
{
 "time": 0.19064618100037478,
 "image": {
 "width": 210,
 "height": 113
 },
 "predictions": [
 {
 "class": "real-image",
 "confidence": 0.7149
 },
 {
 "class": "illustration",
 "confidence": 0.2851
 }
 ],
 "top": "real-image",
 "confidence": 0.7149,
 "image_path": "/cropped-images-1.jpg",
 "prediction_type": "ClassificationModel"
}
​Locating Your Project Information​
Multi-Label Classification
Response Object Format
The hosted API inference route returns a JSON object containing an array of predictions. Each prediction has the following properties:
time = total time, in seconds, to process the image and return predictions
image = an object that holds information about the image width and height
width the height of the predicted image
height = the height of the predicted image
predictions = collection of all predicted classes and their associated confidence values for the prediction
class = the label of the classification
confidence = the model's confidence that the image contains objects of the detected classification
predicted_classes = an array that contains a list of all classifications (labels/classes) returned in model predictions
image_path = path of the predicted image
prediction_type = the model type used to perform inference, ClassificationModel in this case
// an example JSON object
{
 "time": 0.19291414400004214,
 "image": {
 "width": 113,
 "height": 210
 },
 "predictions": {
 "dent": {
 "confidence": 0.5253503322601318
 },
 "severe": {
 "confidence": 0.5804202556610107
 }
 },
 "predicted_classes": [
 "dent",
 "severe"
 ],
 "image_path": "/car-model-343.jpg",
 "prediction_type": "ClassificationModel"
}
The Example Web App
The easiest way to familiarize yourself with the inference endpoint is to visit the Example Web App. To use the Web App, simply input your model , version and api_key. These will be pre-filled for you after training completes if you click through via the web UI under your versions "Training Results" section.
Then select an image via Choose File. After you have chosen the settings you want, click Run Inference. 
On the left side of the screen, you will see example JavaScript code for posting a base64-encoded image to the inference endpoint. Within the form portion of the Web App, you can experiment with changing different API parameters when posting to the API.
post
https://classify.roboflow.com
/:datasetSlug/:versionNumber
Using the Inference API
Code Snippets
For your convenience, we've provided code snippets for calling this endpoint in various programming languages. If you need help integrating the inference API into your project don't hesitate to reach out.
All examples upload to an example dataset with a model-endpoint of your-dataset-slug/your-version. You can easily find your dataset's identifier by looking at the curl command shown in the Roboflow web interface after your model has finished training.
Note: These docs are auto-generated with your API key and version in your Deploy tab within the Roboflow application.
Python
Javascript
Swift
Infer on Local and Hosted Images
To install dependencies, pip install roboflow
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").json())
​
# visualize your prediction
# model.predict("your_image.jpg").save("prediction.jpg")
​
# infer on an image hosted elsewhere
# print(model.predict("URL_OF_YOUR_IMAGE", hosted=True).json())
Inference with the Hosted API
1
import cv2
2
import base64
3
import numpy as np
4
import requests
5
import time
6
import json
7
​
8
# https://docs.roboflow.com/rest-api#obtaining-your-api-key
9
ROBOFLOW_API_KEY = "INSERT_PRIVATE_API_KEY"
10
# https://docs.roboflow.com/python#finding-your-project-information-manually
11
ROBOFLOW_MODEL = f"{INSERT_ROBOFLOW_MODEL_ID}/{VERSION_NUMBER}")
12
​
13
# Construct the Roboflow Infer URL
14
# (if running locally replace https://classify.roboflow.com/ with eg http://127.0.0.1:9001/)
15
upload_url = "".join([
16
 "https://classify.roboflow.com/",
17
 ROBOFLOW_MODEL,
18
 "?api_key=",
19
 ROBOFLOW_API_KEY,
20
 "&format=image",
21
 ])
22
​
23
img = cv2.imread("YOUR_IMAGE.jpg")
24
​
25
# Resize (while maintaining the aspect ratio) to improve speed and save bandwidth
26
height, width, channels = img.shape
27
scale = ROBOFLOW_SIZE / max(height, width)
28
img = cv2.resize(img, (round(scale * width), round(scale * height)))
29
​
30
# Encode image to base64 string
31
retval, buffer = cv2.imencode('.jpg', img)
32
img_str = base64.b64encode(buffer)
33
​
34
# Get prediction from Roboflow Infer API
35
resp = requests.post(upload_url, data=img_str, headers={
36
 "Content-Type": "application/x-www-form-urlencoded"
37
}, stream=True)
38
​
39
preds = resp.json()
Node.js
We're using axios to perform the POST request in this example so first run npm install axios to install the dependency.
Inferring on a Local Image
const axios = require("axios");
const fs = require("fs");
​
const image = fs.readFileSync("YOUR_IMAGE.jpg", {
 encoding: "base64"
});
​
axios({
 method: "POST",
 url: "https://classify.roboflow.com/your-model/42",
 params: {
 api_key: "YOUR_KEY"
 },
 data: image,
 headers: {
 "Content-Type": "application/x-www-form-urlencoded"
 }
})
.then(function(response) {
 console.log(response.data);
})
.catch(function(error) {
 console.log(error.message);
});
Uploading a Local Image Using base64
​
import UIKit
​
// Load Image and Convert to Base64
let image = UIImage(named: "your-image-path") // path to image to upload ex: image.jpg
let imageData = image?.jpegData(compressionQuality: 1)
let fileContent = imageData?.base64EncodedString()
let postData = fileContent!.data(using: .utf8)
​
// Initialize Inference Server Request with API_KEY, Model, and Model Version
var request = URLRequest(url: URL(string: "https://classify.roboflow.com/your-model/your-model-version?api_key=YOUR_APIKEY&name=YOUR_IMAGE.jpg")!,timeoutInterval: Double.infinity)
request.addValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
request.httpMethod = "POST"
request.httpBody = postData
​
// Execute Post Request
URLSession.shared.dataTask(with: request, completionHandler: { data, response, error in
 
 // Parse Response to String
 guard let data = data else {
 print(String(describing: error))
 return
 }
 
 // Convert Response String to Dictionary
 do {
 let dict = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]
 } catch {
 print(error.localizedDescription)
 }
 
 // Print String Response
 print(String(data: data, encoding: .utf8)!)
}).resume()
Accessing Prediction Response Values
Single-Label Classification
All predictions - Single Label Classification:
1
for prediction in preds['predictions']:
2
 print(prediction['class'], prediction['confidence'])
Highest confidence prediction - Single-Label Classification:
1
print(preds['top']) # Example output (type: str) : real-image
2
print(preds['confidence']) #Example output (type: float) : 0.9868
Multi-Label Classification
Predicted classes - Multi-Label Classification:
1
print(preds['predicted_classes']) # Example output (type: list) : ["dent", "severe"]
Confidence values for each predicted class - Multi-Label Classification:
1
class_labels = preds['predicted_classes'] # Example - (type: list) : ["dent", "severe"]
2
​
3
for i in class_labels:
4
 print(preds['predictions'][class_labels[i]])
Inference - Classification
Inference - Instance Segmentation
Last modified 12d ago
Hosted API (Remote Server)

Overview

Single-Label Classification

Response Object Format

​Locating Your Project Information​

Multi-Label Classification

Response Object Format

The Example Web App

Code Snippets

Infer on Local and Hosted Images

Inference with the Hosted API

Node.js

Inferring on a Local Image

Uploading a Local Image Using base64

Accessing Prediction Response Values

Single-Label Classification

Multi-Label Classification

Locating Your Project Information
