FAQ
FAQ
Getting started
Do I need to create a collection before uploading?
Yes. Every video must belong to a collection. Create one with POST /v1/collections first, then pass its id as collection_id in the upload request.
How do I get an API key?
Go to console.pureframe.ai/settings/api-keys, click New Key, and copy it. Keys are only shown once.
Upload & processing
What video formats are supported?
MP4, MOV, AVI, WebM, MPEG, and MKV. Maximum file size is 5 GB per upload.
How long does indexing take?
Typically 1–3 minutes per 10 minutes of video, depending on server load. Poll GET /v1/jobs/{job_id} to track progress. Use the progress_pct field for a live percentage.
Can I search a video before it finishes processing?
No. The video is only searchable once its job status reaches done. Searching before that will return no results for that video.
What happens if processing fails?
The job status will be failed. Re-upload the video to create a new job. If failures persist, contact support.
Search
Can I search across all my videos at once?
Yes. Omit collection_id from the search request to search your entire library.
What does thumbnail_base64 contain?
A base64-encoded JPEG image of the matched video frame. Vision-capable models (Claude, GPT-4o, Gemini) can consume it directly in the same API call without fetching a URL. It’s designed for agent integrations where the model needs to see the frame immediately.
Why are presigned URLs only valid for ~1 hour?
video_url and thumbnail_url are short-lived presigned URLs for security. Don’t store them — store the video_id and re-fetch the URL when you need to display or stream it.
What’s the difference between video and transcript search modes?
video searches visual frame embeddings — what appears on screen. transcript searches transcribed speech — what was said. Both are active by default. Use modes=["transcript"] to search only spoken content, or modes=["video"] to search only visuals.
Agent Vision
Which AI clients support the Pureframe MCP server?
Claude Desktop, Claude Code, Claude.ai (via remote MCP), Cursor, and Windsurf. Any client that supports MCP 1.0 should work.
Do I need to install anything for remote MCP?
No. The remote MCP server at https://mcp.pureframe.ai runs on Pureframe’s infrastructure. Just add the URL and your API key to your client config.
Billing
How are credits consumed?
Each search request consumes 1 credit on Pro accounts. Video processing costs $0.02 per minute of video. Free accounts have a daily search quota of 10 and 100 MB of storage — no credits needed.
What happens when I run out of credits?
Searches return a 402 with code INSUFFICIENT_CREDITS. Add credits from the Billing page or enable auto top-up.
FrameMap
Why are all my frames showing as “Uncategorized”?
This usually means the FrameMap was computed before clustering data was available, or with too few videos. Click Recompute in the left panel to regenerate.
How many videos do I need for meaningful clusters?
At least 20–30 indexed videos. Clusters become more useful and stable as your library grows.
