> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/manage/manage-images.md).

# Manage Images

## About

Roboflow lets you upload, annotate, inspect, tag, and delete individual images in a project through the REST API and the Python SDK. Use these operations when you need finer control than the bulk dataset upload flow provides - for example, uploading one image at a time from a stream, attaching annotations after the fact, or updating image metadata and tags.

## HTTP API

The REST API exposes per-image operations for uploading images and annotations, fetching image details, deleting images, and managing image tags and metadata.

### Upload an Image

You can upload images to Roboflow projects using the web interface, Python SDK, REST API, and CLI.

{% hint style="info" %}
**Server-side dedup (1.3.6+):** As of `roboflow` 1.3.6, the SDK uploads original image bytes rather than re-encoding via Pillow. The Roboflow server deduplicates uploads by SHA-256 - re-uploading the same file (e.g. into a different batch) succeeds without consuming additional storage credits.
{% endhint %}

{% tabs %}
{% tab title="Python SDK" %}

#### Upload to an Existing Project

```python
from roboflow import Roboflow

# Initialize the Roboflow object with your API key
rf = Roboflow(api_key="YOUR_API_KEY")

# Retrieve your current workspace and project name
print(rf.workspace())

# Specify the project for upload
# let's you have a project at https://app.roboflow.com/my-workspace/my-project
workspaceId = 'my-workspace'
projectId = 'my-project'
project = rf.workspace(workspaceId).project(projectId)

# Upload the image to your project
project.upload("UPLOAD_IMAGE.jpg")

"""
Optional Parameters:
- num_retry_uploads: Number of retries for uploading the image in case of failure.
- batch_name: Upload the image to a specific batch.
- split: Upload the image to a specific split.
- tag: Store metadata as a tag on the image.
- sequence_number: [Optional] If you want to keep the order of your images in the dataset, pass sequence_number and sequence_size..
- sequence_size: [Optional] The total number of images in the sequence. Defaults to 100,000 if not set.
"""

project.upload(
    image_path="UPLOAD_IMAGE.jpg",
    batch_name="YOUR_BATCH_NAME",
    split="train",
    num_retry_uploads=3,
    tag_names=["YOUR_TAG_NAME"],
    sequence_number=99,
    sequence_size=100
)
```

#### Upload to a New Project

To upload a new project, add the following code before your model upload:

```python
from roboflow import Roboflow
rf = Roboflow(api_key="YOUR_API_KEY")

new_project = rf.workspace().create_project(
    project_name="PROJECT_NAME",
    project_license="MIT",
    project_type="PROJECT_TYPE", 
    annotation="PROJECT_DESCRIPTION"
)

"""
Parameters:
- project_name: Preferred project name.
- project_type: Must be one of object-detection, single-label-classification, multi-label-classification, instance-segmentation, or semantic-segmentation.
- project_description: Preferred project description.
"""

```

{% endtab %}

{% tab title="CLI" %}
CLI upload is especially useful if you have a large number of images (i.e. 1,000+) that you want to upload to Roboflow.

#### Upload a Single Image

To upload a single file, use the following command:

```
roboflow upload image.jpg
```

This will ask you which of your projects to upload into, but you can also skip that by specifying it explicitly using the `-p` option to the command.

#### Upload an Image and Annotation

If you have annotations for your image such as a file called `image.xml`:

```
roboflow upload image1.jpg -a image.xml
```

#### Upload all Images

To upload all images in a folder, use the following command:

```
roboflow upload *.jpg
```

#### Upload all Images and Annotations

If you have many images with annotations, you can pass a special “\[filename]” value to the `-a` option that will match the annotation file name based on the name of the image. This would upload image1.jpg with annotations from `image1.xml`, and `image2.jpg` with annotations from `image2.xml`, etc

```
roboflow upload *.jpg -a “[filename].xml”
```

This only works if you have one annotation file for each image. If you have an entire dataset in a common format, like one downloaded from Roboflow Universe, you can also use the `import` command.

#### Upload a Dataset

To upload a full dataset, refer to the Upload Dataset documentation.
{% endtab %}

{% tab title="cURL" %}

#### Parameters

Querystring parameters accepted by the API:

**api\_key**: Obtain from <https://app.roboflow.com/account/api\\>
**image**: \[Optional] 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).\
**name**: \[Optional] The filename of the image (if not set, we will try to infer it).\
**batch**: \[Optional] Group images under a batch with this name\
**tag**: \[Optional] Can be specified multiple times. Add tags to uploaded image.\
**split**: \[Optional] One of: train, valid, or test (defaults to train).\
**sequence\_number**: \[Optional] If you want to keep the order of your images in the dataset, you can uploaded images increasing sequence numbers.\
**sequence\_size**: \[Optional] The total number of images in the sequence. Defaults to 100,000 if not set.\
**inference\_id**: \[Optional] The inference ID passed returned from a roboflow inference detection. This inference\_id allows the image to be correlated with a roboflow detection in Model Monitoring (enterprise feature).

#### Linux or macOS

Uploading a local file called `YOUR_IMAGE.jpg` using multipart/form-data (recommended):

```
curl -F name=YOUR_IMAGE.jpg -F split=train \
-F file=@YOUR_IMAGE.jpg \
"https://api.roboflow.com/dataset/YOUR_DATASET_NAME/upload?\
api_key=$ROBOFLOW_API_KEY"
```

Alternatively, uploading a base64 encoded image:

```bash
base64 -i YOUR_IMAGE.jpg | curl -d @- \
"https://api.roboflow.com/dataset/your-dataset/upload?\
api_key=$ROBOFLOW_API_KEY&\
name=YOUR_IMAGE.jpg&\
split=train&\
batch=BATCH_NAME_FOR_UPLOAD"
```

