Quickstart

This guide walks you through uploading a video, waiting for it to index, and running your first search — using nothing but curl.

Step 1 — Upload a video

Send a multipart/form-data request with your video file. The response returns immediately with a job_id — indexing happens in the background.

$
curl -X POST https://api.pureframe.ai/v1/upload \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "file=@footage.mp4"

1
{
2
  "data": {
3
    "job_id": "job_abc123",
4
    "video_id": "vid_xyz789",
5
    "status": "queued"
6
  },
7
  "ok": true
8
}

Save the video_id — you’ll use it to search later.

Step 2 — Wait for indexing

Poll the job endpoint until status is done. This typically takes 1–3 minutes for a 10-minute video.

$
curl https://api.pureframe.ai/v1/jobs/job_abc123 \
>
  -H "Authorization: Bearer pf_key_..."

1
{
2
  "data": {
3
    "job_id": "job_abc123",
4
    "status": "done",
5
    "progress_pct": 100
6
  },
7
  "ok": true
8
}

Step 3 — Search

Send a text query. PureFrame searches across visual content, speech, and audio simultaneously.

$
curl -X POST https://api.pureframe.ai/v1/search \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "query=person waving at the camera"

1
{
2
  "data": [
3
    {
4
      "video_id": "vid_xyz789",
5
      "filename": "footage.mp4",
6
      "segments": [
7
        {
8
          "timestamp_start": 42.5,
9
          "timestamp_end": 47.0,
10
          "score": 0.91,
11
          "text_content": "Hey everyone, welcome back!",
12
          "thumbnail_url": "https://...",
13
          "thumbnail_base64": "/9j/4AAQ..."
14
        }
15
      ]
16
    }
17
  ],
18
  "meta": { "total": 1 },
19
  "ok": true
20
}

Each result gives you:

• timestamp_start / timestamp_end — where in the video the moment occurs
• score — relevance score from 0 to 1
• text_content — transcribed speech in the clip (if any)
• thumbnail_url — presigned URL to the matched frame
• thumbnail_base64 — base64 JPEG for direct use with vision models

Step 4 — Search with an image

You can also search using a reference image — PureFrame finds visually similar moments.

$
curl -X POST https://api.pureframe.ai/v1/search \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "image=@reference.jpg"

Next steps