Search

Pureframe search finds timestamped moments in your video library. You can search using a text description, a reference image, or a public image URL. Results are ranked by relevance and grouped by video.

Input types

At least one input is required. You cannot send both image and image_url in the same request.

Search modes

The modes parameter controls which modalities are searched. Pass one or both:

Both modes are enabled by default: modes=["video", "transcript"]. You can restrict to a single mode — for example, modes=["transcript"] to search only spoken content.

$
# Search only spoken content
$
curl -X POST https://api.pureframe.ai/v1/search \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "query=pricing discussion" \
>
  -F "modes=transcript"

Scoping to a collection

Pass collection_id to limit results to a specific collection. This is faster and more precise than searching your entire library.

$
curl -X POST https://api.pureframe.ai/v1/search \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "query=product demo" \
>
  -F "collection_id=col_abc123"

Pagination

Results are grouped by video and paginated. Use page and per_page (max 10) to navigate:

$
curl -X POST https://api.pureframe.ai/v1/search \
>
  -H "Authorization: Bearer pf_key_..." \
>
  -F "query=explosion scene" \
>
  -F "page=2" \
>
  -F "per_page=10"

The meta field in the response includes total (total matching videos), page, and per_page.

Search result object

Each video in the results contains a list of matching segments:

1
{
2
  "video_id": "vid_abc123",
3
  "filename": "footage.mp4",
4
  "collection_id": "col_xyz",
5
  "segments": [
6
    {
7
      "timestamp_start": 42.5,
8
      "timestamp_end": 47.0,
9
      "score": 0.91,
10
      "type": "visual",
11
      "text_content": "Hey everyone, welcome back!",
12
      "video_url": "https://...",
13
      "thumbnail_url": "https://..."
14
    }
15
  ]
16
}

Credits

Each search request consumes 1 credit on Pro accounts. Free accounts have a daily search quota of 10.

Rate limits

30 requests per minute per API key. See Rate Limits.