Processing

The Processing router controls video analysis jobs. After uploading and registering a video, use these endpoints to start processing and monitor progress.

---

POST /processing/register-upload

Register a file that was uploaded to B2 storage, creating a video record in the database.

Auth: Required

Body Field	Type	Required	Description
file_path	string	Yes	B2 storage path (must be under users/<user-id>/)
file_name	string	No	Display name (defaults to filename from path)
file_size	integer	No	File size in bytes (max 4 GB)
job_id	string	No	Custom job ID (auto-generated UUID if omitted)

Response:

{
  "success": true,
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alreadyExists": false
}

If a video with the same job_id or storage_path already exists, returns alreadyExists: true with the existing job_id.

curl -X POST https://api.lynxvizion.com/api/processing/register-upload \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "users/550e8400-.../my-video.mp4",
    "file_name": "Product Demo",
    "file_size": 52428800
  }'

---

POST /processing/{job_id}/start

Start processing a registered video. The video must be in uploaded or failed status.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Body Field	Type	Required	Description
selected_insights	string	No	JSON string of module names to run (e.g. "[\"visualelements\",\"transcription\"]")

Response: ProcessingStatus

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "error": null,
  "processing_time": null,
  "created_at": "2025-01-15T10:00:00",
  "updated_at": "2025-01-15T10:05:00"
}

curl -X POST https://api.lynxvizion.com/api/processing/a1b2c3d4-.../start \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selected_insights": "[\"visualelements\",\"transcription\",\"scenes\"]"}'

---

GET /processing/{job_id}/status

Poll the current processing status of a video.

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Response: ProcessingStatus

{
  "job_id": "a1b2c3d4-...",
  "status": "processing",
  "error": null,
  "processing_time": null,
  "created_at": "2025-01-15T10:00:00",
  "updated_at": "2025-01-15T10:05:30"
}

Status values:

Status	Description
uploaded	File registered, not yet queued
queued	Waiting for a worker to pick up
processing	Currently being analyzed
completed	All modules finished successfully
failed	Processing encountered an error (see error field)

curl https://api.lynxvizion.com/api/processing/a1b2c3d4-.../status \
  -H "Authorization: $LVZ_KEY"

---

GET /processing/{job_id}/events

Stream real-time processing events via Server-Sent Events (SSE).

Auth: Required

Path Param	Type	Required	Description
job_id	string	Yes	The video’s job ID

Response: text/event-stream

The stream emits JSON events as processing progresses:

data: {"type": "module_started", "module": "transcription"}

data: {"type": "module_completed", "module": "transcription"}

data: {"type": "done", "status": "completed"}

The stream ends automatically when the job reaches completed or failed status. Keepalive comments (: keepalive) are sent every second.

curl -N https://api.lynxvizion.com/api/processing/a1b2c3d4-.../events \
  -H "Authorization: $LVZ_KEY"

In JavaScript:

const eventSource = new EventSource(
  `https://api.lynxvizion.com/api/processing/${jobId}/events`,
  { headers: { Authorization: apiKey } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data.module || data.status);
};