Annotation imports
Import COCO and Unitlab annotation JSON with the Python SDK. Match existing media, map classes and video frames, preview changes and commit labels safely.
Import existing labels or model predictions into media already uploaded or attached to a Unitlab project. Media can come from your computer or a saved cloud connection; the annotation JSON can be local or stored in connected cloud storage.
Media files or folders
CLI media upload, Python SDK or the frontend.
Annotation labels
This Python SDK workflow or Import local annotations in the frontend.
Unitlab CLI 3.1.6 does not have an annotation-import subcommand. You can upload media with the CLI and then run a Python script to import its labels.
Before importing
Use Unitlab 3.1.6 on Python 3.10 or newer and complete authentication. Committing annotations requires a user-created workspace API key so saved labels have an audit author.
Wait for media processing to finish. The importer matches references to existing project items; it does not fetch media from URLs in your label file. Use ordinary, supported project items in an eligible Annotate or Review workflow state. Grouped items and items in Model, Consensus or Archive cannot receive labels through this importer.
Supported annotation files
COCO JSON
Image bounding boxes, supported polygon segmentation, RLE masks and keypoints. Video requires a frame map.
unitlab-image/1
One image with native objects, pixel coordinates and whole-image select classifications.
unitlab-video/1
One video with explicit frame indices, annotations and tracks.
Unitlab UUEF item JSON
One exported item per file. Import each item JSON as its own batch.
Unitlab Audio JSON
Audio regions and supported classifications/properties in Unitlab's export structure.
Unitlab GeoJSON
Geospatial features with Unitlab media and class metadata, using .json or .geojson.
Supported target families are image, video, medical, document, audio, time series, text, HTML, geospatial and pathology. Tabular and pointcloud annotation import are not supported by this importer, even though those families can be exported.
YOLO TXT, JSONL, arbitrary model JSON, generic file-list JSON and whole export ZIPs are not accepted label inputs. A unitlab-import-manifest/1 package manifest or frame map alone is not an annotation document. UUEF group metadata does not recreate Data Groups.
The SDK and parser ceiling is 80 MiB per annotation or frame-map file. A deployment's HTTP request limit can be lower. If a large local file is rejected, split it by media item into smaller valid annotation files or import its JSON through connected cloud storage. Keep each tracked object's frames together and include the required media and class definitions in each file. Reusing a track ID across separate files does not automatically merge those files under the default identity settings.
Import predictions from your own model
Convert the model's output into a supported annotation file, then preview and commit it onto matching project images. A prediction file supplies initial labels that people can inspect and correct.
Bounding boxes
COCO or unitlab-image/1
bbox: [x, y, width, height] in original image pixels.
Polygons
COCO or unitlab-image/1
COCO segmentation contains flat coordinate rings; native polygon contains [x, y] pairs.
Segmentation masks
COCO or unitlab-image/1
COCO RLE with size: [height, width] and uncompressed integer runs or a compressed counts string.
Whole-image classification
unitlab-image/1
An image-scope single_select or multi_select class and a classifications entry.
COCO categories describe object classes in this importer. They do not turn an image into an image-level classification. Use the native classification example below when your model predicts an image-wide category such as weather, quality or scene type. Native image JSON can contain object annotations and image classifications together.
COCO supports masks as well as boxes and polygons. Put an RLE object in the annotation's segmentation field: {"size": [height, width], "counts": [...]} or a compressed COCO counts string. The RLE must use COCO column-major ordering, cover the original image exactly and contain foreground pixels. Polygon coordinate lists remain polygon labels; they are not automatically converted into mask labels. For native image JSON, declare a type: "mask", scope: "object" class and put the same RLE object in the annotation's mask field. Standalone mask PNG files are not annotation JSON inputs.
YOLO label files are not imported directly. Convert detection or segmentation labels to COCO or native image JSON before importing. For a normalized YOLO detection (x_center, y_center, width, height) on an image of size W × H, convert to pixel [x, y, width, height] as [(x_center - width/2) × W, (y_center - height/2) × H, width × W, height × H]. For normalized polygon vertices, multiply each x by W and each y by H. Supply the matching filenames, dimensions, class names and stable annotation IDs required by the chosen format. Renaming .txt to .json does not convert the format.
Preview and commit a local JSON file
This walkthrough imports one Car box onto road.jpg. Use your own 1280 × 720 image and download image-labels.json, or change the file's reference, dimensions and box to match your image.
Run Python from road-scenes/. The label file's media.reference is road.jpg: ordinary SDK uploads send the image's basename, even though the local file is inside images/. The JSON lives in labels/ for organization; its own folder is not part of the media reference.
Keep the following steps in the same Python session so that client, project and batch remain available. Replace PROJECT_ID with the target project's UUID.
Resolve mappings and inspect proposed changes
Check the matched media, classes, annotations and issues. For this example, verify that:
mediaresolves to the intendedroad.jpgat 1280 × 720.carcreates or reuses an object-scope bounding-box class named Car.The proposed box is
[100, 200, 300, 180]in original pixels.issuesis empty and no annotation row is blocked.
Add explicit mappings when a name is ambiguous or a class needs a chosen target. Rebuild the preview after mappings or media readiness change. See Match media and classes.
Check the saved label in Unitlab
Open road.jpg in the project. Check the Car class and box against the image, then follow the configured review workflow. A successful import leaves editable labels; it does not automatically approve the work. Retain batch.id, batch.source_id and the commit report for the next import.
Run the SDK import from a terminal
To inspect the same example interactively, save the following as road-scenes/import_labels.py, replace PROJECT_ID, and run it from road-scenes/:
Run it in your configured Python environment:
Python stays open after printing the preview. Review the matches and issues, apply any mappings described below, and then call batch.commit() when the preview is correct. Call client.close() when finished. This runs the Python SDK; it does not add a label-import command to the Unitlab CLI.
Download example annotation files
These files contain labels only. Upload matching media first, or adapt each example to your files and dimensions.
Native image box for road.jpg, 1280 × 720
COCO image box for the same image
Native video track for drive.mp4, 1280 × 720, six source frames
COCO track on source frames 0 and 5 of the same video
Use track_profile="attributes.track_id" with the downloadable COCO video pair, as shown in the video example below.
Minimal image example
Save this as labels/image-labels.json for the walkthrough. It describes one bounding box in an already uploaded 1280 × 720 image named road.jpg:
bbox is [x, y, width, height] in original image pixels. Use the actual media dimensions, not a resized preview's dimensions or normalized 0-to-1 coordinates. Save UTF-8 JSON with unique annotation IDs and finite numeric values.
For COCO, keep the required images, categories and annotations arrays. Use supported geometry fields.
Model-output examples
These label-only examples use road.jpg at 1280 × 720, or mask-demo.png at 4 × 3 for the small mask fixtures. Replace the references and coordinates with your own media before importing. The two mask files describe the same foreground pixels using different COCO encodings.
COCO boxes and polygons
COCO mask, uncompressed RLE
COCO mask, compressed RLE
Whole-image classification
Native boxes, polygons, and image classification
Image-level classification example
This is a separate example. Save it as labels/image-classification.json. It assigns Weather: Clear to the whole road.jpg image without drawing an object:
Using the same configured project, create and inspect a separate preview:
After checking the match and classification choices, commit that batch:
Open Item properties on road.jpg and verify Weather: Clear.
value is always an array of declared option IDs. single_select requires exactly one value; multi_select accepts one or more unique values. Classification option IDs and names must be unique and nonempty. These classifications become Item properties in the image editor. To include boxes or polygons in the same file, add object-scope classes and their entries in annotations while retaining classifications.
For a native polygon, an object annotation can use {"id": "road-1", "class_id": "road", "polygon": [[0, 400], [1280, 400], [1280, 720], [0, 720]]} with a corresponding {"id": "road", "name": "Road", "type": "polygon", "scope": "object"} class. A COCO polygon instead uses "segmentation": [[0, 400, 1280, 400, 1280, 720, 0, 720]] on an annotation that references its image and category.
Match media and classes
Matching uses explicit mappings, exported identities and exact stored references. A bare filename can match an unambiguous item. A qualified path must match that path; it does not silently fall back to another directory's basename. Dimensions, family and relevant content identity must also agree.
Find candidate project-media IDs:
The helper returns up to 50 candidates. Narrow the search when necessary. Use preview keys and target IDs from these results rather than inventing them.
For the native example, the external media key is the literal media and the class key is car:
Class targets are project class UUIDs, not numeric ontology values. To rename a new imported class, use {"new_name": "Vehicle"} instead of target_id. The import cannot add classes to a shared ontology.
media_mapping
Preview media key to project-media ID. Native/UUEF commonly uses media; COCO uses its filename or frame-map media reference.
class_mapping
Preview class key to {"target_id": "PROJECT_CLASS_ID"} or {"new_name": "Name"}. COCO keys include shape, such as 1:bbox.
object_mapping
Preview annotation row key to an existing object ID.
review_mapping
Preview media key to a Review-stage ID when an accepted change must return protected work for review.
stable_ids
Whether the exporter preserves external object identities across prediction runs. Default false.
batch.refresh() preserves existing options. batch.refresh(options={...}) replaces the entire options dictionary, so include every mapping you still need. Always inspect the refreshed preview before committing.
Reuse a prediction source
This is a later prediction run, using a newly prepared predictions-v2.json and the source_id saved from the first import.
Provide exactly one of source_name or source_id. A source identifies the prediction namespace; it is not the media-upload folder.
Reuse the source for later predictions from the same model. Keep stable_ids=False unless the exporter preserves object identity between runs. This avoids silently treating a reused external ID as the same object.
Video and frame maps
Native unitlab-video/1 describes one video. Declare frame_index_base as 0 or 1. Tracks use presence_mode="explicit_frames" and interpolation="none": unlisted frames are not automatically interpolated.
COCO video uses a separate unitlab-frame-map/1 file. Prepare this separate example, using the downloadable COCO video pair above:
Run the example from video-example/ after drive.mp4 is uploaded and ready in the selected project. Map every COCO image ID exactly once to its original video and zero-based source-frame index:
Use attributes.track_id only when your COCO annotations carry track IDs in that field. Otherwise keep the default track_profile="none". Frame-like filenames are not a substitute for the explicit map.
Native and COCO frame labels refer to original source frames. For all-frame labels, upload at the original video's frame rate rather than the SDK's default 1 FPS. A frame map cannot recover frames omitted by sampling. UUEF video/medical imports must instead match their exported display-frame or slice layout.
Read annotation JSON from connected storage
This alternative uses the configured project from the first example. The saved cloud connection must contain labels/predictions.json, and the media referenced by that JSON must already be in the project. Replace CLOUD_STORAGE_ID with the saved connection's UUID.
For a cloud COCO frame map, supply frame_mapping_key="labels/frames.json". Keys are relative to the saved connection's prefix; use a JSON/GeoJSON object key, not a full URL. Media and label references must resolve in the API key's workspace and the selected project.
Use either a local annotation file or the cloud storage/key pair. Do not provide both. A frame-map file must use .json; annotation files can use .json or .geojson.
Correct and review imported predictions
A successful commit saves editable annotation labels. It does not complete the task or approve the predictions. An approved flag in an input file cannot replace a reviewer action.
Open the affected image in Unitlab, correct its boxes or polygon vertices, remove incorrect objects, add missing labels and check image classifications under Item properties. Your permissions and the current workflow stage determine which changes and actions are available.
To require human approval, use a workflow with an Annotate stage followed by Review. After correction, the annotator selects the available forward action, typically Send to Review. A reviewer inspects the result, makes permitted corrections, and uses the forward action to approve it, or Reject to send it back along the configured rework route. The forward button is labelled by its destination, such as Mark as Complete or Send to [stage name]. Review assignments and self-review restrictions still apply.
An accepted import change to protected work requires a valid Review destination. Work already in Review stays there; other eligible protected work returns to the chosen Review stage. If several Review stages are available, provide review_mapping using the preview's media key and Review-stage ID. Importing into grouped tasks or Model, Consensus and Archive stages remains blocked.
See Review, rework and escalation for workflow setup and reviewer controls.
Conflicts, stale previews and partial imports
Existing human edits and deletions are kept by default. To resolve a specific preview row:
Decisions are keep, incoming or skip. incoming explicitly accepts the incoming change; protected reviewed work can require a valid Review destination. Parser issues or blocked records reject the ordinary commit: commit() raises AnnotationImportError and saves nothing. Use allow_partial=True only when you intend to save eligible records and skip blocked ones. commit() also takes timeout, the number of seconds to wait for the server's reply (default 300).
Media is still processing
Wait for its Batch Queue, then refresh and inspect the preview. The SDK does not schedule the browser's deferred import flow.
Ambiguous or unmatched media
Check original paths and add explicit media mappings. A URL in JSON will not download the file.
Class or property incompatibility
Map a compatible project class or correct the source schema.
Unsupported workflow state
Use an eligible ungrouped Annotate/Review item.
ConflictError
The preview became stale. Refresh, review and commit again.
PermissionDeniedError on commit
Check the workspace and use a user-created API key with an audit author.
AnnotationImportError on commit
Blocked records or file issues stopped the commit and nothing was saved. Inspect .rows, .issues and .batch_id, then fix them.
Commit response was lost
Repeat the same batch's commit with the same decisions. A successful prior commit returns its saved report without duplicating labels.
Import batch is already committed
Create a new batch under the same source for a later import. Committed batches cannot be refreshed.
Continue with frontend annotation import, workflow review, or Unitlab's data annotation platform.
Complete the workflow
See Pre-labels, review, and export for the full S3, import, human review, and delivery workflow.