Skip to content

Recipes

Task-shaped walkthroughs. Recipe 1 (import a COCO dataset) lives in the Quickstart; the rest follow. Every method named here is in the API reference with full argument and error docs.

More recipes

  1. Jobs: kickoff → handle.wait(); per-tenant cap is 3 active jobs — serialize embed/train/export, don't parallelize. ConflictError(JOB_PER_TENANT_CAP).
  2. Workflow: workflow.claim/submit/approve/reject (single, as the acting user's key), workflow_batch.* (≤1000 explicit ids), bulk variants return JobHandles. Edit-locks: a labeler editing someone else's in-progress asset → 409.
  3. Versions: versions.create(project_id, name=..., selection=...) → poll versions.wait_ready(...) (freeze is an internal job, not in /jobs). Browse frozen assets + shapes via versions.assets/asset_detail.
  4. Exports: exp = exports.create(project_id, version_id, format=...) (idempotent per version+format+options) → client.jobs.get(exp.job_id).wait() → exports.download_to(...). GoneError = expired/failed → re-create.
  5. Search: assets.search(dataset_id, parts=[{"type": "text", "text": "a red car"}]) — requires embeddings (datasets.embed() job) AND the GPU search endpoint (see gotchas).
  6. SAM segment: segment.segment(project_id, asset_id, points=[{"x": 100, "y": 200, "label": 1}]) → polygon suggestion; commit it as a normal annotation with a class.
  7. Training: training.catalog() → run = training.create_run(...) (GPU, ~minutes to hours; training.wait_run) → find YOUR model: model = next(m for m in client.models.list() if m.training_run_id == run.id).
  8. Deploy + predict: deployments.create(model_id) → poll ready → deployments.predict(deployment_id, image_url=...) (for a platform asset, pass assets.download_url(...); local file → image_b64; whole-dataset runs → the auto-label job, not a predict loop). An UnavailableError with code MODEL_LOADING (~15s) / MODEL_STARTING (~60s) = warming — sleep that long and retry (the SDK already auto-retries 5xx a couple times).
  9. Auto-label: auto_label.put_config → auto_label.create_run(...) (JobHandle) or per-asset auto_label.suggest(...). Runs never touch human annotations.
  10. Activity verification: activity.project_feed(project_id) — assert your operations produced their actions (bulk ops emit kickoff+completed pairs sharing correlation_id == job id).
  11. Errors: catch typed exceptions; RateLimitError is auto-retried by the SDK; PayloadTooLargeError.hint names the bulk alternative; UnprocessableError.details has per-field errors.