Upload a Vision Event Image

About

This endpoint uploads an image to your workspace for use in Vision Events. The upload is workspace-level and is not tied to any project; the returned sourceId can then be referenced in the images array when you create an event. Use it to attach the original or output frames a model processed so they are viewable alongside the event.

HTTP API

Upload an image for use in vision events. This is a workspace-level upload that is not associated with any specific project. The returned sourceId can be referenced in the images array when creating events.

Required scope: vision-events:write or device:update

POST /vision-events/upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: application/json

{
  "file": "binary",
  "name": "text",
  "metadata": "text"
}

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events/upload' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Accept: application/json' \
  --data '{
  "file": "binary",
  "name": "text",
  "metadata": "text"
}'

const response = await fetch("https://api.roboflow.com/vision-events/upload", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "file": "binary",
    "name": "text",
    "metadata": "text"
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/upload"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json"
}
payload = {
  "file": "binary",
  "name": "text",
  "metadata": "text"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "success": true,
  "sourceId": "text",
  "url": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

Example Request

curl -X POST "https://api.roboflow.com/vision-events/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@inspection-photo.jpg" \
  -F "name=inspection-photo.jpg"

Request Parameters

Send as multipart/form-data:

• file (binary, required): The image file to upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP, HEIC, and AVIF.
• name (string, optional): A custom name for the image.
• metadata (JSON string, optional): Custom metadata to attach to the image. Must be a valid JSON object following the same constraints as event custom metadata: max 100 keys, key names must match [a-zA-Z0-9_ -]+ (max 100 characters), string values max 1000 characters, number and boolean values are also supported. Keys that start with _rf_internal_ are reserved for Roboflow and are rejected.

Example Response

{
  "success": true,
  "sourceId": "ve-img-abc123def456",
  "url": "https://storage.roboflow.com/vision-events/images/ve-img-abc123def456.jpg"
}

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "quality_check",
  "useCaseId": "a1b3c8e1",
  "timestamp": "2024-01-15T10:30:00Z",
  "images": [
    {
      "sourceId": "ve-img-abc123def456",
      "objectDetections": [
        {
          "class": "defect",
          "x": 100,
          "y": 200,
          "width": 50,
          "height": 30,
          "confidence": 0.95
        }
      ]
    }
  ],
  "eventData": {
    "result": "fail"
  }
}

{
  "error": "No file provided"
}

{
  "error": "Insufficient permissions for this resource."
}

Python SDK

Upload a local image for use in vision events. The returned sourceId can be referenced in the images array when creating events.

import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

# Upload an image
result = ws.upload_vision_event_image("inspection-photo.jpg")
source_id = result["sourceId"]

# You can also provide an optional name and metadata
result = ws.upload_vision_event_image(
    "inspection-photo.jpg",
    name="line-a-check-001",
    metadata={"camera": "cam-1", "shift": "morning"},
)

The sourceId from the response is used in the images array when creating a vision event:

ws.write_vision_event({
    "eventId": "d4e5f6a7-b2c3-4d4e-9f6a-7b8c9d0e1f2a",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "images": [
        {
            "sourceId": source_id,
            "label": "inspection-photo",
            "objectDetections": [
                {"class": "defect", "x": 100, "y": 200, "width": 50, "height": 30, "confidence": 0.95}
            ],
        }
    ],
    "eventData": {"result": "fail"},
})

For supported image formats and metadata constraints, see the REST API reference.