Uploading an image hosted on the web via its URL (don't forget to [URL encode it](https://www.urlencoder.org/)):

```bash
curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?\
api_key=$ROBOFLOW_API_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](https://curl.se/windows/) and [GNU's base64 tool for Windows](http://gnuwin32.sourceforge.net/packages/coreutils.htm). The easiest way to do this is to use the [git for Windows installer](https://git-scm.com/downloads) 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.
{% endtab %}

{% tab title="JavaScript" %}

#### Node.js

We're using [axios](https://github.com/axios/axios) and [form-data](https://github.com/form-data/form-data) to perform the POST request in this example so first run `npm install axios form-data` to install the dependency.

#### **Uploading with multipart/form-data (recommended):**

```javascript
const axios = require("axios");
const fs = require("fs");
const FormData = require('form-data');

const formData = new FormData();
formData.append("name", "YOUR_IMAGE.jpg");
formData.append("file", fs.createReadStream("YOUR_IMAGE.jpg"));
formData.append("split", "train");

axios({
    method: "POST",
    url: "https://api.roboflow.com/dataset/YOUR_DATASET_NAME/upload",
    params: {
        api_key: "YOUR_API_KEY"
    },
    data: formData,
    headers: formData.getHeaders()
})
.then(function(response) {
    console.log(response.data);
})
.catch(function(error) {
    console.log(error.message);
});
```

#### **Uploading with base64 encoded image (not recommended):**

```javascript
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_NAME/upload",
    params: {
        api_key: "YOUR_API_KEY",
        name: "YOUR_IMAGE.jpg",
        split: "train",
        batch: "YOUR_BATCH_NAME"
    },
    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**

```javascript
const axios = require("axios");

axios({
    method: "POST",
    url: "https://api.roboflow.com/dataset/YOUR_DATASET_NAME/upload",
    params: {
        api_key: "YOUR_API_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](https://roboflow.com/contact).
{% endtab %}

{% tab title="Swift" %}

#### Swift

An example upload snippet using Swift for developing on iOS.

```swift
//Upload an image to a provided project
public func uploadImage(image: UIImage, project: String, completion: @escaping (UploadResult)->()) {
    let encodedImage = convertImageToBase64String(img: image)
    let uuid = UUID().uuidString
    
    var request = URLRequest(url: URL(string: "https://api.roboflow.com/dataset/\(project)/upload?api_key=\(apiKey!)&name=\(uuid)&split=train")!,timeoutInterval: Double.infinity)

    request.addValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
    request.httpMethod = "POST"
    request.httpBody = encodedImage.toData()
    
    URLSession.shared.dataTask(with: request) { data, response, error in
        // Parse Response to String
        guard let data = data else {
            completion(UploadResult.Error)
            return
        }

        do {
            let dict = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]
            let duplicate = dict!["duplicate"] as? Bool
            
            if duplicate ==  true {
                completion(UploadResult.Duplicate)
            } else {
                let success = dict!["success"] as! Bool
                if success == true {
                    completion(UploadResult.Success)
                } else {
                    completion(UploadResult.Error)
                }
            }

        } catch {
            print(error.localizedDescription)
            completion(UploadResult.Error)
        }
    }.resume()
}

func convertImageToBase64String (img: UIImage) -> String {
    return img.jpegData(compressionQuality: 1)?.base64EncodedString() ?? ""
}
```

}
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Android & Java" %}

#### Kotlin

#### **Uploading with base64 encoded image:**

```kotlin
import java.io.*
import java.net.HttpURLConnection
import java.net.URL
import java.nio.charset.StandardCharsets
import java.util.*

fun main() {
    // Get Image Path
    val filePath = System.getProperty("user.dir") + System.getProperty("file.separator") + "YOUR_IMAGE.jpg"
    val file = File(filePath)

    // Base 64 Encode
    val encodedFile: String
    val fileInputStreamReader = FileInputStream(file)
    val bytes = ByteArray(file.length().toInt())
    fileInputStreamReader.read(bytes)
    encodedFile = String(Base64.getEncoder().encode(bytes), StandardCharsets.US_ASCII)
    val API_KEY = "" // Your API Key
    val DATASET_NAME = "your-dataset" // Set Dataset Name (Found in Dataset URL)

    // Construct the URL
    val uploadURL = "https://api.roboflow.com/dataset/" +
            DATASET_NAME + "/upload" +
            "?api_key=" + API_KEY +
            "&name=YOUR_IMAGE.jpg" +
            "&split=train"

    // Http Request
    var connection: HttpURLConnection? = null
    try {
        // Configure connection to URL
        val url = URL(uploadURL)
        connection = url.openConnection() as HttpURLConnection
        connection.requestMethod = "POST"
        connection.setRequestProperty("Content-Type",
                "application/x-www-form-urlencoded")
        connection.setRequestProperty("Content-Length",
                Integer.toString(encodedFile.toByteArray().size))
        connection.setRequestProperty("Content-Language", "en-US")
        connection.useCaches = false
        connection.doOutput = true

        //Send request
        val wr = DataOutputStream(
                connection.outputStream)
        wr.writeBytes(encodedFile)
        wr.close()

        // Get Response
        val stream = connection.inputStream
        val reader = BufferedReader(InputStreamReader(stream))
        var line: String?
        while (reader.readLine().also { line = it } != null) {
            println(line)
        }
        reader.close()
    } catch (e: Exception) {
        e.printStackTrace()
    } finally {
        connection?.disconnect()
    }
}
main()
```

**Adding an Image Hosted Elsewhere via URL:**

```kotlin
import java.io.BufferedReader
import java.io.DataOutputStream
import java.io.InputStreamReader
import java.net.HttpURLConnection
import java.net.URL
import java.net.URLEncoder
import java.nio.charset.StandardCharsets

