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
https://api.roboflow.com
/dataset/:url/upload
Upload Image

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

Linux or macOS

Uploading a local file called YOUR_IMAGE.jpg:
1
base64 YOUR_IMAGE.jpg | curl -d @- \
2
"https://api.roboflow.com/dataset/your-dataset/upload?\
3
api_key=YOUR_KEY&\
4
name=YOUR_IMAGE.jpg&\
5
split=train"
Copied!
Uploading an image hosted on the web via its URL (don't forget to URL encode it):
1
curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?\
2
api_key=YOUR_KEY&\
3
image=https%3A%2F%2Fi.imgur.com%2FPEEvqPN.png&\
4
name=201-956-1246.png&\
5
split=train"
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 pillow
1
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://api.roboflow.com/dataset/your-dataset/upload",
20
"?api_key=YOUR_KEY",
21
"&name=YOUR_IMAGE.jpg",
22
"&split=train"
23
])
24
25
# POST to the API
26
r = requests.post(upload_url, data=img_str, headers={
27
"Content-Type": "application/x-www-form-urlencoded"
28
})
29
30
# Output result
31
print(r.json())
Copied!

Adding 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
"https://api.roboflow.com/dataset/your-dataset/upload",
8
"?api_key=YOUR_KEY",
9
"&name=201-956-1246.png",
10
"&split=train",
11
"&image=" + urllib.parse.quote_plus(img_url)
12
])
13
14
# POST to the API
15
r = requests.post(upload_url)
16
17
# Output result
18
print(r.json())
Copied!

How To Upload an Image with the API (Python)

We also have a video demonstration of using the Upload API with Python:
Uploading images and annotations with Python

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

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://api.roboflow.com/dataset/your-dataset/upload",
11
params: {
12
api_key: "YOUR_KEY",
13
name: "YOUR_IMAGE.jpg",
14
split: "train"
15
},
16
data: image,
17
headers: {
18
"Content-Type": "application/x-www-form-urlencoded"
19
}
20
})
21
.then(function(response) {
22
console.log(response.data);
23
})
24
.catch(function(error) {
25
console.log(error.message);
26
});
Copied!

Adding an Image Hosted Elsewhere via URL

1
const axios = require("axios");
2
3
axios({
4
method: "POST",
5
url: "https://api.roboflow.com/dataset/your-dataset/upload",
6
params: {
7
api_key: "YOUR_KEY",
8
image: "https://i.imgur.com/PEEvqPN.png",
9
name: "201-956-1246.png",
10
split: "train"
11
}
12
})
13
.then(function(response) {
14
console.log(response.data);
15
})
16
.catch(function(error) {
17
console.log(error.message);
18
});
Copied!

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.
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

Objective C

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

Android

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.
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.
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.
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.
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

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.
post
https://api.roboflow.com
/dataset/:url/annotate/:image
Add Annotation
cURL
Python
Javascript
iOS
Android
Ruby
PHP
Go
.NET
Elixir

Linux or macOS

Attaching a VOC XML annotation to an image with ID abc123 in the your-dataset dataset called YOUR_ANNOTATION.xml:
1
cat YOUR_ANNOTATION.xml | curl -d @- \
2
"https://api.roboflow.com/dataset/your-dataset/annotate/abc123?\
3
api_key=YOUR_KEY&\
4
name=YOUR_ANNOTATION.xml"
Copied!

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.

Uploading a Local Annotation

To install dependencies, pip install requests
1
import requests
2
3
annotation_filename = "YOUR_ANNOTATION.xml"
4
5
# Read Annotation as String
6
annotation_str = open(annotation_filename, "r").read()
7
8
# Construct the URL
9
upload_url = "".join([
10
"https://api.roboflow.com/dataset/your-dataset/annotate/abc123",
11
"?api_key=YOUR_KEY",
12
"&name=", annotation_filename
13
])
14
15
# POST to the API
16
r = requests.post(upload_url, data=annotation_str, headers={
17
"Content-Type": "text/plain"
18
})
19
20
# Output result
21
print(r.json())
Copied!

How To Upload an Annotation with the API (Python)

We also have a video demonstration of using the Upload API with Python:
Uploading images and annotations with Python

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

1
const axios = require("axios");
2
const fs = require("fs");
3
4
const filename = "YOUR_ANNOTATION.xml";
5
const annotation = fs.readFileSync(filename, "utf-8");
6
7
axios({
8
method: "POST",
9
url: "https://api.roboflow.com/dataset/your-dataset/annotate/abc123",
10
params: {
11
api_key: "YOUR_KEY",
12
name: filename
13
},
14
data: annotation,
15
headers: {
16
"Content-Type": "text/plain"
17
}
18
})
19
.then(function(response) {
20
console.log(response.data);
21
})
22
.catch(function(error) {
23
console.log(error.message);
24
});
Copied!
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

Objective C

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

Android

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.
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.
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.
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.
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.
Last modified 1mo ago