evidence

Queue still-frame evidence for a composition

Resolve and freeze the exact authored target, then queue durable still capture. Returns immediately; poll the generic job with wait_job(kind='preview_frame'). One successful request is one compose_capture operation regardless of timestamp count.

post/v1/projects/{id}/preview-frame-jobs

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/projects/{id}/preview-frame-jobs
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.cueframe.ai/api/auth/mcp/authorize, token URL https://api.cueframe.ai/api/auth/mcp/token, scopes: projects:write)
    • API key in header PAYMENT-SIGNATURE

Path parameters

idstring required

Request body

compositionunknown
compositionIdstring

Preview a SPECIFIC persisted composition of this project (create_render parity). Absent ⇒ the active one. A stale/foreign id is a 404 — never a silent fall-through.

session_idstring

Compose-session id: render that session's SCRATCH composition (what the session has been editing) instead of the active row. Ignored when composition is passed.

timestampsnumber[] required

Composition seconds to capture, 18 per request. The batch renders as ONE unit of work — one warm container, one source decode, N seeks — and that unit has a fixed time budget, so a larger batch is refused here rather than accepted and timed out minutes later. For a denser sweep, split it across calls; identical beats are served from the still cache, so overlapping batches are cheap.

imageFormat'png' | 'jpeg'

Still format. Default jpeg — these pixels go to a vision model, where jpeg is equivalent and png costs multiples in bytes to store and move. Pass png only when you need full fidelity.

scalenumber

Render scale 0.1–1. Default 0.5, which is what this schema has always recommended for vision-bound looks. Pass 1 when judging fine detail — it costs ~4x the vision tokens.

jpegQualityinteger

JPEG quality (jpeg only). Default 70 — the quality the eval panel grades at.

Example request

{
  "timestamps": [
    1.5,
    4
  ],
  "imageFormat": "jpeg"
}

Response

Preview-frame job queued.

jobIdstring required

Poll GET /v1/jobs/{jobId} / wait_job until terminal.

jobKeystring required

Deterministic identity of the work (content hash of every input the result depends on). Re-enqueueing the same key returns the same job while it runs; a failed key revives as a fresh attempt.

kindstring required

Job family, e.g. verify | preview | brand_kit_extract.

status'running' | 'succeeded' | 'cancelled' required

running on a fresh/deduped enqueue; succeeded when an identical request already completed. Cancelled is part of the shared status vocabulary; identical cancelled work revives to running.

Changes

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