fun main() {
    val imageURL = "https://i.imgur.com/PEEvqPN.png" // Replace Image URL
    val API_KEY = "" // Your API Key
    val DATASET_NAME = "your-dataset" // Set Dataset Name (Found in Dataset URL)

    // Upload URL
    val uploadURL = ("https://api.roboflow.com/dataset/" + DATASET_NAME + "/upload" + "?api_key=" + API_KEY
            + "&name=YOUR_IMAGE.jpg" + "&split=train" + "&image="
            + URLEncoder.encode(imageURL, "utf-8"))

    // Http Request
    var connection: HttpURLConnection? = null
    try {
        // Configure connection to URL
        val url = URL(uploadURL)
        connection = url.openConnection() as HttpURLConnection
        connection.requestMethod = "POST"
        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded")
        connection.setRequestProperty("Content-Length", Integer.toString(uploadURL.toByteArray().size))
        connection.setRequestProperty("Content-Language", "en-US")
        connection.useCaches = false
        connection.doOutput = true

        // Send request
        val wr = DataOutputStream(connection.outputStream)
        wr.writeBytes(uploadURL)
        wr.close()

        // Get Response
        val stream = connection.inputStream
        val reader = BufferedReader(InputStreamReader(stream))
        var line: String?
        while (reader.readLine().also { line = it } != null) {
            println(line)
        }
        reader.close()
    } catch (e: Exception) {
        e.printStackTrace()
    } finally {
        connection?.disconnect()
    }
}

