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.

1. 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.

1. 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.

1. 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.

1. (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.

1. 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.

1. 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, preparedatasetforimport, importdatasettoexistingproject, importdatasetasnewproject, exportdataset. 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 (importdatasetasnewproject or

importdatasettoexistingproject) 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.