Jumper

https://docs.getjumper.io/
Admin
Jumper is an offline AI-powered search and analysis platform that integrates with video editing...
Tokens:63,211
Snippets:873
Trust Score:7.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Media Analysis Request

Source: https://docs.getjumper.io/api-reference/analysis/start-media-analysis

Example payload for initiating an asynchronous analysis pipeline, including paths for visual analysis and transcription jobs.

```yaml
cache_dir: /Users/me/JumperAnalysis
visual_media_paths:
  - /Videos/interview.mp4
  - /Videos/photo.jpg
transcription_jobs:
  - path: /Videos/interview.mp4
    language: english
  - path: /Audio/voiceover.mp3
    language: english
```

--------------------------------

### Start Watch Folder Service

Source: https://docs.getjumper.io/api-reference/watch-folders/start-the-watch-folder-service

Starts the background service that monitors watch folders for new media. This endpoint requires authentication.

```APIDOC
## POST /watch-folders/service/start

### Description
Starts the background service that monitors watch folders for new media.

### Method
POST

### Endpoint
/watch-folders/service/start

### Parameters
#### Header Parameters
- **X-License-Key** (string) - Required - Jumper Pro license key passed via header

#### Request Body
- **license_key** (string) - Optional - Jumper Pro license key passed in JSON body (alternative to header)

### Request Example
```json
{
  "license_key": "YOUR_LICENSE_KEY"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the service has started or was already running.

#### Response Example
```json
{
  "message": "Watch folder service started successfully."
}
```
```

--------------------------------

### POST /analyze

Source: https://docs.getjumper.io/api-reference/analysis/start-media-analysis

Starts an asynchronous media analysis pipeline for visual, speech, or face detection tasks.

```APIDOC
## POST /analyze

### Description
Starts an asynchronous analysis pipeline. Returns immediately with a task_id that can be used to track progress via SocketIO. You can run visual analysis, speech transcription, and face clustering in a single call.

### Method
POST

### Endpoint
/analyze

### Parameters
#### Request Body
- **cache_dir** (string) - Required - Where to store analysis results
- **visual_media_paths** (array) - Optional - Files to run visual analysis on
- **transcription_jobs** (array) - Optional - Files to transcribe, with optional language hints
- **face_clustering_jobs** (array) - Optional - Face detection and clustering job definitions

### Request Example
{
  "cache_dir": "/Users/me/JumperAnalysis",
  "visual_media_paths": [
    "/Videos/interview.mp4",
    "/Videos/photo.jpg"
  ],
  "transcription_jobs": [
    {
      "path": "/Videos/interview.mp4",
      "language": "english"
    },
    {
      "path": "/Audio/voiceover.mp3",
      "language": "english"
    }
  ]
}

### Response
#### Success Response (202)
- **message** (string) - Status message
- **task_id** (string) - Use this ID to join a SocketIO room for progress events

#### Response Example
{
  "message": "Analysis started",
  "task_id": "example-task-id-123"
}
```

--------------------------------

### Locate Jumper ZXP file path

Source: https://docs.getjumper.io/NLE/premiere/premiere-panel-not-opening

Use these paths to locate the ZXP file for manual installation via ZXPInstaller.

```javascript
~/Applications/Jumper.app/Contents/Resources/Jumper.zxp
```

```python
C:\Program Files (x86)\Jumper\_internal\Jumper.zxp
```

--------------------------------

### GET /models/available

Source: https://docs.getjumper.io/api-reference/models/list-available-models

Retrieves a list of all supported models, identifies which are downloaded, and shows the currently loaded model.

```APIDOC
## GET /models/available

### Description
Returns all supported models for this platform, which ones are downloaded, and which is currently loaded.

### Method
GET

### Endpoint
/models/available

### Response
#### Success Response (200)
- **supported_models** (array) - All model keys supported on this hardware
- **downloaded_models** (array) - Model keys that are downloaded and ready to use
- **loaded_model** (string) - Currently active model key
- **model_info** (object) - Detailed info per model (display name, resolution, etc.)
- **current_system** (string) - Hardware type (e.g. "apple_silicon", "cuda", "cpu")

#### Response Example
{
  "supported_models": ["v2-medium-256", "v2-large-512"],
  "downloaded_models": ["v2-medium-256"],
  "loaded_model": "v2-medium-256",
  "model_info": {},
  "current_system": "cuda"
}
```

--------------------------------

### Execute Agentic Media Search and Export

Source: https://docs.getjumper.io/core-concepts/agentic-editing

Example of using a chat interface to request specific media clips and sequence exports from an AI agent.

```text
<Chat>
  <ChatMessage>
    Use Jumper to find all shots of Anna smiling, export them as individual files, and also export a sequence to Premiere.
  </ChatMessage>

  <ChatStatus>
    Worked for 50s
  </ChatStatus>

  <ChatResponse>
    Export finished. The Premiere XML timeline is saved at <code>~/jumper_test_movies/anna_smiling_sequence.xml</code>

    **Sequence:** Anna smiling

    **Clips:** 20 (~1:20 total duration)

    The clips are in <code>~/jumper_test_movies/anna_smiling_clips/</code>

    In Premiere Pro, use File -> Import and select the XML file. A sequence named "Anna smiling" will be added with all 20 clips in order. Ensure the source media is imported in your project first, or let Premiere relink if paths differ.
  </ChatResponse>
</Chat>
```

```text
<Chat>
  <ChatMessage>
    Use Jumper to cut a sizzle reel from the event footage in <code>/day1_footage/</code> with the voiceover <code>sizzle_reel_audio.wav</code>.
  </ChatMessage>

  <ChatStatus>
    Worked for 1m 15s
  </ChatStatus>

  <ChatResponse>
    Export finished. The sizzle reel with synced voiceover has been created.

    **Sequence file:** <code>~/day1_footage/sizzle_reel_with_vo.xml</code>

    * **Clips:** 12 (cut to match voiceover timing)
    * **Voiceover:** <code>sizzle_reel_audio.wav</code> (synced)

    Drag it to your timeline to add it to your project.
  </ChatResponse>
</Chat>
```

--------------------------------

### Authentication

Source: https://docs.getjumper.io/developers/api

Every endpoint except GET /health requires a Jumper Pro license key. The key can be passed either in the X-License-Key header or within the JSON request body.

```APIDOC
## Authentication

Every endpoint except `GET /health` requires a **Jumper Pro** license key. Pass it one of two ways:

### Header (recommended)
Use the `X-License-Key` header:

```bash
curl -H "X-License-Key: your-key-here" http://localhost:6699/api/v1/models/loaded
```

### JSON body
Include `license_key` in the request body:

```json
{
  "license_key": "your-key-here",
  "cache_dir": "/path",
  "media_paths": []
}
```

**Error Responses:**
- `401`: `{"error": "Authentication required", "message": "Provide license_key in request body or X-License-Key header"}`
- `403`: `{"error": "Jumper Pro license required", "message": "The public API requires a Jumper Pro license"}
```

--------------------------------

### GET /api/v1/health

Source: https://docs.getjumper.io/developers/api

Performs a health check on the service.

```APIDOC
## GET /api/v1/health

### Description
Checks the health status of the Jumper service.

### Method
GET

### Endpoint
/api/v1/health
```

--------------------------------

### Get Currently Loaded Models OpenAPI Spec

Source: https://docs.getjumper.io/api-reference/models/get-currently-loaded-models

This OpenAPI specification defines the GET /models/loaded endpoint, which retrieves the visual and speech analysis models currently loaded in memory. It includes details on request and response schemas, authentication methods, and server information.

```yaml
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, and face detection with clustering.
    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, provided via:

    - `X-License-Key` header (recommended), or

    - `license_key` field in the JSON request body


    Invalid or missing keys return `401`. Non-Pro keys return `403`.


    ## 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 CRC32-based hash that uniquely identifies a media file. Returned by the metadata endpoint.

    - **`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: []
  - BodyAuth: []
paths:
  /models/loaded:
    get:
      tags:
        - Models
      summary: Get currently loaded models
      description: >-
        Returns the visual and speech analysis models that are currently loaded
        in memory.
      responses:
        '200':
          description: Current model state
          content:
            application/json:
              schema:
                type: object
                properties:
                  visual:
                    type: object
                    properties:
                      model_key:
                        type: string
                        nullable: true
                        example: v2-medium-256
                      is_loading:
                        type: boolean
                  speech:
                    type: object
                    properties:
                      model_key:
                        type: string
                        nullable: true
                        example: mlx-large-v3-turbo
                      is_loading:
                        type: boolean
components:
  securitySchemes:
    HeaderAuth:
      type: apiKey
      in: header
      name: X-License-Key
      description: Jumper Pro license key passed via header
    BodyAuth:
      type: apiKey
      in: query
      name: license_key
      description: Jumper Pro license key passed in JSON body (alternative to header)
```

--------------------------------

### GET /api/v1/models/loaded

Source: https://docs.getjumper.io/developers/api

Retrieves the status of currently loaded models.

```APIDOC
## GET /api/v1/models/loaded

### Description
Returns information about the models currently loaded in the system.

### Method
GET

### Endpoint
/api/v1/models/loaded
```

--------------------------------

### GET /health

Source: https://docs.getjumper.io/developers/api

Checks if the Jumper backend is running. This endpoint does not require authentication.

```APIDOC
## GET /health

### Description
Verify the backend is running.

### Method
GET

### Endpoint
`/health`

### Parameters
None

### Request Example
```bash
curl http://localhost:6699/api/v1/health
```

### Response
#### Success Response (200)
- **status** (string) - Indicates if the service is healthy.
```

--------------------------------

### POST /analyze

Source: https://docs.getjumper.io/developers/api

Initiates the analysis of media files. This endpoint requires authentication and returns a task ID for progress tracking.

```APIDOC
## POST /analyze

### Description
Run visual and/or speech analysis on your files. Returns a `task_id` for progress tracking.

### Method
POST

### Endpoint
`/analyze`

### Parameters
#### Request Body
- **media_paths** (array of strings) - Required - Absolute filesystem paths to media files.
- **cache_dir** (string) - Optional - The folder where Jumper stores analysis data.
- **models** (object) - Optional - Specifies which analysis models to use.
  - **visual** (array of strings) - Optional - List of visual analysis model keys.
  - **speech** (array of strings) - Optional - List of speech analysis model keys.

### Request Example
```json
{
  "media_paths": ["/path/to/your/video.mp4"],
  "cache_dir": "/path/to/cache",
  "models": {
    "visual": ["v2-medium-256"],
    "speech": ["mlx-large-v3-turbo"]
  }
}
```

### Response
#### Success Response (200)
- **task_id** (string) - Unique identifier for the analysis task.
```

--------------------------------

### GET /models/loaded

Source: https://docs.getjumper.io/api-reference/models/get-currently-loaded-models

Retrieves the visual and speech analysis models that are currently loaded in memory.

```APIDOC
## GET /models/loaded

### Description
Returns the visual and speech analysis models that are currently loaded in memory.

### Method
GET

### Endpoint
/models/loaded

### Response
#### Success Response (200)
- **visual** (object) - Contains the current visual model state.
  - **model_key** (string) - Internal identifier for the visual model.
  - **is_loading** (boolean) - Indicates if the model is currently loading.
- **speech** (object) - Contains the current speech model state.
  - **model_key** (string) - Internal identifier for the speech model.
  - **is_loading** (boolean) - Indicates if the model is currently loading.

#### Response Example
{
  "visual": {
    "model_key": "v2-medium-256",
    "is_loading": false
  },
  "speech": {
    "model_key": "mlx-large-v3-turbo",
    "is_loading": false
  }
}
```

--------------------------------

### POST /thumbnails/scene

Source: https://docs.getjumper.io/developers/api

Fetches preview images for detected scenes in media files. This endpoint requires authentication.

```APIDOC
## POST /thumbnails/scene

### Description
Fetch preview images for detected scenes.

### Method
POST

### Endpoint
`/thumbnails/scene`

### Parameters
#### Request Body
- **media_path** (string) - Required - Absolute filesystem path to the media file.
- **cache_dir** (string) - Optional - The folder where Jumper stores analysis data.

### Request Example
```json
{
  "media_path": "/path/to/your/video.mp4"
}
```

### Response
#### Success Response (200)
- **scenes** (array of objects) - List of detected scenes, each with a timestamp and potentially a thumbnail.
```

--------------------------------

### Load Models API Request

Source: https://docs.getjumper.io/developers/api

This endpoint checks which models are loaded. Requires an 'X-License-Key' header for authentication.

```bash
curl -H "X-License-Key: YOUR_KEY" http://localhost:6699/api/v1/models/loaded
```

--------------------------------

### POST /thumbnails

Source: https://docs.getjumper.io/developers/api

Fetches preview images (thumbnails) for specific timestamps in media files. This endpoint requires authentication.

```APIDOC
## POST /thumbnails

### Description
Fetch preview images for specific timestamps.

### Method
POST

### Endpoint
`/thumbnails`

### Parameters
#### Request Body
- **media_path** (string) - Required - Absolute filesystem path to the media file.
- **timestamps** (array of numbers) - Required - List of timestamps in seconds for which to generate thumbnails.
- **cache_dir** (string) - Optional - The folder where Jumper stores analysis data.

### Request Example
```json
{
  "media_path": "/path/to/your/video.mp4",
  "timestamps": [10.5, 30.2, 60.0]
}
```

### Response
#### Success Response (200)
- **thumbnails** (array of objects) - List of generated thumbnails, potentially including image data or URLs.
```

--------------------------------

### Get watch folder service status

Source: https://docs.getjumper.io/api-reference/watch-folders/get-watch-folder-service-status

Returns whether the background service is running and its current state.

```APIDOC
## GET /watch-folders/service/status

### Description
Returns whether the background service is running and its current state.

### Method
GET

### Endpoint
/watch-folders/service/status

### Parameters
#### Query Parameters
- **license_key** (string) - Required - Jumper Pro license key passed in JSON body (alternative to header)

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **status** (string) - The current state of the watch folder service.
- **is_running** (boolean) - Indicates if the watch folder service is currently running.

#### Response Example
```json
{
  "status": "running",
  "is_running": true
}
```
```

--------------------------------

### Authentication Methods

Source: https://docs.getjumper.io/api-reference/analysis/start-media-analysis

Details on how to authenticate with the Jumper IO API using either header-based or query parameter-based license keys.

```APIDOC
## Authentication

### Header Authentication

Use the `X-License-Key` header to pass your Jumper Pro license key.

### Query Parameter Authentication

Alternatively, you can pass the `license_key` as a query parameter in your request.

```

--------------------------------

### Analyze Media API Request

Source: https://docs.getjumper.io/developers/api

Initiate analysis for visual and transcription tasks on media files. Requires an 'X-License-Key' and 'Content-Type' header, with a JSON payload detailing the cache directory, visual media paths, and transcription job configurations.

```bash
curl -X POST http://localhost:6699/api/v1/analyze \
    -H "X-License-Key: YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "cache_dir": "/Users/me/JumperAnalysis",
      "visual_media_paths": ["/Videos/interview.mp4"],
      "transcription_jobs": [{"path": "/Videos/interview.mp4", "language": "english"}]
    }'
