FramesRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ffpipe-dev/json-schema/ffpipe-dev-frames-request-schema.json",
  "title": "FramesRequest",
  "description": "EXACTLY ONE of `sourceUrl` or `upload: true` is required, plus `mode`. Every number must be a JSON number, not a string. Validation runs before any charge, including the parameter each mode needs.",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ffpipe-dev-openapi.json#/components/schemas/FramesRequest",
  "type": "object",
  "required": [
    "mode"
  ],
  "additionalProperties": true,
  "properties": {
    "sourceUrl": {
      "$ref": "#/$defs/SourceUrl"
    },
    "upload": {
      "$ref": "#/$defs/UploadFlag"
    },
    "mode": {
      "type": "string",
      "enum": [
        "all",
        "every_nth",
        "interval",
        "keyframes",
        "evenly_spaced",
        "timestamps"
      ],
      "description": "How to pick frames. Required - there is no default, because every possible one implies a sampling rate you did not ask for. `all` every frame; `every_nth` every Nth decoded frame (needs `n`); `interval` a fixed rate in seconds (needs `fps`, may be below 1); `keyframes` keyframes only (cheap on long sources); `evenly_spaced` N samples across the window (needs `count`); `timestamps` one frame per given second (needs `timestamps`). Every mode is bounded by `maxFrames` (1000): `all` and `interval` on a long source, and `keyframes` on a dense one, can exceed it - the job then fails fast and, being our own limit rather than your mistake, earns the usual retry voucher. For long inputs prefer `interval`, `evenly_spaced` or `timestamps`."
    },
    "n": {
      "type": "integer",
      "minimum": 1,
      "description": "`every_nth` only: keep every Nth DECODED frame. This is a frame index, not a time - on a variable-frame-rate source the spacing in seconds varies."
    },
    "fps": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 120,
      "description": "`interval` only: frames per second, framerate-independent. May be below 1 - `0.5` is one frame every two seconds."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "`evenly_spaced` only: how many frames to spread across the window."
    },
    "timestamps": {
      "type": "array",
      "items": {
        "type": "number",
        "minimum": 0
      },
      "maxItems": 1000,
      "description": "`timestamps` only: seconds into the source, one accurate frame each. Sorted for you. A timestamp at or past the end of the media fails the job."
    },
    "startTime": {
      "type": "number",
      "minimum": 0,
      "description": "Window start in seconds (0 = from the beginning). Applies to every mode."
    },
    "endTime": {
      "type": "number",
      "minimum": 0,
      "description": "Window end in seconds (0 = to the end). Must be greater than `startTime`; past the end of the media it is clamped."
    },
    "maxOutputWidth": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4096,
      "description": "Fit box width for each frame, applied to the source's DISPLAY dimensions: aspect preserved, never upscaled, oriented to the input (a portrait clip given 1920x1080 yields 1080x1920). 0 = no limit on this axis."
    },
    "maxOutputHeight": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4096,
      "description": "Fit box height. Same rules as `maxOutputWidth`."
    },
    "format": {
      "type": "string",
      "enum": [
        "jpeg",
        "jpg",
        "webp",
        "png"
      ],
      "default": "jpeg",
      "description": "Image format of each frame. `jpeg` (default) is small and accepted by every vision API; `png` is lossless; `webp` splits the difference. `jpg` is accepted as a spelling of `jpeg`."
    },
    "quality": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 85,
      "description": "Encoder quality for `jpeg`/`webp`; ignored for the lossless `png`."
    },
    "maxFrames": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 1000,
      "description": "Ceiling on how many frames this job may produce, and also the hard limit: 1000 frames is what one job's flat price covers. A request whose sampling would exceed it fails before any decoding, with the predicted count in the message."
    }
  },
  "$defs": {
    "SourceUrl": {
      "type": "string",
      "format": "uri",
      "description": "https URL we fetch the input from. Rejected before any charge if it is not https, is an IP literal, or resolves to a localhost/.internal/.local name; redirects are followed (max 3) and every hop is re-checked. We fetch from datacenter IP ranges - hosts that block datacenter egress will fail with `ingest_failed`, so prefer a presigned URL from storage you control. Body size cap: 100 MiB by default, enforced while streaming."
    },
    "UploadFlag": {
      "type": "boolean",
      "const": true,
      "description": "Push intake: instead of a `sourceUrl`, reserve an upload window and PUT the raw bytes (<= 100 MiB, same cap) to the `uploadUrl` in the 202 before `uploadExpiresAt`. You are charged at the 202, before any bytes move: letting the window expire is a terminal `error` with no refund; a pipeline failure after your upload earns a `retryVoucher`."
    }
  }
}