streams

Create a real-time analysis stream

Returns the signaling WS URL, ephemeral ICE servers, and session limits. Signaling protocol v1: join → ready|queued(position) → offer/answer/ice → live; mid-stream update_prompt {prompt} (client→server; server confirms with prompt_updated), metering (5s ticks), warning, end {reason}. WS auth: ?token= accepts a client token (pvct_) or first-party session JWT — never a secret key. Billed per second of live clock time (join/negotiation free) from the same credit ledger as uploads. options.narrative: true adds (a) a narrative_update object ({t_s, text}) to result-frame detections whenever the engine emits a new sentence — event-driven, absent otherwise — and (b) an additive server→client status event {type: "status", status: "prompt_context"|"combined_prompt"|"recalculating", message?} for ordering/annotating narrative entries (closed vocabulary; non-opted-in streams never receive status events). No extra cost.

post/v1/streams

Request

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

Headers

Idempotency-Keystring

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

Request body

promptstring

Free text — compiled server-side. Exactly one of prompt/query.

queryobject

Structured CompiledQuery JSON.

modelstring
recordingboolean

PRI-496: true — opt into retrieval of the server-side session recording. The ended stream then carries recording: {status} and GET /v1/streams/{id}/recording returns a signed 1h playback URL (raw H.264 elementary stream; lossless remux: ffmpeg -i in.h264 -c copy out.mp4). Default false.

metadataobject

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

Example request

{
  "model": "Darwin-preview-1.3B"
}

Response

Stream created (queued or ready). Response carries signaling.url + ice_servers + limits.

idstring required

Stream resource id (prefixed ULID). P6 §4.8.

object'stream' required
status'queued' | 'ready' | 'live' | 'ended' required

Stream lifecycle state (§4.8): queued → ready → live → ended. Terminal immutable.

metering_rule'per_second' | 'per_frame'

PRI-552: settlement rule pinned at create time. Streams created before the cutover report per_second.

end_reason'completed' | 'canceled' | 'insufficient_credits' | 'error' | 'timeout' | 'ice_failed' | 'media_timeout' nullable required

Why the stream ended. completed — normal end after live. canceled — ended before going live (client action). insufficient_credits — balance exhausted. error — server-side failure. timeout — max_session_s cutoff. ice_failed — WebRTC ICE never connected (see failure_diagnostic). media_timeout — connected but no media/results within the first-frame window. A stream that never went live is never completed.

promptstring nullable required
queryobject nullable required
modelstring required
queue_positioninteger nullable required
estimated_start_sinteger nullable required
ice_serversobject[] nullable required
duration_sinteger nullable required

Live-clock duration. Terminal only.

results_summaryobject nullable required

Terminal summary: {result_frames, frames (deprecated alias of result_frames — removed ~2026-08-28), last_detections}. result_frames counts result EVENTS emitted (results are sampled, not per-source-frame). Detection rows use the same enums/casing as the file-API result contract (answer: yes|no|indeterminate, lowercase; prompt echoed exactly as submitted).

failure_diagnosticobject nullable required

Present when end_reason is ice_failed (and some media_timeout cases): ICE candidate summary from the server side — {local_candidates: string[], hint}. Use it to distinguish "server advertised only private/host candidates" from "client could not reach relay".

metadataobject

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

created_atstring date-time required
live_started_atstring date-time nullable required
ended_atstring date-time nullable required

Example response

{
  "id": "st_01KX12XX3BNM688AWHX7406HCF",
  "model": "Darwin-preview-1.3B",
  "signaling": {
    "url": "wss://api.primateintelligence.ai/v1/streams/st_01KX…/signal",
    "expires_at": "2026-07-08T14:00:00Z"
  },
  "created_at": "2026-07-08T14:00:00Z",
  "live_started_at": "2026-07-08T14:00:00Z",
  "ended_at": "2026-07-08T14:00:00Z"
}

Changes

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