videos

Create a video (presigned upload or URL ingest)

post/v1/videos

Request

Base URL: https://api.primateintelligence.ai
URL: https://api.primateintelligence.ai/v1/videos
Auth: HTTP bearer

Headers

Idempotency-Keystring

§16.1: first request wins; 24h replay window; same key + different body → 409 idempotency_key_reused.

Request body

filenamestring

content_type'video/mp4' | 'video/quicktime'

Required in presigned mode.

size_bytesinteger

urlstring uri

URL-ingest mode: https-only, SSRF-guarded (§18.2). Mutually exclusive with filename/size_bytes.

metadataobject

Free-form key/value metadata. ≤16 keys, key ≤40 chars [a-zA-Z0-9_.-], value ≤500 chars.

Response

Video created. Presigned mode → status awaiting_upload with upload instructions; URL mode → status processing (async fetch).

idstring required

Video resource id (prefixed ULID). Immutable.

object'video' required

livemodeboolean required

true when the request used a live key; false for test keys and sandbox. Stripe-style.

status'awaiting_upload' | 'processing' | 'ready' | 'failed' required

Video lifecycle state (§14.1).

filenamestring nullable required

size_bytesinteger nullable required

duration_snumber nullable required

widthinteger nullable required

heightinteger nullable required

fpsnumber nullable required

content_type'video/mp4' | 'video/quicktime' required

source'upload' | 'url' required

metadataobject

Free-form key/value metadata. ≤16 keys, key ≤40 chars [a-zA-Z0-9_.-], value ≤500 chars.

expires_atstring date-time nullable required

created_atstring date-time required

Example response

{
  "id": "video_01KX12XX3BNM688AWHX7406HCF",
  "upload": {
    "expires_at": "2026-07-08T14:00:00Z"
  },
  "media": {
    "expires_at": "2026-07-08T14:00:00Z"
  },
  "error": {
    "code": "video_unreadable"
  },
  "expires_at": "2026-07-08T14:00:00Z",
  "created_at": "2026-07-08T14:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.