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).
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.
Obtaining Your Model Endpoint
To use the inference API, you will need your model url slug, version number and the API key for the workspace the project belongs to. Your API key can be retrieved from in your workspace's settings page under the "Roboflow API" section. Your model url slug is the unique and url-safe version of your dataset name. The easiest way to retrieve it is via the web UI by clicking the "curl command" link:
post
https://detect.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.cURL
Python
Javascript
iOS
Android
Ruby
PHP
Go
.NET
Elixir
Linux or MacOS
Retrieving JSON predictions for a local file called
YOUR_IMAGE.jpg:1
base64 YOUR_IMAGE.jpg | curl -d @- \
2
"https://detect.roboflow.com/your-model/42?api_key=YOUR_KEY"
Copied!
1
curl -X POST "https://infer.roboflow.com/your-model/42?\
2
api_key=YOUR_KEY&\
3
image=https%3A%2F%2Fi.imgur.com%2FPEEvqPN.png"
Copied!
Windows
You will need to install curl for Windows and GNU's base64 tool for Windows. The easiest way to do this is to use the git for Windows installer which also includes the
curl and base64 command line tools when you select "Use Git and optional Unix tools from the Command Prompt" during installation.Then you can use the same commands as above.
Uploading a Local Image
To install dependencies,
pip install requests pillow1
import requests
2
import base64
3
import io
4
from PIL import Image
5
​
6
# Load Image with PIL
7
image = Image.open("YOUR_IMAGE.jpg").convert("RGB")
8
​
9
# Convert to JPEG Buffer
10
buffered = io.BytesIO()
11
image.save(buffered, quality=90, format="JPEG")
12
​
13
# Base 64 Encode
14
img_str = base64.b64encode(buffered.getvalue())
15
img_str = img_str.decode("ascii")
16
​
17
# Construct the URL
18
upload_url = "".join([
19
"https://detect.roboflow.com/your-model/42",
20
"?api_key=YOUR_KEY",
21
"&name=YOUR_IMAGE.jpg"
22
])
23
​
24
# POST to the API
25
r = requests.post(upload_url, data=img_str, headers={
26
"Content-Type": "application/x-www-form-urlencoded"
27
})
28
​
29
# Output result
30
print(r.json())
Copied!
Inferring on an Image Hosted Elsewhere via URL
1
import requests
2
import urllib.parse
3
​
4
# Construct the URL
5
img_url = "https://i.imgur.com/PEEvqPN.png"
6
upload_url = "".join([
7
"detect.roboflow.com/your-model/42",
8
"?api_key=YOUR_KEY",
9
"&image=" + urllib.parse.quote_plus(img_url)
10
])
11
​
12
# POST to the API
13
r = requests.post(upload_url)
14
​
15
# Output result
16
print(r.json())
Copied!
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
1
const axios = require("axios");
2
const fs = require("fs");
3
​
4
const image = fs.readFileSync("YOUR_IMAGE.jpg", {
5
encoding: "base64"
6
});
7
​
8
axios({
9
method: "POST",
10
url: "https://detect.roboflow.com/your-model/42",
11
params: {
12
api_key: "YOUR_KEY"
13
},
14
data: image,
15
headers: {
16
"Content-Type": "application/x-www-form-urlencoded"
17
}
18
})
19
.then(function(response) {
20
console.log(response.data);
21
})
22
.catch(function(error) {
23
console.log(error.message);
24
});
Copied!
Inferring on an Image Hosted Elsewhere via URL
1
const axios = require("axios");
2
​
3
axios({
4
method: "POST",
5
url: "https://detect.roboflow.com/your-model/42",
6
params: {
7
api_key: "YOUR_KEY",
8
image: "https://i.imgur.com/PEEvqPN.png"
9
}
10
})
11
.then(function(response) {
12
console.log(response.data);
13
})
14
.catch(function(error) {
15
console.log(error.message);
16
});
Copied!
Web
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your iOS app, please click below to record your upvote.
Swift
Objective C
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your Android app, please click below to record your upvote.
Kotlin
Java
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your Ruby app, please click here to record your upvote.
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your PHP app, please click here to record your upvote.
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your Go app, please click here to record your upvote.
Uploading a Local Image
1
using System;
2
using System.IO;
3
using System.Net;
4
using System.Text;
5
​
6
namespace UploadLocal
7
{
8
class UploadLocal
9
{
10
​
11
static void Main(string[] args)
12
{
13
byte[] imageArray = System.IO.File.ReadAllBytes(@"YOUR_IMAGE.jpg");
14
string encoded = Convert.ToBase64String(imageArray);
15
byte[] data = Encoding.ASCII.GetBytes(encoded);
16
string API_KEY = ""; // Your API Key
17
string DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)
18
​
19
// Construct the URL
20
string uploadURL =
21
"https://api.roboflow.com/dataset/" +
22
DATASET_NAME + "/upload" +
23
"?api_key=" + API_KEY +
24
"&name=YOUR_IMAGE.jpg" +
25
"&split=train";
26
​
27
// Service Request Config
28
ServicePointManager.Expect100Continue = true;
29
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
30
​
31
// Configure Request
32
WebRequest request = WebRequest.Create(uploadURL);
33
request.Method = "POST";
34
request.ContentType = "application/x-www-form-urlencoded";
35
request.ContentLength = data.Length;
36
​
37
// Write Data
38
using (Stream stream = request.GetRequestStream())
39
{
40
stream.Write(data, 0, data.Length);
41
}
42
​
43
// Get Response
44
string responseContent = null;
45
using (WebResponse response = request.GetResponse())
46
{
47
using (Stream stream = response.GetResponseStream())
48
{
49
using (StreamReader sr99 = new StreamReader(stream))
50
{
51
responseContent = sr99.ReadToEnd();
52
}
53
}
54
}
55
​
56
Console.WriteLine(responseContent);
57
​
58
}
59
}
60
}
Copied!
Inferring on a Local Image
1
using System;
2
using System.IO;
3
using System.Net;
4
using System.Text;
5
​
6
namespace InferenceLocal
7
{
8
class InferenceLocal
9
{
10
​
11
static void Main(string[] args)
12
{
13
byte[] imageArray = System.IO.File.ReadAllBytes(@"YOUR_IMAGE.jpg");
14
string encoded = Convert.ToBase64String(imageArray);
15
byte[] data = Encoding.ASCII.GetBytes(encoded);
16
string API_KEY = ""; // Your API Key
17
string MODEL_ENDPOINT = "dataset/v"; // Set model endpoint
18
​
19
// Construct the URL
20
string uploadURL =
21
"https://detect.roboflow.com/" + MODEL_ENDPOINT + "?api_key=" + API_KEY
22
+ "&name=YOUR_IMAGE.jpg";
23
​
24
// Service Request Config
25
ServicePointManager.Expect100Continue = true;
26
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
27
​
28
// Configure Request
29
WebRequest request = WebRequest.Create(uploadURL);
30
request.Method = "POST";
31
request.ContentType = "application/x-www-form-urlencoded";
32
request.ContentLength = data.Length;
33
​
34
// Write Data
35
using (Stream stream = request.GetRequestStream())
36
{
37
stream.Write(data, 0, data.Length);
38
}
39
​
40
// Get Response
41
string responseContent = null;
42
using (WebResponse response = request.GetResponse())
43
{
44
using (Stream stream = response.GetResponseStream())
45
{
46
using (StreamReader sr99 = new StreamReader(stream))
47
{
48
responseContent = sr99.ReadToEnd();
49
}
50
}
51
}
52
​
53
Console.WriteLine(responseContent);
54
​
55
}
56
}
57
}
Copied!
Uploading an Image Hosted Elsewhere via URL
1
using System;
2
using System.IO;
3
using System.Net;
4
using System.Web;
5
​
6
namespace UploadHosted
7
{
8
class UploadHosted
9
{
10
static void Main(string[] args)
11
{
12
string API_KEY = ""; // Your API Key
13
string DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)
14
string imageURL = "https://i.imgur.com/PEEvqPN.png";
15
imageURL = HttpUtility.UrlEncode(imageURL);
16
​
17
// Construct the URL
18
string uploadURL =
19
"https://api.roboflow.com/dataset/" +
20
DATASET_NAME + "/upload" +
21
"?api_key=" + API_KEY +
22
"&name=YOUR_IMAGE.jpg" +
23
"&split=train" +
24
"&image=" + imageURL;
25
​
26
// Service Point Config
27
ServicePointManager.Expect100Continue = true;
28
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
29
​
30
// Configure Http Request
31
WebRequest request = WebRequest.Create(uploadURL);
32
request.Method = "POST";
33
request.ContentType = "application/x-www-form-urlencoded";
34
request.ContentLength = 0;
35
​
36
// Get Response
37
string responseContent = null;
38
using (WebResponse response = request.GetResponse())
39
{
40
using (Stream stream = response.GetResponseStream())
41
{
42
using (StreamReader sr99 = new StreamReader(stream))
43
{
44
responseContent = sr99.ReadToEnd();
45
}
46
}
47
}
48
​
49
Console.WriteLine(responseContent);
50
​
51
}
52
}
53
}
Copied!
Inferring on an Image Hosted Elsewhere via URL
1
using System;
2
using System.IO;
3
using System.Net;
4
using System.Web;
5
​
6
namespace InferenceHosted
7
{
8
class InferenceHosted
9
{
10
static void Main(string[] args)
11
{
12
string API_KEY = ""; // Your API Key
13
string imageURL = "https://i.ibb.co/jzr27x0/YOUR-IMAGE.jpg";
14
string MODEL_ENDPOINT = "dataset/v"; // Set model endpoint
15
​
16
// Construct the URL
17
string uploadURL =
18
"https://detect.roboflow.com/" + MODEL_ENDPOINT
19
+ "?api_key=" + API_KEY
20
+ "&image=" + HttpUtility.UrlEncode(imageURL);
21
​
22
// Service Point Config
23
ServicePointManager.Expect100Continue = true;
24
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
25
​
26
// Configure Http Request
27
WebRequest request = WebRequest.Create(uploadURL);
28
request.Method = "POST";
29
request.ContentType = "application/x-www-form-urlencoded";
30
request.ContentLength = 0;
31
​
32
// Get Response
33
string responseContent = null;
34
using (WebResponse response = request.GetResponse())
35
{
36
using (Stream stream = response.GetResponseStream())
37
{
38
using (StreamReader sr99 = new StreamReader(stream))
39
{
40
responseContent = sr99.ReadToEnd();
41
}
42
}
43
}
44
​
45
Console.WriteLine(responseContent);
46
​
47
}
48
}
49
}
Copied!
We are adding code snippets as they are requested by users. If you'd like to integrate the inference API into your Elixir app, please click here to record your upvote.
Video Inference
To get predictions from your model on a video, split it into frames, perform inference on each frame, then composite the predictions back into a rendered video.
We have an open source video inference utility script that performs these steps with
ffmpeg and the Roboflow Inference API:GitHub - roboflow-ai/video-inference: Example showing how to do inference on a video file with Roboflow Infer
GitHub
Using Your Webcam
You can also pipe frames from your webcam to your Roboflow model for predictions. We've created a tutorial with example code to show you how:
Using Your Webcam with Roboflow Models
Roboflow Blog
Displaying the Response Image with format=image
If you pass
format=image in the query string the inference API will return a base64 encoded string of your image with the inference detections drawn on top. You can decode this with your favorite image processing library - here we provide an example with cv2 and numpy1
# Get prediction from Roboflow Infer API
2
resp = requests.post(upload_url, data=img_str, headers={
3
"Content-Type": "application/x-www-form-urlencoded"
4
}, stream=True).raw
5
​
6
# Parse result image
7
image = np.asarray(bytearray(resp.read()), dtype="uint8")
8
image = cv2.imdecode(image, cv2.IMREAD_COLOR)
Copied!
Drawing a Box from the Inference API JSON Output
Note: to receive and image with predicted box output - just pass "format=image" as a query parameter. This section shows an example if you want to double check and parse your JSON output.
Let's suppose you've created an inference url to return JSON predictions like so:
1
parts = []
2
url_base = 'https://infer.roboflow.com/'
3
endpoint = '[YOUR-MODEL]'
4
access_token = '?access_token=[YOUR_TOKEN]'
5
format = '&format=json'
6
confidence = '&confidence=10'
7
stroke='&stroke=5'
8
parts.append(url_base)
9
parts.append(endpoint)
10
parts.append(access_token)
11
parts.append(format)
12
parts.append(confidence)
13
parts.append(stroke)
14
url = ''.join(parts)
Copied!
And you've drawn an inference from your API like so:
1
import glob
2
import requests
3
import base64
4
from base64 import decodebytes
5
import io
6
from PIL import Image
7
import time
8
import cv2
9
from io import BytesIO
10
​
11
​
12
f = '[YOUR-IMAGE].jpg'
13
image = Image.open(f)
14
buffered = io.BytesIO()
15
image = image.convert("RGB")
16
image.save(buffered, quality=90, format="JPEG")
17
img_str = base64.b64encode(buffered.getvalue())
18
img_str = img_str.decode("ascii")
19
​
20
headers = {'accept': 'application/json'}
21
start = time.time()
22
r = requests.post(url, data=img_str, headers=headers)
23
print('post took ' + str(time.time() - start))
24
​
25
# print(r)
26
print(r.json())
27
preds = r.json()
28
detections = preds['predictions']
Copied!
Then you can draw the box on your image like so:
1
from PIL import Image, ImageDraw, ImageFont
2
f = './[YOUR-IMAGE].jpg'
3
image = Image.open(f)
4
​
5
draw = ImageDraw.Draw(image)
6
font = ImageFont.load_default()
7
​
8
for box in detections:
9
color = "#4892EA"
10
x1 = box['x'] - box['width'] / 2
11
x2 = box['x'] + box['width'] / 2
12
y1 = box['y'] - box['height'] / 2
13
y2 = box['y'] + box['height'] / 2
14
​
15
draw.rectangle([
16
x1, y1, x2, y2
17
], outline=color, width=5)
18
​
19
if True:
20
text = box['class']
21
text_size = font.getsize(text)
22
​
23
# set button size + 10px margins
24
button_size = (text_size[0]+20, text_size[1]+20)
25
button_img = Image.new('RGBA', button_size, color)
26
# put text on button with 10px margins
27
button_draw = ImageDraw.Draw(button_img)
28
button_draw.text((10, 10), text, font=font, fill=(255,255,255,255))
29
​
30
# put button on source image in position (0, 0)
31
image.paste(button_img, (int(x1), int(y1)))
32
image.show()
Copied!
Last modified 1mo ago