Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

What you want to import
Available route

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

Input
Supported use

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.

Prediction
Recommended input
Key fields

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.

1

Select the project and prepare its media

If the media is not already in the project:

You can also upload through the CLI or frontend, attach existing Assets, or use project.import_cloud(). Do not upload duplicate media when the target already exists.

2

Create the import preview

The returned AnnotationImport contains id, project_id, source_id and preview. Creating it stores a batch and builds a preview; it does not save labels.

3

Resolve mappings and inspect proposed changes

Check the matched media, classes, annotations and issues. For this example, verify that:

  • media resolves to the intended road.jpg at 1280 × 720.

  • car creates or reuses an object-scope bounding-box class named Car.

  • The proposed box is [100, 200, 300, 180] in original pixels.

  • issues is 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.

4

Commit the reviewed preview

The report includes applicable created, updated, kept, unchanged and skipped counts. On a fresh image with no prior import, this fixture creates one box. A reimport can produce different counts because existing work is reconciled.

5

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.

Example
Download

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.

Example
Download

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.

Option
Meaning

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

Result
Next step

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.