How to Detect Shot Changes in Videos Using Python

Detecting shot changes is essential in video processing, where you need to identify when one scene changes to another.

For example, when a new camera angle is used or a scene transitions, this is considered a shot change. Detecting these changes helps with tasks like video summarization, scene segmentation, and more.

In this tutorial, we will explain how to implement shot change detection using Python and the Eden AI API. This API allows us to run shot change detection in a single request, with minimal code.

‍

What is Video Shot Change Detection?

Video Shot Change Detection annotates a video with segments that are generated by detecting abrupt shot changes within the video.

This process helps break the video into distinct sections, making it easier to analyze and edit.

‍

How to Detect Shot Changes in Videos

‍

Get Access to Eden AI API

1. Sign up: Visit Eden AI and create an account for free to get started. Once registered, navigate to the API section to find your personal API key which gives you access to a wide range of AI services, including Shot Change Detection.

2. Navigate to Video Technologies – Log in and head to the Video Technologies section.

3. Select Shot Change Detection– From there, select the Shot Change Detection option, or dive into more advanced features based on your requirements.

‍

Live Test Models on Eden AI

Eden AI provides a platform where you can test different AI models before integrating them, allowing you to evaluate and select the provider that best aligns with your needs.

‍

Implementing Shot Change Detection in Python

‍

Step 1: Install Python Requests Module

Before implementing the solution, ensure you have the Requests library installed in Python. If you haven’t already installed it, you can do so by running:

pip install requests

This module is required to send HTTP requests to the Eden AI API.

‍

Code Explanation

Shot change detection now goes through a multimodal LLM that accepts video as input, called with Eden AI’s OpenAI-compatible chat completions endpoint. It works in two steps:

1. Sending the request: you send the video URL, your instruction and the JSON format you expect for the answer.
   
2. Reading the results: the shots come back in the same response, as JSON, so there is no job to poll.
   

A 10-second clip is processed in a few seconds. For long videos, set a generous timeout on your HTTP client.

‍

Request Phase

This part of the code sends the video and the instruction to Eden AI.

import requests

# Replace with your actual API Key
headers = {"Authorization": "Bearer {API_KEY}"}

# The JSON format expected for the answer: one entry per shot
schema = {
    "type": "object",
    "properties": {
        "shots": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "start_time": {"type": "number"},
                    "end_time": {"type": "number"},
                    "description": {"type": "string"},
                },
                "required": ["start_time", "end_time", "description"],
            },
        }
    },
    "required": ["shots"],
}

# Replace with the actual URL of your video
json_payload = {
    "model": "google/gemini-2.5-flash",  # Any model that accepts video input
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "List every shot in this video. A new shot starts at each camera cut. Give start and end times in seconds."},
                {"type": "image_url", "image_url": {"url": "🔗 URL of your video"}},
            ],
        }
    ],
    "response_format": {"type": "json_schema", "json_schema": {"name": "shots", "schema": schema}},
}

# Eden AI's OpenAI-compatible chat endpoint
url = "https://api.edenai.run/v3/chat/completions"

# Send the POST request
response = requests.post(url, json=json_payload, headers=headers)

# Get the response and display it
result = response.json()
print(result)

Explanation of the Request Phase:

• URL: We are using Eden AI’s OpenAI-compatible endpoint https://api.edenai.run/v3/chat/completions.
  
• Authorization Header: The Authorization header contains your API key, which is required for authentication with Eden AI’s API.
  
• json_payload: Contains the data required for the request:
  
  • model: The multimodal LLM to use, in the provider/model format. It must accept video: check for video in input_modalities at https://api.edenai.run/v3/models (for example google/gemini-2.5-flash or amazon/amazon.nova-2-lite-v1:0).
    
  • messages: Your instruction in a text block, and the public URL of your video in an image_url block.
    
  • response_format: The JSON schema the answer must follow, here a list of shots with start and end times and a short description.
    

The answer comes back in the same response, so there is no job to track.

‍

Reading Phase (Results)

This part of the code reads the shots from the result of the previous step.

import json

# The shots are in the model's answer, as a JSON string
shots = json.loads(result["choices"][0]["message"]["content"])["shots"]
for i, shot in enumerate(shots, 1):
    print(f'Shot {i}: {shot["start_time"]}s to {shot["end_time"]}s, {shot["description"]}')

print("Cost:", result["cost"], "USD")

Explanation of the Reading Phase:

• json.loads: The answer, in choices[0].message.content, is a JSON string that follows your schema, so it is turned into a Python dictionary.
  
• Loop: Prints each shot with its start time, end time and description.
  
• cost: The cost of the request, in USD.

‍

Interpreting the Results

The model’s answer, read from choices[0].message.content, contains:

• shots: A list of detected shots, each with its start time and end time in seconds and a short description.
  
  

The full response also gives the status of the request, its cost and the provider that served it.

Example output:

{
  "shots": [
    {"start_time": 0.0, "end_time": 1.76, "description": "A red-haired woman sits in a snowy, desolate landscape, looking up with a worried expression as snow falls."},
    {"start_time": 1.76, "end_time": 2.13, "description": "An overhead shot shows the red-haired woman running across a snowy field."},
    {"start_time": 2.13, "end_time": 3.2, "description": "A close-up of a large, muscular man's arm and torso as he runs towards the camera, his hand extended."},
    ...
  ]
}

shots: These are the detected shots. For example, the first shot starts at 0s and ends at 1.76s, when the camera cuts to an overhead view. The timestamps are estimated by the model: check them on a few of your own videos before relying on them in production.

‍

Managing Your Video Files

‍

To analyze a video stored on your machine, upload it first with POST https://api.edenai.run/v3/upload, then send a file block with the returned file_id instead of the image_url block. Eden AI provides additional optional endpoints to manage these files:

Video Files - List Files

GET Request:
https://api.edenai.run/v3/upload
This lists the files you uploaded, with their file_id and expiration date.

Video Files - Delete Files

POST Request:
https://api.edenai.run/v3/upload/delete
Send the list of file_ids you no longer need in the file_ids field to delete them.

‍

Why Eden AI is the Best Tool for Shot Change Detection

Eden AI offers a robust shot change detection solution with several advantages.

‍

Multiple Provider Options

Eden AI offers a selection of AI providers, giving you the flexibility to detect deepfakes using various models.

High Accuracy

‍The shot change detection models used by Eden AI are trained on vast datasets and designed to deliver reliable results.

Ease of Integration

Eden AI simplifies the integration of shot change detection into your applications with clear and straightforward Python code examples.

Security and Trust

‍The Eden AI platform prioritizes data security and privacy, ensuring that your image data is handled securely.

‍

Conclusion

In this guide, we’ve learned how to detect shot changes in videos using Python and Eden AI's Shot Change Detection API.

By sending the video and the expected JSON format in a single request, we can easily automate the process of shot change detection without the complexity of managing different AI models or platforms.

With Eden AI’s easy-to-integrate API, you can streamline video processing workflows and focus more on creative and impactful tasks.

FAQ — Detect Shot Changes in Videos Using Python