main()
```

#### Android (Java)

#### **Uploading with base64 encoded image:**

```java
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class UploadLocal {
    public static void main(String[] args) throws IOException {
        // Get Image Path
        String filePath = System.getProperty("user.dir") + System.getProperty("file.separator") + "YOUR_IMAGE.jpg";
        File file = new File(filePath);

        // Base 64 Encode
        String encodedFile;
        FileInputStream fileInputStreamReader = new FileInputStream(file);
        byte[] bytes = new byte[(int) file.length()];
        fileInputStreamReader.read(bytes);
        encodedFile = new String(Base64.getEncoder().encode(bytes), StandardCharsets.US_ASCII);

        String API_KEY = ""; // Your API Key
        String DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

        // Construct the URL
        String uploadURL =
                "https://api.roboflow.com/dataset/"+
                        DATASET_NAME + "/upload" +
                        "?api_key=" + API_KEY +
                        "&name=YOUR_IMAGE.jpg" +
                        "&split=train";

        // Http Request
        HttpURLConnection connection = null;
        try {
            //Configure connection to URL
            URL url = new URL(uploadURL);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type",
                    "application/x-www-form-urlencoded");

            connection.setRequestProperty("Content-Length",
                    Integer.toString(encodedFile.getBytes().length));
            connection.setRequestProperty("Content-Language", "en-US");
            connection.setUseCaches(false);
            connection.setDoOutput(true);

            //Send request
            DataOutputStream wr = new DataOutputStream(
                    connection.getOutputStream());
            wr.writeBytes(encodedFile);
            wr.close();

            // Get Response
            InputStream stream = connection.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
            reader.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}
```

**Adding an Image Hosted Elsewhere via URL:**

```java
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class UploadHosted {
    public static void main(String[] args) {
        String imageURL = "https://i.imgur.com/PEEvqPN.png"; // Replace Image URL
        String API_KEY = ""; // Your API Key
        String DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

        // Upload URL
        String uploadURL = "https://api.roboflow.com/dataset/" + DATASET_NAME + "/upload" + "?api_key=" + API_KEY
                + "&name=YOUR_IMAGE.jpg" + "&split=train" + "&image="
                + URLEncoder.encode(imageURL, StandardCharsets.UTF_8);

        // Http Request
        HttpURLConnection connection = null;
        try {
            // Configure connection to URL
            URL url = new URL(uploadURL);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

            connection.setRequestProperty("Content-Length", Integer.toString(uploadURL.getBytes().length));
            connection.setRequestProperty("Content-Language", "en-US");
            connection.setUseCaches(false);
            connection.setDoOutput(true);

            // Send request
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(uploadURL);
            wr.close();

            // Get Response
            InputStream stream = connection.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
            reader.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

#### **Ruby**

{% code title="Gemfile" %}

```ruby
source "https://rubygems.org"

gem "httparty", "~> 0.18.1"
gem "base64", "~> 0.1.0"
gem "cgi", "~> 0.2.1"
```

{% endcode %}

{% code title="Gemfile.lock" %}

```ruby
GEM
  remote: https://rubygems.org/
  specs:
    base64 (0.1.0)
    cgi (0.2.1)
    httparty (0.18.1)
      mime-types (~> 3.0)
      multi_xml (>= 0.5.2)
    mime-types (3.3.1)
      mime-types-data (~> 3.2015)
    mime-types-data (3.2021.0225)
    multi_xml (0.6.0)

PLATFORMS
  x64-mingw32
  x86_64-linux

DEPENDENCIES
  base64 (~> 0.1.0)
  cgi (~> 0.2.1)
  httparty (~> 0.18.1)

BUNDLED WITH
   2.2.15
```

{% endcode %}

#### **Uploading with base64 encoded image:**

```ruby
require 'base64'
require 'httparty'

encoded = Base64.encode64(File.open("YOUR_IMAGE.jpg", "rb").read)
dataset_name = "your-dataset" # Set Dataset Name (Found in Dataset URL)
api_key = "" # Your API KEY Here

params = "?api_key=" + api_key + 
"&name=YOUR_IMAGE.jpg" + 
"&split=train"

response = HTTParty.post(
    "https://api.roboflow.com/dataset/" + dataset_name + "/upload" + params,
    body: encoded, 
    headers: {
    'Content-Type' => 'application/x-www-form-urlencoded',
    'charset' => 'utf-8'
  })

  puts response

 
```

**Adding an Image Hosted Elsewhere via URL:**

```ruby
require 'httparty'
require 'cgi'

dataset_name = "your-dataset" # Set Dataset Name (Found in Dataset URL)
api_key = "" # Your API KEY Here
img_url = "https://i.imgur.com/PEEvqPN.png" # Construct the URL

img_url = CGI::escape(img_url)

params = "?api_key=" + api_key + 
"&name=YOUR_IMAGE.jpg" + 
"&split=train" +
"&image=" + img_url

response = HTTParty.post(
    "https://api.roboflow.com/dataset/" + dataset_name + "/upload" + params,
    headers: {
    'Content-Type' => 'application/x-www-form-urlencoded',
    'charset' => 'utf-8'
  })

puts response
```

{% endtab %}

{% tab title="PHP" %}

#### **PHP**

#### **Uploading with base64 encoded image:**

```php
<?php

// Base 64 Encode Image
$data = base64_encode(file_get_contents("YOUR_IMAGE.jpg"));

$api_key = ""; // Set API Key
$dataset_name = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

// URL for Http Request
$url = "https://api.roboflow.com/dataset/" 
. $dataset_name .  "/upload" 
.  "?api_key="  .  $api_key  
.  "&name=YOUR_IMAGE.jpg" 
. "&split=train";

// Setup + Send Http request
$options = array(
  'http' => array (
    'header' => "Content-type: application/x-www-form-urlencoded\r\n",
    'method'  => 'POST',
    'content' => $data
  ));

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
?>
```

**Adding an Image Hosted Elsewhere via URL:**

```php
<?php

$api_key = ""; // Set API Key
$dataset_name = "your-dataset"; // Set Dataset Name (Found in Dataset URL)
$img_url = "https://i.imgur.com/PEEvqPN.png";

// URL for Http Request
$url = "https://api.roboflow.com/dataset/" 
. $dataset_name .  "/upload" 
.  "?api_key="  .  $api_key  
.  "&name=YOUR_IMAGE.jpg" 
. "&split=train" 
. "&image=" . urlencode($img_url);

// Setup + Send Http request
$options = array(
  'http' => array (
    'header' => "Content-type: application/x-www-form-urlencoded\r\n",
    'method'  => 'POST'
  ));

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
?>
```

{% endtab %}

{% tab title="Go" %}

#### **Go**

#### **Uploading with base64 encoded image:**

```go
package main

import (
    "bufio"
    "encoding/base64"
    "fmt"
    "io/ioutil"
    "os"
	"net/http"
	"strings"
)

func main() {
	api_key := ""  // Your API Key
	dataset_name := "Your-Dataset" // Set Dataset Name (Found in Dataset URL)

    // Open file on disk.
    f, _ := os.Open("YOUR_IMAGE.jpg")

    // Read entire JPG into byte slice.
    reader := bufio.NewReader(f)
    content, _ := ioutil.ReadAll(reader)

    // Encode as base64.
    data := base64.StdEncoding.EncodeToString(content)
	uploadURL := "https://api.roboflow.com/dataset/"+ dataset_name + "/upload"+
    "?api_key=" + api_key +
    "&name=YOUR_IMAGE.jpg" +
    "&split=train"

	res, _ := http.Post(uploadURL, "application/x-www-form-urlencoded", strings.NewReader(data))
    body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(string(body))

}
```

**Adding an Image Hosted Elsewhere via URL:**

```go
package main

import (
    "fmt"
	"net/http"
	"net/url"
	"io/ioutil"

)

func main() {
	api_key := ""  // Your API Key
	dataset_name := "Your-Dataset" // Set Dataset Name (Found in Dataset URL)
	img_url := "https://i.imgur.com/PEEvqPN.png"


	uploadURL := "https://api.roboflow.com/dataset/"+ dataset_name + "/upload"+
    "?api_key=" + api_key +
    "&name=YOUR_IMAGE.jpg" +
    "&split=train" + "&image=" + url.QueryEscape(img_url)

	res, _ := http.Post(uploadURL, "application/x-www-form-urlencoded", nil)
	body, _ := ioutil.ReadAll(res.Body)
    fmt.Println(string(body))


}
```

{% endtab %}

{% tab title=".NET" %}

#### **.NET**

#### **Uploading with base64 encoded image:**

```csharp
using System;
using System.IO;
using System.Net;
using System.Text;

namespace UploadLocal
{
    class UploadLocal
    {

        static void Main(string[] args)
        {
            byte[] imageArray = System.IO.File.ReadAllBytes(@"YOUR_IMAGE.jpg");
            string encoded = Convert.ToBase64String(imageArray);
            byte[] data = Encoding.ASCII.GetBytes(encoded);
            string API_KEY = ""; // Your API Key
            string DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

            // Construct the URL
            string uploadURL =
                    "https://api.roboflow.com/dataset/" +
                            DATASET_NAME + "/upload" +
                            "?api_key=" + API_KEY +
                            "&name=YOUR_IMAGE.jpg" +
                            "&split=train";

            // Service Request Config
            ServicePointManager.Expect100Continue = true;
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

            // Configure Request
            WebRequest request = WebRequest.Create(uploadURL);
            request.Method = "POST";
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = data.Length;

            // Write Data
            using (Stream stream = request.GetRequestStream())
            {
                stream.Write(data, 0, data.Length);
            }

            // Get Response
            string responseContent = null;
            using (WebResponse response = request.GetResponse())
            {
                using (Stream stream = response.GetResponseStream())
                {
                    using (StreamReader sr99 = new StreamReader(stream))
                    {
                        responseContent = sr99.ReadToEnd();
                    }
                }
            }

            Console.WriteLine(responseContent);

        }
    }
}
```

**Adding an Image Hosted Elsewhere via URL:**

```csharp
using System;
using System.IO;
using System.Net;
using System.Web;

namespace UploadHosted
{
    class UploadHosted
    {
        static void Main(string[] args)
        {
            string API_KEY = ""; // Your API Key
            string DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)
            string imageURL = "https://i.imgur.com/PEEvqPN.png";
            imageURL = HttpUtility.UrlEncode(imageURL);

            // Construct the URL
            string uploadURL =
                    "https://api.roboflow.com/dataset/" +
                            DATASET_NAME + "/upload" +
                            "?api_key=" + API_KEY +
                            "&name=YOUR_IMAGE.jpg" +
                            "&split=train" +
                            "&image=" + imageURL;

            // Service Point Config
            ServicePointManager.Expect100Continue = true;
            ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

            // Configure Http Request
            WebRequest request = WebRequest.Create(uploadURL);
            request.Method = "POST";
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = 0;

            // Get Response
            string responseContent = null;
            using (WebResponse response = request.GetResponse())
            {
                using (Stream stream = response.GetResponseStream())
                {
                    using (StreamReader sr99 = new StreamReader(stream))
                    {
                        responseContent = sr99.ReadToEnd();
                    }
                }
            }

            Console.WriteLine(responseContent);

        }
    }
}
```

{% endtab %}
{% endtabs %}

#### View Uploaded Images in Roboflow

Images uploaded via the API can be found in the `Annotate` tab, under the `unassigned` column and marked as `uploaded via API`.

If you specify a `batch` upload parameter, your image will still be found in the `Annotate` tab but instead of going to the `uploaded via API` batch it will be found in the batch you specified.

### Upload a Dataset Zip

Upload a dataset as a single zip archive (up to 2 GB, 10,000 files) using an async task. Unlike the standard image upload endpoint, you do not hold an HTTP connection open while the zip is processed. The API returns a signed URL that you PUT the zip to, and a `taskId` you poll for status.

This endpoint accepts zips containing images and annotations in any of the formats supported by the Roboflow dataset upload tools (COCO, YOLO, Pascal VOC, etc.). Folder names are used as class labels for classification datasets.

#### Flow

1. `POST /:workspace/:project/upload/zip` returns a signed URL and a `taskId`.
2. `PUT` the zip directly to the signed URL.
3. `GET /:workspace/upload/zip/:taskId` to poll until the task completes.

#### Initiate the Upload

Send a `POST` to `/:workspace/:project/upload/zip`. The response includes a GCS signed URL and a `taskId`.

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-project/upload/zip?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split": "train", "batchName": "my-batch"}'
```

**Body Parameters**

```
- split (string, optional) - One of train, valid, or test. Defaults to train.
- batchName (string, optional) - Group uploaded images under a batch with this name.
```

**Response**

```json
{
    "taskId": "abc123",
    "signedUrl": "https://storage.googleapis.com/...",
    "url": "https://api.roboflow.com/my-workspace/upload/zip/abc123"
}
```

#### Upload the Zip

`PUT` the zip file to the returned `signedUrl`. The Content-Type must be `application/zip`.

```bash
curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: application/zip" \
  --upload-file ./my-dataset.zip
```

Processing starts automatically once the upload completes.

#### Poll Task Status

Send a `GET` to `/:workspace/upload/zip/:taskId`.

```bash
curl "https://api.roboflow.com/my-workspace/upload/zip/abc123?api_key=$ROBOFLOW_API_KEY"
```

The response follows the standard [Async Tasks](https://docs.roboflow.com/reference/rest-api/rest-api/async-tasks) shape. When the task completes, `result` includes a per-image summary plus any warnings or errors encountered during parsing.

```json
{
    "taskId": "abc123",
    "status": "completed",
    "progress": { "current": 250, "total": 250 },
    "result": {
        "uploaded": 248,
        "failed": 2,
        "warnings": [],
        "errors": []
    }
}
```

Up to 100 per-image errors and 100 warnings are reported. Videos and PDFs inside the zip are surfaced as unsupported-format warnings and skipped.

#### Limits

* Maximum zip size: 2 GB
* Maximum files per zip: 10,000

#### Errors

```
- 400 - The zip is malformed or exceeds the size or file count limits.
- 401 - Missing or invalid API key.
- 404 - The workspace, project, or task does not exist, or belongs to another workspace.
```

### Upload an Annotation

If you already have existing annotations, along with your images, you can upload them to Roboflow.

{% hint style="success" %}
This works with any of [our supported annotation formats](http://roboflow.com/formats) that use an annotation file that references the file name of the uploaded image.
{% endhint %}

{% hint style="info" %}
Did you know? You can drag and drop (or select) the annotation files along with your images on the Upload page of the app without using the API.
{% endhint %}

{% tabs %}
{% tab title="Python SDK" %}
You can attach annotation files when you upload images via the Python SDK. [See more in the Python SDK reference](https://roboflow.github.io/roboflow-python/core/project/#roboflow.core.project.Project.upload)

#### Example: Uploading a Local Annotation

```python
import glob
from roboflow import Roboflow

# Initialize Roboflow client
rf = Roboflow(api_key="YOUR_API_KEY")

# Directory path and file extension for images
dir_name = "PATH/TO/IMAGES"
file_extension_type = ".jpg"

# Annotation file path and format (e.g., .coco.json)
annotation_filename = "PATH/TO/_annotations.coco.json"

# Get the upload project from Roboflow workspace
project = rf.workspace().project("YOUR_PROJECT_NAME")

# Upload images
image_glob = glob.glob(dir_name + '/*' + file_extension_type)
for image_path in image_glob:
    print(project.single_upload(
        image_path=image_path,
        annotation_path=annotation_filename,
        # -- optional parameters: --
        # annotation_labelmap=labelmap_path,
        # split='train',
        # num_retry_uploads=0,
        # batch_name='batch_name',
        # tag_names=['tag1', 'tag2'],
        # is_prediction=False,
    ))

```

{% endtab %}

{% tab title="cURL" %}

#### Example

Attaching a [VOC XML annotation](https://roboflow.com/formats/pascal-voc-xml) to an image with ID `abc123` in the `your-dataset` dataset called `YOUR_ANNOTATION.xml`:

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

Attaching a [Darknet TXT annotation](https://roboflow.com/formats/yolo-darknet-txt) to an image with ID `abc123` in the `your-dataset` dataset called `YOUR_ANNOTATION.txt` using a json labelmap - in this case we need to send the contents of the annotation file in a json instead of just sending it as the body.

```bash
#!/bin/bash
# store the annotation as a json-compatible string
txt_content=$(cat YOUR_ANNOTATION.txt | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/' | tr -d '\n')
# create a json string with the annotation file and the label map [0=flower, 1=leaf]
json_payload="{ \"annotationFile\": \"$txt_content\", \"labelmap\":{\"0\":\"flower\", \"1\":\"leaf\"} }"

# upload the annotation + labelmap
echo $json_payload | curl -H "Content-Type: application/json" -d @- \
"https://api.roboflow.com/dataset/cultura-pepino-dark/annotate/abc123?\
api_key=YOUR_KEY&\
name=YOUR_ANNOTATION.txt"
```

{% endtab %}

{% tab title="JavaScript" %}
We're using [axios](https://github.com/axios/axios) to perform the POST request in this example so first run `npm install axios` to install the dependency.

**Uploading a Local Image**

```javascript
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);
});
```

{% endtab %}

{% tab title="Android and Java" %}

#### Kotlin

#### **Uploading with base64 encoded image:**

```kotlin
import java.io.*
import java.net.HttpURLConnection
import java.net.URL
import java.nio.charset.StandardCharsets
import java.util.*

fun main() {
    // Get Image Path
    val filePath = System.getProperty("user.dir") + System.getProperty("file.separator") + "YOUR_IMAGE.jpg"
    val file = File(filePath)

    // Base 64 Encode
    val encodedFile: String
    val fileInputStreamReader = FileInputStream(file)
    val bytes = ByteArray(file.length().toInt())
    fileInputStreamReader.read(bytes)
    encodedFile = String(Base64.getEncoder().encode(bytes), StandardCharsets.US_ASCII)
    val API_KEY = "" // Your API Key
    val DATASET_NAME = "your-dataset" // Set Dataset Name (Found in Dataset URL)

    // Construct the URL
    val uploadURL = "https://api.roboflow.com/dataset/" +
            DATASET_NAME + "/upload" +
            "?api_key=" + API_KEY +
            "&name=YOUR_IMAGE.jpg" +
            "&split=train"

    // Http Request
    var connection: HttpURLConnection? = null
    try {
        // Configure connection to URL
        val url = URL(uploadURL)
        connection = url.openConnection() as HttpURLConnection
        connection.requestMethod = "POST"
        connection.setRequestProperty("Content-Type",
                "application/x-www-form-urlencoded")
        connection.setRequestProperty("Content-Length",
                Integer.toString(encodedFile.toByteArray().size))
        connection.setRequestProperty("Content-Language", "en-US")
        connection.useCaches = false
        connection.doOutput = true

        //Send request
        val wr = DataOutputStream(
                connection.outputStream)
        wr.writeBytes(encodedFile)
        wr.close()

        // Get Response
        val stream = connection.inputStream
        val reader = BufferedReader(InputStreamReader(stream))
        var line: String?
        while (reader.readLine().also { line = it } != null) {
            println(line)
        }
        reader.close()
    } catch (e: Exception) {
        e.printStackTrace()
    } finally {
        connection?.disconnect()
    }
}
main()
```

**Adding an Image Hosted Elsewhere via URL:**

```kotlin
import java.io.BufferedReader
import java.io.DataOutputStream
import java.io.InputStreamReader
import java.net.HttpURLConnection
import java.net.URL
import java.net.URLEncoder
import java.nio.charset.StandardCharsets

fun main() {
    val imageURL = "https://i.imgur.com/PEEvqPN.png" // Replace Image URL
    val API_KEY = "" // Your API Key
    val DATASET_NAME = "your-dataset" // Set Dataset Name (Found in Dataset URL)

    // Upload URL
    val uploadURL = ("https://api.roboflow.com/dataset/" + DATASET_NAME + "/upload" + "?api_key=" + API_KEY
            + "&name=YOUR_IMAGE.jpg" + "&split=train" + "&image="
            + URLEncoder.encode(imageURL, "utf-8"))

    // Http Request
    var connection: HttpURLConnection? = null
    try {
        // Configure connection to URL
        val url = URL(uploadURL)
        connection = url.openConnection() as HttpURLConnection
        connection.requestMethod = "POST"
        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded")
        connection.setRequestProperty("Content-Length", Integer.toString(uploadURL.toByteArray().size))
        connection.setRequestProperty("Content-Language", "en-US")
        connection.useCaches = false
        connection.doOutput = true

        // Send request
        val wr = DataOutputStream(connection.outputStream)
        wr.writeBytes(uploadURL)
        wr.close()

        // Get Response
        val stream = connection.inputStream
        val reader = BufferedReader(InputStreamReader(stream))
        var line: String?
        while (reader.readLine().also { line = it } != null) {
            println(line)
        }
        reader.close()
    } catch (e: Exception) {
        e.printStackTrace()
    } finally {
        connection?.disconnect()
    }
}

main()
```

#### Android (Java)

#### **Uploading with base64 encoded image:**

```java
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class UploadLocal {
    public static void main(String[] args) throws IOException {
        // Get Image Path
        String filePath = System.getProperty("user.dir") + System.getProperty("file.separator") + "YOUR_IMAGE.jpg";
        File file = new File(filePath);

        // Base 64 Encode
        String encodedFile;
        FileInputStream fileInputStreamReader = new FileInputStream(file);
        byte[] bytes = new byte[(int) file.length()];
        fileInputStreamReader.read(bytes);
        encodedFile = new String(Base64.getEncoder().encode(bytes), StandardCharsets.US_ASCII);

        String API_KEY = ""; // Your API Key
        String DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

        // Construct the URL
        String uploadURL =
                "https://api.roboflow.com/dataset/"+
                        DATASET_NAME + "/upload" +
                        "?api_key=" + API_KEY +
                        "&name=YOUR_IMAGE.jpg" +
                        "&split=train";

        // Http Request
        HttpURLConnection connection = null;
        try {
            //Configure connection to URL
            URL url = new URL(uploadURL);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type",
                    "application/x-www-form-urlencoded");

            connection.setRequestProperty("Content-Length",
                    Integer.toString(encodedFile.getBytes().length));
            connection.setRequestProperty("Content-Language", "en-US");
            connection.setUseCaches(false);
            connection.setDoOutput(true);

            //Send request
            DataOutputStream wr = new DataOutputStream(
                    connection.getOutputStream());
            wr.writeBytes(encodedFile);
            wr.close();

            // Get Response
            InputStream stream = connection.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
            reader.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}
```

**Adding an Image Hosted Elsewhere via URL:**

```java
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class UploadHosted {
    public static void main(String[] args) {
        String imageURL = "https://i.imgur.com/PEEvqPN.png"; // Replace Image URL
        String API_KEY = ""; // Your API Key
        String DATASET_NAME = "your-dataset"; // Set Dataset Name (Found in Dataset URL)

        // Upload URL
        String uploadURL = "https://api.roboflow.com/dataset/" + DATASET_NAME + "/upload" + "?api_key=" + API_KEY
                + "&name=YOUR_IMAGE.jpg" + "&split=train" + "&image="
                + URLEncoder.encode(imageURL, StandardCharsets.UTF_8);

        // Http Request
        HttpURLConnection connection = null;
        try {
            // Configure connection to URL
            URL url = new URL(uploadURL);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

            connection.setRequestProperty("Content-Length", Integer.toString(uploadURL.getBytes().length));
            connection.setRequestProperty("Content-Language", "en-US");
            connection.setUseCaches(false);
            connection.setDoOutput(true);

            // Send request
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeBytes(uploadURL);
            wr.close();

            // Get Response
            InputStream stream = connection.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println(line);
            }
            reader.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}

### Get Details About an Image

You can fetch details of a specific image using the REST API.

To fetch details of a specific image, make a GET request to the following API endpoint.

```url
https://api.roboflow.com/:workspace/:project/images/:image_id
```

Here is an example request to the API to fetch the details of an image

```bash
curl -X GET "https://api.roboflow.com/my-workspace/my-project-name/images/image-id?api_key=$ROBOFLOW_API_KEY" \
-H 'Content-Type: application/json'
```

This endpoint returns a JSON object containing the following information about the image:

```typescript
{
    "image":
        "id": string,
        "name": string,
        "annotation": {
            "key": string,
            "width": number,
            "height": number,
            "boxes": Array<{
                "label": string,
                "x": number,
                "y": number,
                "width": number,
                "height": number
            }>
        },
        "labels": string[],
        "split": string,
        "tags": string[],
        "created": number,
        "urls": {
            "original": string,
            "thumb": string,
            "annotation": string
        },
        "embedding": number[]
    }
}
```

### Delete an Image from a Dataset

You can remove images from a Dataset using the REST API.

{% tabs %}
{% tab title="REST API" %}
To remove images from a Dataset, make a DELETE request to the following API endpoint, passing the image IDs in the endpoint.

```url
https://api.roboflow.com/:workspace/:project/images
```

Here is an example request to the API to remove images

```bash
curl "https://api.roboflow.com/my-workspace/my-project/images?api_key=$ROBOFLOW_API_KEY" \
  -X DELETE \
  -H "Content-Type: application/json" \
  -d '{"images": ["1", "2"]}'
```

This endpoint returns a 204 status if the operation was successful.
{% endtab %}
{% endtabs %}

### List, Add, and Remove Image Tags

You can assign tags to specific images on Roboflow using the REST API

{% tabs %}
{% tab title="REST API" %}
To add, remove, and set tags to images hosted on Roboflow, make POST request to the following API endpoint. Use the Search API to retrieve the image ID associated with the image name:

```url
https://api.roboflow.com/:workspace/:project/images/:image_id/tags
```

Here is an example request to the API (can "add", "remove", or "set" a tag):

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-project-name/images/image-id/tags?api_key=$ROBOFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--data \
'{
    "operation": "add",
    "tags": "image_tag_test"
}'
```

This endpoint accepts the following values in the POST body:

```json
{
     // // options are ["add", "remove", "set"]
     "operation": string,
     
     // array of strings of the tags
     "tags": string[],
     
}
```

The API will add the tag to the specified image in Roboflow (remember to pass in the image ID to the post request and not the image name).
{% endtab %}
{% endtabs %}

### Update Image Metadata and Tags

You can write custom metadata and tags to images in your workspace using the REST API. There are two endpoints: one for updating a single image synchronously, and one for updating up to 1,000 images in a batch.

Both endpoints require an API key with the `image:tag` scope.

#### Request Body

Both endpoints accept the same fields (the batch endpoint wraps them in an `updates` array):

```
- imageId (string) - required for batch update in body, inferred ffrom the path in single update
- metadata (object) - Key-value pairs to set on the image's user metadata.
- removeMetadata (string[]) - Metadata keys to delete from the image.
- addTags (string[]) - Tags to add to the image.
- removeTags (string[]) - Tags to remove from the image.
```

You must include at least one of these fields. You cannot set and remove the same metadata key or tag in the same request.

#### Single Image

Update metadata and tags for a single image.

```
POST https://api.roboflow.com/:workspace/images/:image/metadata?api_key=YOUR_API_KEY
```

**Example**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/images/abc123/metadata?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "camera": "front", "blur_score": 0.8 },
    "addTags": ["reviewed"]
  }'
```

**Response**

```json
{
    "success": true
}
```

#### Batch Update

Update metadata and tags for multiple images asynchronously. Accepts up to 1,000 images per request.

```
POST https://api.roboflow.com/:workspace/images/metadata?api_key=YOUR_API_KEY
```

**Example**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/images/metadata?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "imageId": "abc123",
        "metadata": { "camera": "front" },
        "addTags": ["reviewed"]
      },
      {
        "imageId": "def456",
        "removeTags": ["needs-review"]
      }
    ]
  }'
