Using the Geti pipeline (application)

The Geti application is a FastAPI server (application/backend/, the geti package) that exposes a REST API for the full computer-vision workflow: create a project, upload and annotate media, train a model as an async job, then configure and enable a live inference pipeline (source → model → sink). This skill is about using that API; to change backend code use the geti-backend-dev skill instead.

These endpoints are served by a running Geti instance; how it was launched does not matter (Docker container, Windows MSIX app, install script, or just run-server from application/backend/ for development). Ask the user for their base URL rather than assuming one — https://localhost:7860 is only the default for a local deployment, the port is configurable and remote instances use a different host. See application/docs/install.md for the deployment modes. The authoritative API reference is the spec the instance serves; fetch it as JSON from /api/openapi.json (the /api/docs page is only an HTML viewer for humans). Read endpoint paths and payloads from there rather than from any checked-in Markdown, which may be out of date. If no instance is running and you have the sources, generate the spec with just gen-api-spec --output-path openapi.json from application/backend/.

End-to-end pipeline

flowchart LR
    A[Create project] --> B[Upload media]
    B --> C[Annotate media]
    C --> D[Train job]
    D --> E[Configure pipeline: source, model, sink]
    E --> F[Enable pipeline / live inference]

1. Create a project with a task type and labels.
   • POST /api/projects (name, task, labels) → project info.
   • Done when: GET /api/projects/<id> returns the project with its labels.
2. Upload media (images/videos) to the project dataset.
   • POST /api/projects/<id>/dataset/media (binary) → media info.
   • Done when: GET /api/projects/<id>/dataset/media lists the uploaded item.
3. Annotate media so the dataset is trainable.
   • POST /api/projects/<id>/dataset/media/<media_id>/annotations (annotation info).
   • Done when: GET .../annotations returns the saved annotation.
   • (Optional) import an existing dataset instead via the dataset jobs below.
4. Train a model as an async job.
   • POST /api/jobs with job type train → job id.
   • Track it: GET /api/jobs/<id>, stream GET /api/jobs/<id>/status and GET /api/jobs/<id>/logs; cancel with POST /api/jobs/<id>:cancel.
   • Done when: the job reaches a finished state and GET /api/projects/<id>/models lists the new model.
5. (Optional) Quantize the trained model for faster inference.
   • POST /api/jobs with job type quantize.
   • Done when: the quantized model variant appears under the project's models.
6. Configure the inference pipeline — bind a source, the model, and a sink.
   • Sources: POST /api/sources; sinks: POST /api/sinks.
   • PATCH /api/projects/<id>/pipeline with the ids of source, sink, and model.
   • Done when: GET /api/projects/<id>/pipeline shows the wired components.
7. Enable live inference and monitor it.
   • POST /api/projects/<id>/pipeline:enable (disable with :disable).
   • Metrics: GET /api/projects/<id>/pipeline/metrics (latency, throughput).
   • POST /api/projects/<id>/pipeline:capture collects the next frame into the dataset for continued annotation/retraining.
   • Done when: the pipeline reports active and metrics update.

The async job model

Long-running work runs as jobs (POST /api/jobs), keeping the API responsive. Job types: train, quantize, prepare_dataset_for_import, import_dataset_to_existing_project, import_dataset_as_new_project, export_dataset. Poll GET /api/jobs/<id> or stream /status and /logs; jobs are cancelable.

Datasets: import instead of manual annotation

To bring in an existing dataset rather than annotating from scratch:

• Upload an archive to staging: POST /api/staged_datasets.
• Then submit an import job (import_dataset_as_new_project or import_dataset_to_existing_project) via POST /api/jobs.
• Export a project's dataset with the export_dataset job.

Notes

• Training and quantization jobs run out-of-process and call into the getitune library; the underlying capabilities map to the getitune-training-a-model and getitune-optimizing-a-model skills.
• This skill covers API usage; the contract for endpoint paths and payloads is the spec at /api/openapi.json. To add or change endpoints, use geti-backend-dev and geti-openapi-sync.

Related skills

• getitune-training-a-model / getitune-optimizing-a-model — the library capabilities behind the train and quantize jobs.
• geti-backend-dev — change the backend/API itself.
• geti-ui-dev — the web UI that drives this same API.