# Primate Vision API — Primate Intelligence

> Video scene understanding API. Upload a video (or point at a URL), ask a question in plain English, get a deterministic answer with confidence and clip timestamps — no hallucinations. Zero-touch provisioning: `POST https://api.primateintelligence.ai/v1/sandbox` returns an instant free test key (no email, no card).

Start here (agents): [Quickstart for AI agents](https://primateintelligence.ai/docs/agents.md)

## Machine-readable surfaces

- [OpenAPI 3.1 spec](https://api.primateintelligence.ai/v1/openapi.json): the full API contract — source of truth
- [Error registry](https://api.primateintelligence.ai/v1/errors): every error code with retryable/idem flags
- [Test fixture](https://api.primateintelligence.ai/v1/test-fixture): stable video + prompt + expected answer for CI self-verification
- [Credit pricing](https://api.primateintelligence.ai/v1/credit-pricing): current pricing, public

## Integration contract

- Base URL: `https://api.primateintelligence.ai` · Auth: `Authorization: Bearer $PRIMATE_API_KEY`
- Env var: `PRIMATE_API_KEY` (both SDKs + MCP server read it; keys never go in URLs or tool arguments)
- Core loop: `POST /v1/videos` → `POST /v1/analyses` → `GET /v1/analyses/{id}` (or `Prefer: wait=60` to collapse the poll)
- SDKs: `npm install @primate-intelligence/sdk` · `pip install primate-intelligence`
- MCP server: `npx @primate-intelligence/mcp` (env: PRIMATE_API_KEY)

## Docs

- [Quickstart](https://primateintelligence.ai/docs/quickstart.md): First analysis in three curl commands — no signup required.
- [Quickstart for AI agents](https://primateintelligence.ai/docs/agents.md): The zero-human-intervention integration path — discover, provision, integrate, self-verify.
- [Uploading video](https://primateintelligence.ai/docs/guides/uploading.md): Three ways to get video in — presigned upload, URL ingest, SDK helper — and how to choose.
- [Prompts & queries](https://primateintelligence.ai/docs/guides/prompts.md): Free-text prompts vs structured queries, what's answerable, and how unassessable components behave.
- [Waiting for results](https://primateintelligence.ai/docs/guides/waiting.md): Poll vs Prefer: wait vs webhooks — pick the right completion strategy.
- [Webhooks](https://primateintelligence.ai/docs/guides/webhooks.md): Standard Webhooks signing, verification, retries, redelivery, and the integration rules that matter.
- [Errors & retries](https://primateintelligence.ai/docs/guides/errors-retries.md): The error envelope, the closed registry, and exactly what to retry.
- [Rate limits & quotas](https://primateintelligence.ai/docs/guides/rate-limits.md): Limit classes, headers, 429 handling, and how quotas differ from rate limits.
- [Test mode](https://primateintelligence.ai/docs/guides/test-mode.md): pv_test_ keys, deterministic fixtures, and CI verification without burning quota.
- [Versioning & deprecation](https://primateintelligence.ai/docs/guides/versioning.md): Compatibility guarantees, deprecation process, model sunsets, and service expectations.
- [Security model](https://primateintelligence.ai/docs/guides/security-model.md): API keys, client tokens, scopes, data handling, and the key-compromise procedure.
- [Billing & credits](https://primateintelligence.ai/docs/guides/billing.md): Credit-seconds, grants, auto-refill, and handling insufficient_credits in code.
- [Streaming](https://primateintelligence.ai/docs/guides/streaming.md): Real-time video analysis over WebRTC — create, signal, go live, get per-frame results.
- [Tutorial: build from scratch](https://primateintelligence.ai/docs/guides/build-from-scratch.md): Zero to a working video-question CLI in ~15 minutes — no account required to start.
- [Error registry](https://primateintelligence.ai/docs/errors.md): Every error code with retry semantics — the docs_url targets.
- [Changelog](https://primateintelligence.ai/docs/changelog.md): Dated, typed API changes. Subscribe via RSS at /docs/changelog.xml.

## Full corpus

- [llms-full.txt](https://primateintelligence.ai/llms-full.txt): every docs page in one file