Upload & Processing

Pureframe processes videos asynchronously. You upload a file, get a job_id back immediately, and poll for status while the pipeline runs in the background.

Accepted formats

Maximum file size is 5 GB per upload.

Uploading a video

collection_id is required — a video must belong to a collection. Create one first if you haven’t already.

$
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 both job_id (for tracking progress) and video_id (for searching and managing the video later).

Job status

Poll GET /v1/jobs/{job_id} until status is done or failed.

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

1
{
2
  "data": {
3
    "job_id": "job_xyz789",
4
    "status": "processing",
5
    "progress_pct": 64
6
  }
7
}

Status values

Polling recommendation

Use exponential backoff. For most videos, check at 5s, 10s, 20s intervals:

1
import time, httpx
2
3
def wait_for_job(job_id: str, api_key: str) -> dict:
4
    headers = {"Authorization": f"Bearer {api_key}"}
5
    delay = 5
6
    while True:
7
        resp = httpx.get(
8
            f"https://api.pureframe.ai/v1/jobs/{job_id}",
9
            headers=headers
10
        ).json()
11
        status = resp["data"]["status"]
12
        if status in ("done", "failed"):
13
            return resp["data"]
14
        time.sleep(delay)
15
        delay = min(delay * 2, 60)

Processing time

Typical processing time is 1–3 minutes per 10 minutes of video. Actual time depends on server load and video complexity.

What happens during processing

1. Frame extraction — frames are extracted at regular intervals throughout the video
2. Visual embedding — each frame is encoded into a vector used for visual search
3. Speech transcription — spoken audio is transcribed and aligned to timestamps
4. Indexing — all vectors and transcripts are indexed for fast retrieval

Once the job is done, the video is fully searchable.

Deleting a video

$
curl -X DELETE https://api.pureframe.ai/v1/videos/vid_def456 \
>
  -H "Authorization: Bearer pf_key_..."

Permanently removes the video file, all frame data, and indexed segments. Returns 204 No Content. This cannot be undone.