> 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/annotation-imports.md).

# Annotation imports

Import COCO, UUEF, Audio JSON, GeoJSON or native JSON labels for media already in a project, with a preview before anything is saved.

Bring labels from your own model or another tool into a project. The import runs in two steps: `create()` uploads the file and returns a **preview**, and `commit()` saves it. Nothing changes until you commit.

```python
imported = project.annotation_imports.create("./detector-v3.json", source_name="detector-v3")

print(imported.preview["counts"])
for issue in imported.preview["issues"][:10]:
    print(issue)

report = imported.commit()
print(report)
```

Upload the media first and wait for processing. Labels only match media the server has finished.

## Supported files

| Format                               | Media                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------- |
| COCO JSON                            | Images; video with a frame map                                          |
| UUEF item JSON (`.json`)             | Every media type. One file holds one item; import each file on its own. |
| Audio JSON                           | Audio                                                                   |
| GeoJSON (`.geojson`, `.json`)        | Geospatial and pathology                                                |
| `unitlab-image/1`, `unitlab-video/1` | Images and video                                                        |

Each file can be up to 80 MiB. YOLO text files and other tools' project files are not accepted.

## How labels find their media

Media is matched by original path or ID, then by a unique file name. When names are ambiguous, map them yourself:

```python
candidates = project.annotation_imports.media(search="cell04_0001")
imported = imported.refresh(options={"media_mapping": {"cell04_0001.jpg": "DATASOURCE_ID"}})
```

`refresh(options=...)` replaces every option. Supported options are `stable_ids`, `media_mapping`, `class_mapping`, `object_mapping` and `review_mapping`.

## Create options

| Argument                                               | Use                                                                                                        |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `source_name`                                          | Name of the label source. Reuse it for the next run of the same model.                                     |
| `source_id`                                            | Reuse a source by ID; `annotation_imports.sources()` lists them                                            |
| `frame_mapping_file`                                   | COCO video: a `unitlab-frame-map/1` file mapping images to frames                                          |
| `track_profile="attributes.track_id"`                  | COCO video with track IDs in `attributes.track_id`                                                         |
| `cloud_storage`, `annotation_key`, `frame_mapping_key` | Read the files from a connected bucket instead of your disk                                                |
| `options={"stable_ids": True}`                         | Your exporter keeps object IDs stable between runs                                                         |
| `benchmark=True`, `approve_keys=True`                  | Write into benchmark answer keys; see [Benchmarks](https://docs.unitlab.ai/api-sdk-cli/sdks/benchmarks.md) |

Import video at its original frame rate. Labels on frames dropped by sampling are refused.

## Commit

| Argument        | Default | Effect                                                                   |
| --------------- | ------- | ------------------------------------------------------------------------ |
| `decisions`     | None    | Resolve one conflict: `{annotation_key: "keep" \| "incoming" \| "skip"}` |
| `allow_partial` | `False` | Save the valid rows even when others are blocked                         |
| `timeout`       | 300 s   | How long to wait for the commit                                          |

By default a commit keeps existing labels on conflict and does not bring back objects people deleted. The report counts created, updated, kept, unchanged and skipped objects.

| Situation                    | What happens                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| Some rows are blocked        | `AnnotationImportError`. `.rows` and `.issues` list them; nothing is saved.                |
| The preview is out of date   | `ConflictError`. Call `refresh()`, check it and commit again.                              |
| The commit response was lost | Call `commit()` again with the same decisions. You get the saved report and no duplicates. |

Imported labels are pre-labels. Approving them is a separate review step in the workflow.

The key needs **Manage data** and **Create labels**, and must have been created by a workspace member.

## Related

[Pre-labels, review and export](https://docs.unitlab.ai/api-sdk-cli/sdks/prelabels-review-and-export.md) · [Upload, label and export](https://docs.unitlab.ai/api-sdk-cli/get-started/upload-label-and-export.md) · [Annotation JSON reference](https://docs.unitlab.ai/api-sdk-cli/apis/annotation-json-reference.md)
