Upload API

Adding images to your datasets via the web UI is preferred when possible because it is more fully featured and you can import and validate annotations from other tools. But it can be useful to use our API to collect real world images directly from your application to improve your model.

post
Upload Image

https://api.roboflow.com/dataset/:url/upload
Note: be sure to obtain your API key from your Roboflow account here: https://app.roboflow.com/account/api
Request
Response
Request
Path Parameters
url
required
string
This is the url-safe version of the dataset name. You can find it in the web UI by looking at the URL when on the main dataset view. Example: chess-sample-xyz
Query Parameters
api_key
required
string
Obtain your API Key from the Roboflow API section of your account page.
image
optional
string
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.
name
optional
string
The filename of the image (if not set, we will try to infer it).
split
optional
string
One of: train, valid, or test (defaults to train).
Body Parameters
body
optional
string
A base64 encoded image. (Required when you don't pass an image URL in the query parameters.)
Response
200: OK
Image successfully uploaded.
{
"success": true,
"id": "XlplSXYMZIknL7yekeXg"
}
401: Unauthorized
If you don't pass an API key, don't specify a valid dataset, or don't have permission to access the dataset you specified.
{
"error": {
"message": "Unsupported get request. Dataset with ID {{url}} does not exist or cannot be loaded due to missing permissions.",
"type": "GraphMethodException",
"hint": "You can see your available datasets by issuing a GET request to /datasets"
}
}

Code Snippets

For your convenience, we've provided code snippets for calling this endpoint in various programming languages. If you need help integrating the upload API into your project don't hesitate to reach out.

All examples upload to an example dataset with an identifier of your-dataset. You can easily find your dataset's identifier by looking at the URL when you're in the Roboflow web interface.

cURL
Python
Javascript
iOS
Android
Ruby
PHP
Go
.NET
Elixir
cURL

Linux or macOS

Uploading a local file called YOUR_IMAGE.jpg:

base64 YOUR_IMAGE.jpg | curl -d @- \
"https://api.roboflow.com/dataset/your-dataset/upload?\
api_key=YOUR_KEY&\
name=YOUR_IMAGE.jpg&\
split=train"

Uploading an image hosted on the web via its URL (don't forget to URL encode it):

curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?\
api_key=YOUR_KEY&\
image=https%3A%2F%2Fi.imgur.com%2FPEEvqPN.png&\
name=201-956-1246.png&\
split=train"

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.

Python

Uploading a Local Image

To install dependencies, pip install requests pillow

import requests
import base64
import io
from PIL import Image
# Load Image with PIL
image = Image.open("YOUR_IMAGE.jpg").convert("RGB")
# Convert to JPEG Buffer
buffered = io.BytesIO()
image.save(buffered, quality=90, format="JPEG")
# Base 64 Encode
img_str = base64.b64encode(buffered.getvalue())
img_str = img_str.decode("ascii")
# Construct the URL
upload_url = "".join([
"https://api.roboflow.com/dataset/your-dataset/upload",
"?api_key=YOUR_KEY",
"&name=YOUR_IMAGE.jpg",
"&split=train"
])
# POST to the API
r = requests.post(upload_url, data=img_str, headers={
"Content-Type": "application/x-www-form-urlencoded"
})
# Output result
print(r.json())

Adding an Image Hosted Elsewhere via URL

import requests
import urllib.parse
# Construct the URL
img_url = "https://i.imgur.com/PEEvqPN.png"
upload_url = "".join([
"https://api.roboflow.com/dataset/your-dataset/upload",
"?api_key=YOUR_KEY",
"&name=201-956-1246.png",
"&split=train",
"&image=" + urllib.parse.quote_plus(img_url)
])
# POST to the API
r = requests.post(upload_url)
# Output result
print(r.json())
Javascript

Node.js

We're using axios to perform the POST request in this example so first run npm install axios to install the dependency.

Uploading 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://api.roboflow.com/dataset/your-dataset/upload",
params: {
api_key: "YOUR_KEY",
name: "YOUR_IMAGE.jpg",
split: "train"
},
data: image,
headers: {
"Content-Type": "application/x-www-form-urlencoded"
}
})
.then(function(response) {
console.log(response.data);
})
.catch(function(error) {
console.log(error.message);
});

Adding an Image Hosted Elsewhere via URL

const axios = require("axios");
axios({
method: "POST",
url: "https://api.roboflow.com/dataset/your-dataset/upload",
params: {
api_key: "YOUR_KEY",
image: "https://i.imgur.com/PEEvqPN.png",
name: "201-956-1246.png",
split: "train"
}
})
.then(function(response) {
console.log(response.data);
})
.catch(function(error) {
console.log(error.message);
});