```

**Response**

Returns `202` with a task ID. Poll the task URL to check progress.

```json
{
    "taskId": "task-id-here",
    "url": "https://api.roboflow.com/my-workspace/asynctasks/task-id-here"
}
```

See [Async Tasks](https://docs.roboflow.com/reference/rest-api/rest-api/async-tasks) for how to poll the task status.

#### Errors

```
- 400 - Empty body, malformed field types, or conflicting fields (e.g. same key in both metadata and removeMetadata).
- 404 - Image not found in the workspace (single image endpoint only).
```

## Python SDK

`Project` exposes the per-image operations that complement the bulk [`upload_dataset`](/datasets/create-and-upload/upload-a-dataset.md#python-sdk) flow. Use these when you need finer control over single-image uploads, want to attach annotations after the fact, or are ingesting images one-at-a-time from a stream.

### Upload an image (with optional annotation)

`Project.upload()` is the high-level "do the right thing" helper. It accepts a single image plus an optional matching annotation file and ships both to the project in one call.

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

result = project.upload(
    image_path="./photo.jpg",
    annotation_path="./photo.xml",   # optional; matched VOC / COCO / etc. annotation
    split="train",                    # train | valid | test
    batch_name="ingest-2026-05",     # optional; groups uploads in the web UI
    tag_names=["camera-A", "indoor"], # optional; apply tags
    is_prediction=False,              # set True for model-generated annotations awaiting review
    num_retry_uploads=2,              # retries on transient upload failures
)
print(result)
```

