PreviewFrameRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cueframe-ai/json-schema/cueframe-ai-preview-frame-request-schema.json",
  "title": "PreviewFrameRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cueframe-ai-evidence-api-openapi.yml#/components/schemas/PreviewFrameRequest",
  "type": "object",
  "properties": {
    "composition": {
      "description": "The composition to render. Absent ⇒ the project's ACTIVE composition — what create_render will encode. The response's `previewed.source` names what was rendered."
    },
    "compositionId": {
      "description": "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.",
      "type": "string"
    },
    "session_id": {
      "description": "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.",
      "type": "string"
    },
    "timestamps": {
      "minItems": 1,
      "maxItems": 18,
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "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": {
      "description": "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.",
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ]
    },
    "scale": {
      "description": "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.",
      "type": "number",
      "minimum": 0.1,
      "maximum": 1
    },
    "jpegQuality": {
      "description": "JPEG quality (jpeg only). Default 70 — the quality the eval panel grades at.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "timestamps"
  ],
  "additionalProperties": false
}