> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/sdks/prelabels-review-and-export.md).

# Pre-labels, review, and export

Import model pre-labels for local or S3-linked images, review them in Unitlab, and export labels with explicit approval and storage checks.

Use this workflow when your model predicts labels and your team corrects them before training. Unitlab separates media ingestion, label import, human review, and release delivery.

{% hint style="warning" %}
**Check availability first.** Label import requires a Unitlab server with Annotation Imports support. `unitlab==3.1.6` contains the Python methods, but installing it does not enable the server feature. Confirm availability for your workspace before building a production integration.
{% endhint %}

## What is supported?

| Requirement                        | Support and boundary                                                                                                                                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Import COCO model predictions      | Python SDK, HTTP API, and frontend on compatible deployments. Boxes, polygons, and instance masks using compressed or uncompressed COCO RLE are supported.                                                                                                                |
| Import image-level classes         | Use native `unitlab-image/1` single-select or multi-select classifications. COCO categories describe objects, not whole-image classes.                                                                                                                                    |
| Import YOLO labels                 | No direct YOLO TXT or ZIP import. Convert to a supported format first. YOLO export support does not imply import support.                                                                                                                                                 |
| Link images from S3                | Originals remain referenced in the customer bucket. Unitlab reads them for processing and writes generated data, so the connection is not read-only.                                                                                                                      |
| Import labels for S3-linked images | Yes, after linking the images into the Project and completing processing. Labels can be local JSON or a JSON key in a saved cloud connection.                                                                                                                             |
| Correct and approve imported work  | Yes. Import commits editable labels; acceptance remains a separate configured Review decision.                                                                                                                                                                            |
| Retrieve label payloads            | Create and download a Release through the SDK or HTTP API. For one Workflow task, `task.get_annotations()` (SDK 3.1.4 and later) returns each item's full annotation document, geometry included. Other task/state endpoints expose metadata and review evidence.         |
| Retrieve only approved items       | No built-in approved-only Release filter. `completed_only=True` releases only items whose current status is Complete, which does not prove approval. Independently verify the entire selected Project or Batch Queue, or filter the downloaded data in your own pipeline. |
| Export directly to S3              | Generated exports can use the saved source S3 connection. An arbitrary destination bucket/key cannot be chosen through the Release API or CLI.                                                                                                                            |

## 1. Prepare the media and model output