```

--------------------------------

### POST /cache-paths

Source: https://docs.getjumper.io/api-reference/utilities/get-cache-folder-paths-for-a-media-file

Returns the visual and audio cache folder paths for a specific media file, useful for inspecting or managing analysis data on disk.

```APIDOC
## POST /cache-paths

### Description
Returns the visual and audio cache folder paths for a specific media file. Useful for inspecting or managing analysis data on disk.

### Method
POST

### Endpoint
/cache-paths

### Parameters
#### Request Body
- **cache_dir** (string) - Required - The folder where Jumper stores analysis data.
- **media_path** (string) - Required - Absolute path to the media file.

### Request Example
{
  "cache_dir": "/path/to/cache",
  "media_path": "/path/to/media/file.mp4"
}

### Response
#### Success Response (200)
- **video_cache_path** (string) - Path to the visual analysis cache folder (null if not yet analyzed)
- **audio_cache_path** (string) - Path to the audio/transcription cache folder (null if not yet analyzed)
- **hash_str** (string) - Unique hash identifying this media file

#### Response Example
{
  "video_cache_path": "/path/to/cache/video_hash",
  "audio_cache_path": "/path/to/cache/audio_hash",
  "hash_str": "a1b2c3d4"
}
```

--------------------------------

### POST /media/metadata

Source: https://docs.getjumper.io/api-reference/media/get-metadata-for-media-files

Returns properties (duration, FPS, timecode) and analysis status for each media file. Use this to check which files have been analyzed and to get their `hash_str` identifiers.

```APIDOC
## POST /media/metadata

