Quickstart

This guide walks you through the complete workflow: upload a video, start AI processing, and retrieve structured analysis results.

Prerequisites

• A LynxVizion account
• An API key (create one in the dashboard or via the API Keys endpoint)

1. Create an API Key

Generate an API key from the dashboard, or via the API:

curl -X POST https://api.lynxvizion.com/api/keys \
  -H "Authorization: Bearer <your-clerk-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Key"}'

The response includes your raw API key (shown only once):

{
  "id": "1",
  "name": "My First Key",
  "key_prefix": "lvz_live_abcdef...",
  "raw_key": "lvz_live_abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
  "is_active": 1,
  "created_at": "2025-01-15T10:00:00"
}

Save raw_key — you won’t see it again. Use it as your Authorization header for all subsequent requests.

export LVZ_KEY="lvz_live_abcdef1234..."

2. Get a Presigned Upload URL

Request a presigned URL to upload your video file to storage:

curl -X POST https://api.lynxvizion.com/api/storage/upload-url \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "my-video.mp4", "content_type": "video/mp4"}'

Response:

{
  "success": true,
  "upload_url": "https://s3.eu-central-003.backblazeb2.com/...",
  "file_path": "users/<user-id>/my-video.mp4",
  "sanitized_filename": "my-video.mp4"
}

3. Upload the File

Use the presigned URL to upload your video via PUT:

curl -X PUT "<upload_url from step 2>" \
  -H "Content-Type: video/mp4" \
  --data-binary @my-video.mp4

4. Register the Upload

Tell LynxVizion about the uploaded file to create a video record:

curl -X POST https://api.lynxvizion.com/api/processing/register-upload \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "users/<user-id>/my-video.mp4",
    "file_name": "my-video.mp4"
  }'

Response:

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

5. Start Processing

Kick off AI analysis with your chosen modules:

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

Response:

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

6. Poll for Status

Check processing progress:

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

Status progresses through: uploaded → queued → processing → completed (or failed).

For real-time updates, use the SSE endpoint instead:

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

7. Get Results

Once status is completed, fetch the full analysis:

curl https://api.lynxvizion.com/api/results/job/$JOB_ID \
  -H "Authorization: $LVZ_KEY"

Response includes all segments grouped by module:

{
  "job_id": "a1b2c3d4-...",
  "video_name": "my-video.mp4",
  "duration": 120.5,
  "status": "completed",
  "processing_time": 45.2,
  "segments": [...],
  "visualelements": [
    {
      "id": "1",
      "module": "visualelements",
      "content": "Objects Detected: person, laptop; Colors: blue, white; ...",
      "start_time": 0.0,
      "end_time": 3.0
    }
  ],
  "transcription": [
    {
      "id": "2",
      "module": "transcription",
      "content": "Hello and welcome to this demonstration.",
      "start_time": 1.5,
      "end_time": 4.2
    }
  ]
}

8. Search Across Videos

Once you have processed videos, search across all of them with natural language:

curl -X POST https://api.lynxvizion.com/api/search \
  -H "Authorization: $LVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "person using a laptop", "limit": 10}'

Response:

[
  {
    "id": "42",
    "job_id": "a1b2c3d4-...",
    "module": "visualelements",
    "content": "Objects Detected: person, laptop, desk; ...",
    "start_time": 15.0,
    "end_time": 18.0,
    "similarity": 0.8234
  }
]

Next Steps

• Authentication — API key and JWT details
• Videos — manage your video library
• Chat — ask the AI agent questions about your videos
• Processing — processing controls and SSE events