Get Started

Quickstart

Quickstart

Prerequisites

You’ll need an API key. Get one at console.pureframe.ai/settings/api-keys.

All examples use curl. Swap in your own key where you see pf_key_....

Step 1 — Create a collection

Every video must belong to a collection. Create one first:

$curl -X POST https://api.pureframe.ai/v1/collections \
>  -H "Authorization: Bearer pf_key_..." \
>  -H "Content-Type: application/json" \
>  -d '{ "name": "My footage" }'
1{
2  "data": {
3    "id": "col_abc123",
4    "name": "My footage",
5    "video_count": 0,
6    "created_at": "2025-01-01T12:00:00Z"
7  }
8}

Save the id — you’ll use it in the next step.

Step 2 — Upload a video

$curl -X POST https://api.pureframe.ai/v1/upload \
>  -H "Authorization: Bearer pf_key_..." \
>  -F "collection_id=col_abc123" \
>  -F "file=@footage.mp4"
1{
2  "data": {
3    "job_id": "job_xyz789",
4    "video_id": "vid_def456",
5    "status": "queued"
6  }
7}

Save the job_id.

Step 3 — Wait for indexing

Poll until status is done. A 10-minute video typically takes 1–3 minutes.

$curl https://api.pureframe.ai/v1/jobs/job_xyz789 \
>  -H "Authorization: Bearer pf_key_..."
1{
2  "data": {
3    "job_id": "job_xyz789",
4    "status": "done",
5    "progress_pct": 100
6  }
7}

In production, use exponential backoff — poll at 5s, 10s, 20s intervals rather than a tight loop.

Step 4 — Search

Send a text query. Pureframe searches visual content and speech simultaneously.

$curl -X POST https://api.pureframe.ai/v1/search \
>  -H "Authorization: Bearer pf_key_..." \
>  -F "query=person waving at the camera" \
>  -F "collection_id=col_abc123"
1{
2  "data": [
3    {
4      "video_id": "vid_def456",
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          "video_url": "https://...",
13          "thumbnail_url": "https://..."
14        }
15      ]
16    }
17  ],
18  "meta": { "total": 1 }
19}

Each result gives you:

FieldDescription
timestamp_start / timestamp_endWhere in the video this moment occurs (seconds)
scoreRelevance from 0 to 1
text_contentTranscribed speech in this clip, if any
video_urlPresigned URL to stream the video (valid ~1 hour)
thumbnail_urlPresigned URL to the matched frame image

Step 5 — Search with an image

You can also search using a reference image to find visually similar moments:

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

Or supply a public image URL:

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

Next steps

Core Concepts: Search

Search modes, multimodal inputs, and pagination.

Core Concepts: Collections

Organize videos and scope searches to a specific library.

Agent Vision

Full guide to MCP and function calling integrations.

API Reference

Every endpoint, parameter, and response field.