### Description
Returns properties (duration, FPS, timecode) and analysis status for each media file. Use this to check which files have been analyzed and to get their `hash_str` identifiers.

### Method
POST

### Endpoint
/media/metadata

### Parameters
#### Request Body
- **cache_dir** (string) - Required - Path to the analysis data folder
- **media_paths** (array of strings) - Required - Absolute paths to media files

### Request Example
```json
{
  "cache_dir": "/Users/me/JumperAnalysis",
  "media_paths": [
    "/Videos/interview.mp4",
    "/Videos/photo.jpg",
    "/Audio/voiceover.mp3"
  ]
}
```

### Response
#### Success Response (200)
- **media_properties** (object) - Metadata keyed by file path. Contains properties like `video_cached`, `audio_cached`, `runtime`, `fps`, `media_path`, `timecode`, and `hash_str`.

#### Response Example
```json
{
  "media_properties": {
    "/Videos/interview.mp4": {
      "video_cached": true,
      "audio_cached": true,
      "runtime": "00:02:30",
      "fps": 29.97,
      "media_path": "/Videos/interview.mp4",
      "timecode": "00:00:00:00",
      "hash_str": "1e09e4953de0471b"
    },
    "/Videos/photo.jpg": {
      "video_cached": false,
      "audio_cached": false,
      "runtime": null,
      "fps": 0,
      "media_path": "/Videos/photo.jpg",
      "timecode": null,
      "hash_str": "a3b8c7d6e5f4a3b2"
    }
  }
}
```

#### Error Response (400)
- **error** (string) - Error message

#### Error Response Example
```json
{
  "error": "Invalid input provided."
}
```
```
Tokens:
Raw