Uploads

Pure Frame 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_..." \
>
  -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_..."

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)

Deleting a video

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

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

Next steps

See Video Processing for what happens inside the pipeline while your job is processing.