Web

We are currently beta testing roboflow.js, a browser-based JavaScript library which, among other things, includes safe client-side uploads without exposing your secret API Key to the web. If you'd like early access, please contact us.

iOS

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your iOS app, please click below to record your upvote.

Swift

Click here to request a Swift snippet.

Objective C

Click here to request an Objective-C snippet.

Android

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Android app, please click below to record your upvote.

Kotlin

Click here to request a Kotlin snippet.

Android

Click here to request a Java snippet.

Ruby

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Ruby app, please click here to record your upvote.

PHP

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your PHP app, please click here to record your upvote.

Go

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Go app, please click here to record your upvote.

.NET

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your .NET app, please click here to record your upvote.

Elixir

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Elixir app, please click here to record your upvote.

Upload Annotations via API (Pro)

If you have an existing annotation workflow in place or want to pre-annotate images with predictions from an external model you can do so via the API. This is a feature of Roboflow Pro; please reach out for access.

post
Add Annotation

https://api.roboflow.com/dataset/:url/annotate/:image
Note: the image ID you need is returned by the /upload method.
Request
Response
Request
Path Parameters
url
required
string
This is the url-safe version of the dataset name. You can find it in the web UI by looking at the URL when on the main dataset view. Example: chess-sample-xyz
id
required
string
The image ID returned as id by the /upload method.
Query Parameters
api_key
required
string
Obtain your API Key from the Roboflow API section of your account page.
name
required
string
The filename of the annotation. This is needed to determine which parser to use.
Body Parameters
body
required
string
The annotation contents. May be in any of our supported import formats.
Response
200: OK
Image successfully uploaded.
{ "success": true }
401: Unauthorized
If you don't pass an API key, don't specify a valid dataset, or don't have permission to access the dataset you specified.
{
"error": {
"message": "Unsupported get request. Dataset with ID {{url}} does not exist or cannot be loaded due to missing permissions.",
"type": "GraphMethodException",
"hint": "You can see your available datasets by issuing a GET request to /datasets"
}
}
cURL
Python
Javascript
iOS
Android
Ruby
PHP
Go
.NET
Elixir
cURL

Linux or macOS

Attaching a VOC XML annotation to an image with ID abc123 in the your-dataset dataset called YOUR_ANNOTATION.xml:

cat YOUR_ANNOTATION.xml | curl -d @- \
"https://api.roboflow.com/dataset/your-dataset/annotate/abc123?\
api_key=YOUR_KEY&\
name=YOUR_ANNOTATION.xml"

Windows

You will need to install curl for Windows. The easiest way to do this is to use the git for Windows installer which also includes the curl command line tool when you select "Use Git and optional Unix tools from the Command Prompt" during installation.

Then you can use the same command as above.

Python

Uploading a Local Image

To install dependencies, pip install requests

import requests
annotation_filename = "YOUR_ANNOTATION.xml"
# Read Annotation as String
annotation_str = open(annotation_filename, "r").read()
# Construct the URL
upload_url = "".join([
"https://api.roboflow.com/dataset/your-dataset/annotate/abc123",
"?api_key=YOUR_KEY",
"&name=", annotation_filename
])
# POST to the API
r = requests.post(upload_url, data=annotation_str, headers={
"Content-Type": "text/plain"
})
# Output result
print(r.json())
Javascript

Node.js

We're using axios to perform the POST request in this example so first run npm install axios to install the dependency.

Uploading a Local Image

const axios = require("axios");
const fs = require("fs");
const filename = "YOUR_ANNOTATION.xml";
const annotation = fs.readFileSync(filename, "utf-8");
axios({
method: "POST",
url: "https://api.roboflow.com/dataset/your-dataset/annotate/abc123",
params: {
api_key: "YOUR_KEY",
name: filename
},
data: annotation,
headers: {
"Content-Type": "text/plain"
}
})
.then(function(response) {
console.log(response.data);
})
.catch(function(error) {
console.log(error.message);
});
iOS

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your iOS app, please click below to record your upvote.

Swift

Click here to request a Swift snippet.

Objective C

Click here to request an Objective-C snippet.

Android

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Android app, please click below to record your upvote.

Kotlin

Click here to request a Kotlin snippet.

Android

Click here to request a Java snippet.

Ruby

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Ruby app, please click here to record your upvote.

PHP

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your PHP app, please click here to record your upvote.

Go

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Go app, please click here to record your upvote.

.NET

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your .NET app, please click here to record your upvote.

Elixir

We are adding code snippets as they are requested by users. If you'd like to integrate the upload API into your Elixir app, please click here to record your upvote.