`single_upload()` is a lower-level variant that takes the same arguments and returns the raw API responses for both the image and (if provided) the annotation.

### Upload an image only

```python
project.upload_image(
    image_path="./photo.jpg",
    split="train",
    batch_name="ingest-2026-05",
    tag_names=["camera-A"],
)
```

Useful when annotations don't exist yet and the image goes straight to a labeler.

### Validate an image before uploading

`check_valid_image()` runs Roboflow's local size / format checks without hitting the API:

```python
if project.check_valid_image("./photo.jpg"):
    project.upload_image("./photo.jpg")
```

### Attach an annotation to an existing image

`save_annotation()` posts an annotation against an image that's already in the project. Useful for adding labels created elsewhere, or for promoting a model prediction to ground truth.

```python
project.save_annotation(
    image_id="<image-id>",
    annotation_path="./photo.xml",
    is_prediction=False,
    annotation_overwrite=True,    # replace any existing annotation
)
```

Pass `annotation_labelmap="./labelmap.yaml"` to map class indices into class names if your annotation format requires it.

### Fetch an image's metadata

```python
info = project.image("<image-id>")
print(info["name"], info["split"], info["annotations"])
```

Returns image metadata, current split, and annotation status.

### Delete images

Project-level (only deletes images that belong to this project):

```python
project.delete_images(["<image-id-1>", "<image-id-2>"])
```

Workspace-level (removes images regardless of which projects reference them - use with care):

```python
workspace.delete_images(["<image-id-1>", "<image-id-2>"])
```

### A note on uploads in v1.3.6+

As of `roboflow` 1.3.6, the SDK uploads the original image bytes rather than re-encoding via Pillow. This restores parity with the web uploader and lets the Roboflow server deduplicate uploads by SHA-256. If you have automation that uploads the same image twice (e.g. to add it to multiple batches), you'll see the second upload succeed without consuming additional storage credits.

### REST and CLI equivalents

* REST: see the [HTTP API](#http-api) section above (upload, get, tag, delete) and [Upload an Annotation](#upload-an-annotation).
* CLI: see the `roboflow image` command group, e.g. [Upload a Dataset (CLI)](/datasets/create-and-upload/upload-a-dataset.md#cli).