Pureframe AI API Documentation

Search
Agent Vision

Prerequisites

You’ll need an API key. Get one at API Platform.All examples use curl. Swap in your own key where you see pf_....

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_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My footage" }'

{
  "data": {
    "id": "col_abc123",
    "name": "My footage",
    "video_count": 0,
    "created_at": "2025-01-01T12:00:00Z"
  }
}

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_..." \
  -F "collection_id=col_abc123" \
  -F "file=@footage.mp4"

{
  "data": {
    "job_id": "job_xyz789",
    "video_id": "vid_def456",
    "status": "queued"
  }
}

Save the job_id.

Step 3: Wait for indexing

Poll until status is done. Processing time varies by video.

curl https://api.pureframe.ai/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer pf_..."

{
  "data": {
    "job_id": "job_xyz789",
    "status": "done",
    "progress_pct": 100
  }
}

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

Step 4: Search

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

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

{
  "data": [
    {
      "video_id": "vid_def456",
      "filename": "footage.mp4",
      "segments": [
        {
          "timestamp_start": 42.5,
          "timestamp_end": 47.0,
          "score": 0.91,
          "type": "frame",
          "text_content": "Hey everyone, welcome back!",
          "video_url": "https://...",
          "thumbnail_url": "https://...",
          "rank": 0
        }
      ]
    }
  ],
  "meta": { "total": 1 }
}

Each result gives you:

Field	Description
`timestamp_start` / `timestamp_end`	Where in the video this moment occurs (seconds)
`score`	Relevance from 0 to 1
`type`	Matching signal: `frame`, `transcript`, `scene`, or `ocr`
`text_content`	Transcribed speech in this clip, if any
`video_url`	Presigned URL to stream the video (valid ~1 hour)
`thumbnail_url`	Presigned URL to the matched frame image
`rank`	Position within the result page

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_..." \
  -F "image=@reference.jpg"

Or supply a public image URL:

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

Prerequisites

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

Option A: Local MCP

Install the Pureframe AI MCP server into your AI client in one step.Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pureframe": {
      "command": "npx",
      "args": ["-y", "@pureframeai/mcp"],
      "env": { "PUREFRAME_API_KEY": "pf_..." }
    }
  }
}

Claude Code: run once:

claude mcp add pureframe -- npx -y @pureframeai/mcp

Restart your client. The agent can now call search_videos, list_collections, get_collection, and get_video directly.

Option B: Remote MCP (no install)

For Claude.ai or another client that supports remote MCP endpoints:

{
  "mcpServers": {
    "pureframe": {
      "url": "https://mcp.pureframe.ai",
      "headers": { "Authorization": "Bearer pf_..." }
    }
  }
}

Option C: Function calling (Python)

Fetch the OpenAI-compatible schema and pass it to a model provider that supports function calling:Set ANTHROPIC_MODEL to a model available to your Anthropic account.

import os

import anthropic
import httpx

pf_headers = {"Authorization": "Bearer pf_..."}

# Get the tool schema
schema = httpx.get(
    "https://api.pureframe.ai/v1/agent/schema.json",
    headers=pf_headers
).json()

# Ask Claude to use Pureframe AI tools
client = anthropic.Anthropic()
response = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    tools=schema,
    messages=[{"role": "user", "content": "Find clips of the presenter showing a demo"}]
)

When the model calls search_videos, execute it:

import json

for block in response.content:
    if block.type == "tool_use" and block.name == "search_videos":
        result = httpx.post(
            "https://api.pureframe.ai/v1/agent/call",
            headers=pf_headers,
            json={"tool": "search_videos", "input": block.input}
        ).json()
        # result["data"] contains clips with thumbnail_base64

thumbnail_base64 is a base64 JPEG you can pass to a vision-capable model that accepts inline image data.

Next steps

Search

Search modes, multimodal inputs, and pagination.

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.

Get Started

Search

Video Processing

Agents

Production

Resources

Quickstart

Prerequisites

Step 1: Create a collection

Step 2: Upload a video

Step 3: Wait for indexing

Step 4: Search

Step 5: Search with an image

Prerequisites

Option A: Local MCP

Option B: Remote MCP (no install)

Option C: Function calling (Python)

Next steps

Search

Collections

Agent Vision

API Reference

​Prerequisites

​Step 1: Create a collection

​Step 2: Upload a video

​Step 3: Wait for indexing

​Step 4: Search

​Step 5: Search with an image

​Prerequisites

​Option A: Local MCP

​Option B: Remote MCP (no install)

​Option C: Function calling (Python)

​Next steps

Search

Collections

Agent Vision

API Reference

Prerequisites

Step 1: Create a collection

Step 2: Upload a video

Step 3: Wait for indexing

Step 4: Search

Step 5: Search with an image

Prerequisites

Option A: Local MCP

Option B: Remote MCP (no install)

Option C: Function calling (Python)

Next steps