A developer guide for importing attachments and image overlay layers via the Python SDK.
Supported attachment types
Below are the types of attachment data that we support in the editor.
| Type | Value | Description |
|---|---|---|
IMAGE | URL of Image (PNG/JPG) (HTTPS or IAM delegated access path) | Labelers can see the attached image(s) while labeling the primary data row |
VIDEO | URL of Video (MP4) (HTTPS or IAM delegated access path) | Labelers can see the attached video(s) while labeling the primary data row |
RAW_TEXT | Text string or hyperlink (see below for cloud-hosted text files) | Labelers can see the attached text or hyperlink while labeling the primary data row If passing a hyperlink, we will show a clickable hyperlink. If you want to display text from a URL endpoint, please use the TEXT_URL type. |
TEXT_URL | URL of a text file (HTTPS or IAM delegated access path) | Labelers can see the attached text from the linked text URL while labeling the primary data row |
HTML | URL of an HTML file (HTTPS or IAM delegated access path) | Renders HTML in an iframe as an attachment. Labelers can see and interact with the attached HTML widget while labeling the primary data row. |
IMAGE_OVERLAY | URL of the image layer (PNG/JPG) (HTTPS or IAM delegated access path). | A visualization tool designed to help you view the asset to be labeled in different ways by adding image layers over the asset. |
PDF_URL | URL of the PDF file (HTTPS or IAM delegated access path) | Labelers can see the attached document while labeling the primary data row |
When using an IAM delegated access path, the attachment must utilize the same cloud storage integration as the data row to which the asset is attached.
Import attachments
Use the following methods to import attachments to Labelbox using the Python SDK.
import labelbox
#Enter your API key
API_KEY = ""
client = labelbox.Client(api_key=API_KEY)
#create a new dataset
dataset = client.create_dataset(name="Data Row attachment example")
#create a data row with external ID
data_row = dataset.create_data_row(row_data="https://storage.googleapis.com/labelbox-sample-datasets/Docs/basic.jpg",
external_id="base_image")
#Create multiple attachments
data_row.create_attachment(attachment_type="RAW_TEXT", attachment_value="IOWA, Zone 2232, June 2022 [Text string]")
data_row.create_attachment(attachment_type="RAW_TEXT", attachment_value="https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt")
data_row.create_attachment(attachment_type="TEXT_URL", attachment_value="https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt")
data_row.create_attachment(attachment_type="IMAGE", attachment_value="https://storage.googleapis.com/labelbox-sample-datasets/Docs/disease_attachment.jpeg")
data_row.create_attachment(attachment_type="VIDEO", attachment_value="https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4")
data_row.create_attachment(attachment_type="HTML", attachment_value="https://storage.googleapis.com/labelbox-sample-datasets/Docs/windy.html")
data_row.create_attachment(attachment_type="PDF_URL", attachment_value="https://storage.googleapis.com/labelbox-datasets/arxiv-pdf/data/99-word-token-pdfs/0801.3483.pdf")
JSON format
Use the following format to include attachments in your JSON import file.
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/image-samples/sample-image-1.jpg",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/image-samples/sample-image-1.jpg",
"media_type": "IMAGE",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "RAW_TEXT",
"value": "IOWA, Zone 2232, June 2022 [Text string]"
},
{
"type": "RAW_TEXT",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
},
{
"type": "TEXT_URL",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
},
{
"type": "IMAGE",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/disease_attachment.jpeg"
},
{
"type": "VIDEO",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4"
},
{
"type": "HTML",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/windy.html"
},
{
"type": "PDF_URL",
"value": "https://storage.googleapis.com/labelbox-datasets/arxiv-pdf/data/99-word-token-pdfs/0801.3483.pdf"
}
]
}
]
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-1.mp4",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/video-samples/sample-video-1.mp4",
"media_type": "VIDEO",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "RAW_TEXT",
"value": "Some sample text"
},
{
"type": "RAW_TEXT",
"value": "Some more sample text"
}
]
}
]
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/text-samples/sample-text-1.txt",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/text-samples/sample-text-1.txt",
"media_type": "TEXT",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "RAW_TEXT",
"value": "Some sample text"
},
{
"type": "RAW_TEXT",
"value": "Some more sample text"
}
]
}
]
[
{
"row_data":{
"tile_layer_url": "https://s3-us-west-1.amazonaws.com/lb-tiler-layers/mexico_city/{z}/{x}/{y}.png",
"bounds": [
[
19.405662413477728,
-99.21052827588443
],
[
19.400498983095076,
-99.20534818927473
]
],
"min_zoom": 12,
"max_zoom": 20,
"epsg": "EPSG4326",
"alternative_layers": [
{
"tile_layer_url": "https://api.mapbox.com/styles/v1/mapbox/satellite-streets-v11/tiles/{z}/{x}/{y}?access_token=pk.eyJ1IjoibWFwYm94IiwiYSI6ImNpejY4NXVycTA2emYycXBndHRqcmZ3N3gifQ.rJcFIG214AriISLbB6B5aw",
"name": "Satellite"
},
{
"tile_layer_url": "https://api.mapbox.com/styles/v1/mapbox/navigation-guidance-night-v4/tiles/{z}/{x}/{y}?access_token=pk.eyJ1IjoibWFwYm94IiwiYSI6ImNpejY4NXVycTA2emYycXBndHRqcmZ3N3gifQ.rJcFIG214AriISLbB6B5aw",
"name": "Guidance"
}
]
},
"global_key": "https://s3-us-west-1.amazonaws.com/lb-tiler-layers/mexico_city/{z}/{x}/{y}.png",
"media_type": "TMS_GEO",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
}
]
}
]
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/audio-samples/sample-audio-1.mp3",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/audio-samples/sample-audio-1.mp3",
"media_type": "AUDIO",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "VIDEO", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4"
}
]
},
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/audio-samples/sample-audio-2.mp3",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/audio-samples/sample-audio-2.mp3",
"media_type": "AUDIO",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
}
]
}
]
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/dicom-samples/sample-dicom-1.dcm",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/dicom-samples/sample-dicom-1.dcm",
"media_type": "DICOM",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "VIDEO", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/drone_video.mp4"
}
]
},
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/dicom-samples/sample-dicom-2.dcm",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/dicom-samples/sample-dicom-2.dcm",
"media_type": "DICOM",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
}
]
}
]
[
{
"row_data": {
"pdf_url": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-1.pdf",
"text_layer_url": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-custom-text-layer.json"
},
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-1.pdf",
"media_type": "PDF",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "HTML", "value": "https://www.wikipedia.org/"
}
]
},
{
"row_data": {
"pdf_url": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-2.pdf",
"text_layer_url": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-2-custom-text-layer.json"
},
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/document-samples/sample-document-2.pdf",
"media_type": "PDF",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
}
]
}
]
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/conversation-samples/sample-conversation-1.json",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/conversation-samples/sample-conversation-1.json",
"media_type": "CONVERSATIONAL",
"metadata_fields": [{"schema_id": "cko8s9r5v0001h2dk9elqdidh", "value": "tag_string"}],
"attachments": [
{
"type": "TEXT_URL", "value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/text_attachment.txt"
}
]
}
]
Import image overlay layers
Image overlays are imported as attachments to a data row. You must include the following information for each image layer.
Image overlay limits
Only images may be attached as layers, and they may only be attached to image assets.
A maximum of 10 layers may be added per image.
| Parameter | Required | Value |
|---|---|---|
type | Yes | IMAGE_OVERLAY |
value | Yes | URL of the image layer (PNG/JPG) (HTTPS or IAM delegated access path). |
name | No | User-determined string for reference. |
For details on how to create image layers or import data rows with image layers using the Python SDK, please view the documentation here.
JSON format
If uploading a JSON file of data rows through the SDK, use the below format to include image layers. Note how the image overlay layers are imported as attachments on an individual data row.
[
{
"row_data": "https://lb-test-data.s3.us-west-1.amazonaws.com/image-samples/sample-image-1.jpg",
"global_key": "https://lb-test-data.s3.us-west-1.amazonaws.com/image-samples/sample-image-1.jpg",
"media_type": "IMAGE",
"attachments": [
{
"type": "IMAGE_OVERLAY",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/rgb.jpg",
"name": "RGB"
},
{
"type": "IMAGE_OVERLAY",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/cir.jpg",
"name": "CIR"
},
{
"type": "IMAGE_OVERLAY",
"value": "https://storage.googleapis.com/labelbox-sample-datasets/Docs/weeds.jpg",
"name": "Weeds"
}
]
}
]