@primate-intelligence/sdk

Official TypeScript SDK for the Primate Vision API by Primate Intelligence — video scene understanding: upload a video, ask a question, get a deterministic answer with confidence and clip timestamps.

Status: built in-repo from the OpenAPI spec (GET /v1/openapi.json). Not yet published to npm — install from the repo or via npm pack until the first public release.

Install

npm install @primate-intelligence/sdk

Requires Node 20+.

Quickstart

import Primate from '@primate-intelligence/sdk';

const client = new Primate(); // reads PRIMATE_API_KEY from the environment

// URL ingest → analyze → wait, in three lines
const video = await client.videos.create({ url: 'https://example.com/clip.mp4' });
const analysis = await client.analyses.createAndWait({
  video_id: video.id,
  prompt: 'Is there a person in this video?',
});
console.log(analysis.result?.answer, analysis.result?.confidence);

Get a free test key with no signup:

curl -X POST https://api.primateintelligence.ai/v1/sandbox

Features

• Typed resources for the full /v1 surface: videos, analyses, streams, client_tokens, models, usage, errors, webhook_endpoints.
• Automatic retries driven by the error registry retryable flags + Retry-After.
• Auto idempotency keys (UUIDv4) on all create calls — safe to retry network failures.
• createAndWait() — create an analysis and block until a terminal state (uses Prefer: wait server-side, then polls).
• videos.upload() — create + presigned S3 PUT + complete, in one call.
• Pagination iterators — for await (const v of client.videos.iter()) { … }.
• Webhook verification — verifyWebhook() implements Standard Webhooks with constant-time compare + replay-window checks.
• connectStream() (browser entrypoint @primate-intelligence/sdk/browser) — full WebRTC streaming handshake against /v1/streams.

Error handling

import Primate, { PrimateError } from '@primate-intelligence/sdk';

try {
  await client.analyses.create({ video_id: 'video_x', prompt: 'hi' });
} catch (err) {
  if (err instanceof PrimateError) {
    console.error(err.code, err.status, err.requestId, err.docsUrl);
    if (err.code === 'insufficient_credits') {
      const usage = await client.usage.retrieve();
      // → prompt the account owner to top up or enable auto-refill
    }
  }
}

Every error carries code, status, request_id, and a docs_url anchor into the error registry. Retryable codes are retried automatically before the error reaches you.

Webhooks

import { verifyWebhookRequest } from '@primate-intelligence/sdk';

app.post('/webhooks/primate', { config: { rawBody: true } }, (req, reply) => {
  verifyWebhookRequest({
    secret: process.env.PRIMATE_WEBHOOK_SECRET!, // whsec_…
    headers: req.headers,
    rawBody: req.rawBody,
  }); // throws on bad signature / stale timestamp
  // dedupe on the webhook-id header — delivery is at-least-once
  reply.code(204).send();
});

Browser streaming

import { connectStream } from '@primate-intelligence/sdk/browser';

// Your server mints { stream, client_token } — see docs/guides/security-model
const session = await connectStream({
  stream,
  clientToken,                       // pvct_… — NEVER a secret key in the browser
  mediaStream: await navigator.mediaDevices.getUserMedia({ video: true }),
  onResult: (r) => render(r.detections),
  onWarning: (remaining) => showCountdown(remaining),
});
// later: session.end();

Configuration

| Option | Env var | Default | |---|---|---| | apiKey | PRIMATE_API_KEY | — (required) | | baseUrl | PRIMATE_BASE_URL | https://api.primateintelligence.ai | | maxRetries | — | 3 | | timeoutMs | — | 60000 |

Regeneration

Types + retry tables are generated from the API's single sources of truth (npm run sdk:artifacts in the repo root). This SDK is structured so a Stainless-generated client can replace the internals without changing the public import surface.