Upload a local file or folder using [CLI media uploads](https://docs.unitlab.ai/api-sdk-cli/clis/cli-projects-and-data-units) or the [Python SDK](https://docs.unitlab.ai/api-sdk-cli/sdks/project-uploads.md). For S3, configure a saved connection in the web application, then follow [Cloud storage](https://docs.unitlab.ai/api-sdk-cli/sdks/cloud-storage.md) to link existing objects. Wait for processing before importing labels.

Use this small local example to test the complete handoff before processing a larger dataset:

```
road-scenes/
├── images/
│   └── road.jpg
└── labels/
    └── coco-labels.json
```

Download the [COCO bounding-box example](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports.md#download-example-annotation-files), which references `road.jpg` at 1280 × 720 and contains one **Car** box. Supply matching media or update its reference, dimensions and geometry. Run Python from `road-scenes/`; ordinary SDK/CLI uploads use the basename `road.jpg`.

Use COCO JSON for object boxes, polygon segmentation, or RLE instance masks. For whole-image classes, use the native image JSON example in [Annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports.md). Keep original image dimensions and stable filenames; resolve ambiguous matches in the preview. The import does not download URLs embedded in the JSON.

## 2. Preview the predictions

The following example assumes the images already belong to the target Project and have finished processing. Set your API key through your environment or configured SDK credentials.

```python
from unitlab import UnitlabClient

client = UnitlabClient()
project = client.projects.get("PROJECT_ID")

batch = project.annotation_imports.create(
    "./labels/coco-labels.json",
    source_name="detector-v1",
)
print(batch.preview)
```

Inspect the matched filename, class, proposed box and issues. This fixture should resolve one image and one **Car** box; no row should be blocked. If it does not, resolve the mapping and refresh before continuing.

## 3. Commit and check the labels

Continue in the same Python session, using the `batch` you inspected:

```python
report = batch.commit()
print(report)
```

On a fresh image, expect one created box. Open `road.jpg` and verify the saved geometry. Keep the returned `source_id` for subsequent predictions from the same model. Human edits are preserved by default when they conflict with incoming predictions. See [Annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports.md) for refresh, explicit decisions, partial commits, and cloud JSON inputs. For HTTP requests, see [Annotations and workflow API](https://docs.unitlab.ai/api-sdk-cli/apis/annotations-and-workflow-api.md).

The CLI supports media file/folder upload. CLI 3.1.6 does not have an annotation-import command; use the Python SDK or frontend for labels, or call the documented HTTP API directly.

## 4. Review and correct the work

Configure **Annotate → Review → Complete**, with a rejection path back for corrections. Annotators check and edit the imported boxes, polygons, masks, and classifications. Reviewers accept or reject according to the configured workflow. The acceptance button may read **Mark as Complete** or **Send to \[stage name]**.

Importing labels, saving corrections, and finishing export preparation do not constitute review approval. Read the [review procedure](https://docs.unitlab.ai/documentation/workflows/review-rework-and-escalation) before automating the handoff.

You can inspect currently completed work and its history:

```python
completed = project.data_units(
    status="complete",
    batch_queue="BATCH_QUEUE_ID",
)
for unit in completed:
    if unit.workflow_task_id:
        task = project.workflow.get_task(unit.workflow_task_id)
        print(unit.id, task.get_timeline())
```

This query returns completed work, not an approved export. Inspect the required review decisions and subsequent changes. A manager override or a workflow without Review can also produce Complete. Discover the Project's actual stages with `project.workflow.stages` when more than one review is required.

## 5. Create and validate a controlled delivery

There is no `approved_only=True` Release option. Release selection uses eligible latest annotations within the selected Project, Batch Queues, and data types. Pass `completed_only=True` (SDK 3.1.2 and later) to keep only items whose current workflow status is Complete; like the completed-work query above, it does not prove review approval. See [Release only completed items](https://docs.unitlab.ai/api-sdk-cli/sdks/create-and-download-releases.md#release-only-completed-items).

Before creating a reviewed delivery:

1. Use a dedicated Project or Batch Queue and verify that **all eligible items in that scope** passed the required reviews.
2. Keep media, labels, and workflow state unchanged while the snapshot is being prepared. The snapshot captures the latest eligible histories when it freezes, not necessarily the versions approved earlier.
3. Create the Release with explicit scope, then reconcile the downloaded item IDs and counts against your approved delivery list.

Run this only after those review checks, in the same session with `client` and `project`. Replace `BATCH_QUEUE_ID` with the queue whose entire eligible contents you verified:

```python
release = client.releases.create(
    project,
    export_type="COCO",
    data_types=["image"],
    upload_sessions=["BATCH_QUEUE_ID"],
    split_ratios={"train": 100},
)
archive_path = release.download(dest="./exports")
print(release.id, release.version, archive_path)
```

COCO is suitable for supported object geometry. Use UUEF when you need Unitlab's richer annotation representation, including image-level properties, and check the resulting schema before training. See [Create and download releases](https://docs.unitlab.ai/api-sdk-cli/sdks/create-and-download-releases.md).

## 6. Deliver to S3 when required

For a Project using one saved S3 connection, generated annotation exports can be stored in that source bucket under Unitlab's generated release prefix. The connection must permit those writes. Original media is not copied into a Unitlab-owned bucket as part of linking it, but processing still reads the originals and generates derived data.

There is no Release parameter for a destination S3 bucket, prefix, or object key. With multiple source connections, the backend chooses a source connection for export storage; do not assume you can select it. If the customer needs a separate delivery bucket or a specific key, download the export and upload it using their AWS tooling.

See [S3 setup and permissions](https://docs.unitlab.ai/documentation/data/cloud-providers) and [SDK cloud storage](https://docs.unitlab.ai/api-sdk-cli/sdks/cloud-storage.md) for access-key authentication, read/write requirements, and deployment compatibility.
