> ## Documentation Index > Fetch the complete documentation index at: https://docs.getjumper.io/llms.txt > Use this file to discover all available pages before exploring further. # Get detected scenes for videos > Returns the scenes Jumper detected during visual analysis with the current visual model, in source seconds and source timecode. Scenes are contiguous: each one starts where the previous one ends. - Scene times are on the 1 FPS visual analysis grid, so they have 1-second resolution. `end_seconds` and `end_timecode` are exclusive: a scene ends just before them, where the next scene starts. - The last scene ends at `frame_count` / `fps` instead of at the next whole second, rounded to milliseconds. - `fps` is the nominal (rounded) frame rate, and seconds count timecode seconds: for 29.97 fps media, second N starts at frame N × 30. A file with 4522 frames at 29.97 fps ends its last scene at 150.733 timecode seconds, while it plays for 150.88 seconds. - Timecodes add the seconds to the file's `start_timecode` at `fps`. They are null when the frame rate is unknown. - Videos without visual analysis for the current visual model are listed in `missing_visual_analysis`. Images, audio-only files, and files Jumper can't read are left out of both. ## OpenAPI ````yaml /api-reference/openapi-v1.yaml post /media/scenes openapi: 3.0.3 info: title: Jumper Public API version: '1.0' description: > REST API for third-party integrations with Jumper's media analysis engine. Jumper analyzes video, image, and audio files — enabling semantic visual search, speech transcription, face detection with clustering, and hierarchical summaries. This API exposes those capabilities for use by MAM systems, automation pipelines, and custom tooling. ## Authentication All endpoints except `/health` require a **Jumper Pro** license key. The OpenAPI contract models the supported `X-License-Key` header flow. Jumper also accepts a `license_key` field in many JSON POST bodies as a convenience, but that is a Jumper-specific request-body convention rather than an OpenAPI security scheme. A non-empty JSON `license_key` takes precedence over the header. Send the raw license key on every authenticated request. Activating Jumper in the UI does not authenticate later API requests automatically. Pro uses the same entitlements in the UI and API; no separate API entitlement is needed. Missing keys return `401`. Supplied keys that cannot be validated or lack Pro entitlements return `403`. The `error` is `Jumper Pro license required` for both cases; inspect the response `message` for the validation reason. A valid non-Pro key can have `message: "OK"` and still return `403`. Enterprise policy denials also return `403`, with a `policy_error` field. Successful validation can be cached for 30 minutes. Health only checks connectivity and does not validate a license. The API is local to the machine running Jumper; use `localhost` or `127.0.0.1`. ## Key Concepts - **`cache_dir`** — The folder where Jumper stores analysis data (visual analysis, transcriptions, face clusters). You choose this path. - **`media_paths`** — Absolute filesystem paths to media files. Jumper needs direct access to these files. - **`hash_str`** — A backend-issued media identity returned by the metadata endpoint. Computed with xxh64 from the file size and sampled head/tail bytes; it is not a full-file integrity checksum. - **`model_key`** — Internal identifier for a visual or speech analysis model variant (e.g. `v2-medium-256`). contact: name: Jumper url: https://getjumper.io servers: - url: http://localhost:6699/api/v1 description: Local Jumper backend security: - HeaderAuth: [] paths: /media/scenes: post: tags: - Media summary: Get detected scenes for videos description: > Returns the scenes Jumper detected during visual analysis with the current visual model, in source seconds and source timecode. Scenes are contiguous: each one starts where the previous one ends. - Scene times are on the 1 FPS visual analysis grid, so they have 1-second resolution. `end_seconds` and `end_timecode` are exclusive: a scene ends just before them, where the next scene starts. - The last scene ends at `frame_count` / `fps` instead of at the next whole second, rounded to milliseconds. - `fps` is the nominal (rounded) frame rate, and seconds count timecode seconds: for 29.97 fps media, second N starts at frame N × 30. A file with 4522 frames at 29.97 fps ends its last scene at 150.733 timecode seconds, while it plays for 150.88 seconds. - Timecodes add the seconds to the file's `start_timecode` at `fps`. They are null when the frame rate is unknown. - Videos without visual analysis for the current visual model are listed in `missing_visual_analysis`. Images, audio-only files, and files Jumper can't read are left out of both. requestBody: required: true content: application/json: schema: type: object required: - cache_dir - media_paths properties: cache_dir: type: string description: Analysis folder to read visual analysis from media_paths: type: array items: type: string description: Video files to read scenes for responses: '200': description: Scenes keyed by each path exactly as sent content: application/json: schema: type: object required: - media_scenes - missing_visual_analysis properties: media_scenes: type: object description: Keyed by each path exactly as sent. additionalProperties: type: object properties: hash_str: type: string fps: type: integer nullable: true description: Nominal (rounded) frame rate used for the timecodes start_timecode: type: string description: Source start timecode of the file scenes: type: array items: type: object properties: start_seconds: type: integer end_seconds: type: number description: >- Exclusive. A whole second, except for the last scene, which ends at frame_count / fps. start_timecode: type: string nullable: true end_timecode: type: string nullable: true description: Exclusive missing_visual_analysis: type: array items: type: string description: >- Requested videos, as sent, without visual analysis for the current visual model '400': description: cache_dir or media_paths is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/AuthenticationRequired' '403': $ref: '#/components/responses/Forbidden' '500': description: Failed to read scenes content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Analysis folder is unreadable or unavailable content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: error: type: string description: Error message message: type: string description: >- Additional validation detail. Authentication failures include this field. required: - error PolicyError: type: object required: - policy_error properties: policy_error: type: string description: Enterprise policy restriction that denied the request. responses: AuthenticationRequired: description: >- No license key was supplied in X-License-Key or the JSON license_key field. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Authentication required message: Provide license_key in request body or X-License-Key header Forbidden: description: >- The supplied key could not be validated, lacks Pro entitlements, or an Enterprise policy denied the action. Inspect message or policy_error for the reason. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/PolicyError' examples: invalidKey: summary: License key does not exist value: error: Jumper Pro license required message: >- License invalid and activation not required: license does not exist nonProKey: summary: Valid license without Pro entitlements value: error: Jumper Pro license required message: OK policyDenied: summary: Enterprise policy denied the action value: policy_error: >- This action is not available under your organization's Jumper policy securitySchemes: HeaderAuth: type: apiKey in: header name: X-License-Key description: >- Raw Jumper Pro license key on every authenticated request, without a Bearer prefix ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.