analyses

Create an analysis (video × prompt × model)

Async by default: 202 + poll. Prefer: wait=<s> (≤120) blocks and returns the terminal resource when it finishes in time. Test-mode keys (pv_test_) return deterministic canned results with no GPU time and no credit burn. Set validate_only: true to dry-run a prompt — returns an AnalysisPreview with cost/assessability and creates nothing.

post/v1/analyses

Request

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

Headers

Idempotency-Keystring

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

Preferstring

wait=<seconds> (cap 120)

Request body

video_idstring required

Video resource id (prefixed ULID). Immutable.

promptstring

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

queryobject

Structured CompiledQuery JSON (schema at /v1/schemas/compiled-query.json).

modelstring

Defaults to latest (currently Darwin-preview-1.3B, status preview); deprecated aliases (e.g. darwin-1.3) are accepted case-insensitively; response always echoes the canonical id.

metadataobject

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

validate_onlyboolean

Dry run (PRI-480). Compiles the prompt, reports whether the query is assessable, and estimates duration/cost — WITHOUT creating an analysis, touching the GPU, or burning credits. Returns an AnalysisPreview (object: "analysis_preview") with 200, not an Analysis. Use it to check a prompt before paying for it.

Example request

{
  "video_id": "video_01KX12XX3BNM688AWHX7406HCF",
  "model": "Darwin-preview-1.3B",
  "validate_only": true
}

Response

Terminal resource (Prefer: wait satisfied, or test mode) — OR an AnalysisPreview when validate_only:true was sent. Discriminate on the object field.

OR

Example response

{
  "id": "an_01KX12XX3BNM688AWHX7406HCF",
  "video_id": "video_01KX12XX3BNM688AWHX7406HCF",
  "model": "Darwin-preview-1.3B",
  "result": {
    "unsupported_action": {
      "reason": "unsupported_query_form",
      "docs_url": "https://primateintelligence.ai/docs/supported-actions"
    }
  },
  "artifacts": {
    "expires_at": "2026-07-08T14:00:00Z"
  },
  "error": {
    "code": "video_unreadable"
  },
  "created_at": "2026-07-08T14:00:00Z",
  "started_at": "2026-07-08T14:00:00Z",
  "completed_at": "2026-07-08T14:00:00Z"
}

Changes

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