Start a training run

This guide shows how to start training once you understand the overview.

Base path: /api/v1
Auth header: Authorization: Bearer <Clerk JWT or lty_… project key>

Replace placeholders:

export BASE="https://api.development.labelty.ai/api/v1"
export KEY="lty_..."
export PROJECT_ID="<project-uuid>"   # or resolve via GET /projects/current

Option A — Use the web wizard (recommended for beginners)

Open your project in Labelty.
Go to the Training area (training wizard / monitor).
Select dataset scope (all approved, filters, or specific assets).
Review readiness warnings (need enough labeled images).
Pick a base model with successful weights.
Choose a GPU tier and hyperparameters (or accept suggestions).
Enter a run name and output model version.
Start the run and open the monitor page.

Screenshot: Training wizard — dataset step
Screenshot: Training wizard — compute / hyperparameters step

Option B — REST API

1. Preview the dataset

Endpoint: POST /projects/{projectId}/training/datasets/preview

curl -sX POST "$BASE/projects/$PROJECT_ID/training/datasets/preview" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": { "mode": "all_approved" },
    "sample_limit": 20,
    "dataset_split": {
      "train_percent": 70,
      "val_percent": 20,
      "test_percent": 10
    }
  }'

What this does: counts assets, labeled images, split sizes, and readiness without starting compute.

Why preview first: create-run will 400 if the dataset is not ready. Preview returns actionable readiness_issues.

Key response fields:

Field	Use
`total_count`	Assets in selection
`labeled_image_count`	Pass to compute-options as `training_image_count`
`ready_for_training`	Must be true before create-run
`readiness_issues`	Human-readable blockers
`selection`	Reuse verbatim in create-run
`dataset_split` / `split_counts`	Resolved percentages and absolute counts

2. List base models

curl -s "$BASE/projects/$PROJECT_ID/models?status=SUCCESS" \
  -H "Authorization: Bearer $KEY"

Pick a base_ml_model_id that has weights you want to fine-tune.

3. Get compute options

curl -sG "$BASE/projects/$PROJECT_ID/training/compute-options" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "base_ml_model_id=$BASE_MODEL_ID" \
  --data-urlencode "training_image_count=$LABELED_COUNT" \
  --data-urlencode "imgsz=640"

What this returns: GPU tiers with pricing / within_budget, wallet budget summary, and a full suggested_training_config (Ultralytics hyperparameters).

4. Create the run

Endpoint: POST /projects/{projectId}/training/runs → 201

curl -sX POST "$BASE/projects/$PROJECT_ID/training/runs" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My run",
    "output_model_version": "1.0.0",
    "dataset_selection": { "mode": "all_approved" },
    "base_ml_model_id": "770e8400-e29b-41d4-a716-446655440002",
    "model_source_type": "REGISTRY_MODEL",
    "gpu_tier": "xlarge",
    "epochs_planned": 100,
    "training_config": {
      "batch": 16,
      "patience": 20,
      "lr0": 0.01,
      "optimizer": "AdamW",
      "mosaic": 0.8
    }
  }'

Required fields: name, output_model_version, dataset_selection, base_ml_model_id.

Important: name + output_model_version become the registry identity of the output model. Duplicate name+version returns 409 — pick another pair before starting.

Useful `training_config` keys

All keys are optional; omitted keys use server suggestions.

Key	Default (typical)	Meaning
`imgsz`	640	Train image size
`batch`	memory budget	Batch size
`patience`	50	Early stopping patience (epochs)
`lr0`	0.01	Initial learning rate
`optimizer`	`auto`	e.g. `SGD`, `AdamW`
`mosaic` / `mixup` / flips	grayscale-safe defaults	Augmentation

HSV hue/saturation jitter defaults are fixed off for grayscale-safe training (hsv_h / hsv_s = 0).

Common create-run errors

Code	Meaning
`400`	Dataset not ready / invalid config
`403`	Missing permission or org budget exceeded
`409`	Output name+version already exists
`503`	SageMaker / training infra not configured

Next step

Watch metrics and build the inference package: Monitor and build.