primate-intelligence 0.1.0

Official Python SDK for the Primate Vision API (Primate Intelligence). Video scene understanding: upload, analyze, stream.

primate-intelligence

Official Python 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 PyPI — install from the repo until the first public release.

Install

pip install primate-intelligence

Requires Python 3.10+.

Quickstart

from primate_intelligence import Primate

client = Primate()  # reads PRIMATE_API_KEY from the environment

video = client.videos.create(url="https://example.com/clip.mp4")
analysis = client.analyses.create_and_wait(
    video_id=video["id"],
    prompt="Is there a person in this video?",
)
print(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 resource namespaces 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.
• create_and_wait() — 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 video in client.videos.iter(): ….
• Webhook verification — verify_webhook() implements Standard Webhooks with constant-time compare + replay-window checks.

Error handling

from primate_intelligence import Primate, PrimateError

client = Primate()
try:
    client.analyses.create(video_id="video_x", prompt="hi")
except PrimateError as err:
    print(err.code, err.status, err.request_id, err.docs_url)
    if err.code == "insufficient_credits":
        usage = 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 exception reaches you.

Webhooks

from primate_intelligence import verify_webhook_request

@app.post("/webhooks/primate")
async def receive(request: Request):
    raw = await request.body()
    verify_webhook_request(
        secret=os.environ["PRIMATE_WEBHOOK_SECRET"],  # whsec_…
        headers=dict(request.headers),
        raw_body=raw,
    )  # raises ValueError on bad signature / stale timestamp
    # dedupe on the webhook-id header — delivery is at-least-once
    return Response(status_code=204)

Configuration

Kwarg	Env var	Default
api_key	PRIMATE_API_KEY	— (required)
base_url	PRIMATE_BASE_URL	https://api.primateintelligence.ai
max_retries	—	3
timeout_s	—	60.0