Labeling guide

Label images in the browser, review annotations with your team, and export a verified dataset.

Jump to the API reference

Create a project and upload images

  1. Sign in and open Labeling projects. Create a project and give it a name.
  2. Under Label types, choose the annotation types you need. A project can combine boxes, segmentation, points, skeleton poses, image labels, and model hints.
  3. Open Dataset and upload your images. Keep the paths the same as in any annotation files you plan to import.
  4. Open Annotate to draw or edit labels. Add classes for the objects you want to distinguish and save your work.

Import existing annotations

Upload the images first. In Dataset, use the annotation import action to select COCO JSON for boxes and skeleton poses, CSV for confirmed or weak image labels, or the native manifest.json and items.jsonl pair.

Labeling tries the full image path, a matching path suffix, and then an unambiguous filename. Review unmatched files before importing. Ambiguous matches and mismatched dimensions need to be resolved first. Mark model predictions as model-sourced so the Dataset can distinguish them from manually drawn labels.

Assign and verify work

The project owner can invite annotators from the project overview and assign selected images from Dataset. Annotators edit the images assigned to them and submit those images for review. The owner can verify a revision or return it with feedback. Edits after verification require a new review before that image can appear in a new export.

Export a dataset

Verify the images you want in the dataset, then open Export and create an export. Labeling freezes the verified revisions and their image versions. Download the ZIP when it is ready. The archive includes image previews, available originals, review metadata, and supported annotation formats. Use the native JSON/JSONL files for reimport and COCO for workflows that consume boxes or skeleton poses.

Use the API

Open API tokens on the project overview. Give the token only the permissions the script needs and copy the secret when it appears. Send it as an Authorization: Bearer header on each request. You can revoke a token from the same page. Each token applies to a single project.

The image endpoint includes the active image version and the current annotation revision. An annotation import script resolves image paths, creates a job, stages batches against those versions and revisions, publishes, and polls the job. Send JSON records matching the request schema. The browser import action handles conversion from COCO, CSV, or native files.

For automated exports, start a job, poll its status until it completes, and follow the download redirect to the ZIP. The project owner verifies annotations in a signed-in session. The API reference below gives the exact paths, required access, and request and response schemas.

API reference

OpenAPI JSON

List images with a token that has Read annotations permission.

curl -fsS -X GET -H "Authorization: Bearer $LABELING_TOKEN" \
  "https://albumentations.ai/label/api/projects/$PROJECT_ID/dataset/"
  • GET/label/api/projects/{projectId}/

    Get the project and its labeling schema

    annotations:read · HTTP 200

  • GET/label/api/projects/{projectId}/dataset/

    List image summaries with filters and pagination

    annotations:read · HTTP 200

  • GET/label/api/projects/{projectId}/images/{imageId}/

    Get image metadata, revision, annotations and image-level labels

    annotations:read · HTTP 200

  • GET/label/api/projects/{projectId}/annotations/{imageId}/

    Read the current annotation set and revision

    annotations:read · HTTP 200

  • POST/label/api/projects/{projectId}/imports/matches/

    Resolve source paths to images already in the project

    annotations:import · HTTP 200

  • POST/label/api/projects/{projectId}/imports/

    Create or resume an annotation import

    annotations:import · HTTP 201

  • GET/label/api/projects/{projectId}/imports/{importId}/

    Get import status and errors

    annotations:import · HTTP 200

  • PUT/label/api/projects/{projectId}/imports/{importId}/

    Stage a batch of annotations against image versions and revisions

    annotations:import · HTTP 200

  • DELETE/label/api/projects/{projectId}/imports/{importId}/

    Cancel an unpublished import

    annotations:import · HTTP 200

  • GET/label/api/projects/{projectId}/imports/{importId}/items/

    List staged item statuses

    annotations:import · HTTP 200

  • POST/label/api/projects/{projectId}/imports/{importId}/publish/

    Publish a staged annotation import

    annotations:import · HTTP 200, 202

  • POST/label/api/projects/{projectId}/annotations/{imageId}/verify/

    Verify the current annotation revision as project owner

    Project owner session · HTTP 200

  • POST/label/api/projects/{projectId}/exports/

    Start an export of the verified dataset

    dataset:export · HTTP 201

  • GET/label/api/projects/{projectId}/exports/{exportId}/status/

    Check export progress and availability

    dataset:export · HTTP 200

  • GET/label/api/projects/{projectId}/exports/{exportId}/download/

    Redirect to the signed ZIP download URL

    dataset:export · HTTP 302

  • POST/label/api/projects/{projectId}/exports/{exportId}/regenerate/

    Regenerate the expired archive from the frozen export

    dataset:export · HTTP 202

  • GET/label/api/projects/{projectId}/tokens/

    List project token metadata

    Project owner session · HTTP 200

  • POST/label/api/projects/{projectId}/tokens/

    Create a project token and return its secret once

    Project owner session · HTTP 201

  • DELETE/label/api/projects/{projectId}/tokens/{tokenId}/

    Revoke a project token

    Project owner session · HTTP 200