Create Scene Index

Create video scene index

curl --request POST \
  --url https://api.videodb.io/video/{video_id}/index/scene/ \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
}
'

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scene_type: 'shot',
    segmentation_threshold: 0.8,
    callback_url: 'https://webhook.example.com/callback'
  })
};

fetch('https://api.videodb.io/video/{video_id}/index/scene/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.videodb.io/video/{video_id}/index/scene/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scene_type' => 'shot',
    'segmentation_threshold' => 0.8,
    'callback_url' => 'https://webhook.example.com/callback'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.videodb.io/video/{video_id}/index/scene/"

	payload := strings.NewReader("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-access-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.videodb.io/video/{video_id}/index/scene/")
  .header("x-access-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.videodb.io/video/{video_id}/index/scene/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}"

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("x-access-token", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.videodb.io/video/{video_id}/index/scene/' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
}'

import Foundation

let parameters = [
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
] as [String : Any?]

let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])

let url = URL(string: "https://api.videodb.io/video/{video_id}/index/scene/")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "x-access-token": "<api-key>",
  "Content-Type": "application/json"
]
request.httpBody = postData

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

using RestSharp;


var options = new RestClientOptions("https://api.videodb.io/video/{video_id}/index/scene/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-access-token", "<api-key>");
request.AddJsonBody("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.videodb.io/video/{video_id}/index/scene/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-access-token", "<api-key>");
request.AddJsonBody("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scene_type: 'shot',
    segmentation_threshold: 0.8,
    callback_url: 'https://webhook.example.com/callback'
  })
};

fetch('https://api.videodb.io/video/{video_id}/index/scene/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.videodb.io/video/{video_id}/index/scene/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "x-access-token: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.videodb.io/video/{video_id}/index/scene/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "x-access-token: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}");

CURLcode ret = curl_easy_perform(hnd);

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")
val request = Request.Builder()
  .url("https://api.videodb.io/video/{video_id}/index/scene/")
  .post(body)
  .addHeader("x-access-token", "<api-key>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "success": true,
  "status": "processing",
  "data": {
    "id": "job-123",
    "output_url": "https://api.videodb.io/async-response/job-123"
  }
}

POST

video

{video_id}

index

scene

Create video scene index

curl --request POST \
  --url https://api.videodb.io/video/{video_id}/index/scene/ \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
}
'

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scene_type: 'shot',
    segmentation_threshold: 0.8,
    callback_url: 'https://webhook.example.com/callback'
  })
};

fetch('https://api.videodb.io/video/{video_id}/index/scene/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.videodb.io/video/{video_id}/index/scene/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scene_type' => 'shot',
    'segmentation_threshold' => 0.8,
    'callback_url' => 'https://webhook.example.com/callback'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.videodb.io/video/{video_id}/index/scene/"

	payload := strings.NewReader("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-access-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.videodb.io/video/{video_id}/index/scene/")
  .header("x-access-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.videodb.io/video/{video_id}/index/scene/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-access-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}"

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("x-access-token", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.videodb.io/video/{video_id}/index/scene/' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
}'

import Foundation

let parameters = [
  "scene_type": "shot",
  "segmentation_threshold": 0.8,
  "callback_url": "https://webhook.example.com/callback"
] as [String : Any?]

let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])

let url = URL(string: "https://api.videodb.io/video/{video_id}/index/scene/")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "x-access-token": "<api-key>",
  "Content-Type": "application/json"
]
request.httpBody = postData

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

using RestSharp;


var options = new RestClientOptions("https://api.videodb.io/video/{video_id}/index/scene/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-access-token", "<api-key>");
request.AddJsonBody("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.videodb.io/video/{video_id}/index/scene/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-access-token", "<api-key>");
request.AddJsonBody("{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

const options = {
  method: 'POST',
  headers: {'x-access-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scene_type: 'shot',
    segmentation_threshold: 0.8,
    callback_url: 'https://webhook.example.com/callback'
  })
};

fetch('https://api.videodb.io/video/{video_id}/index/scene/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.videodb.io/video/{video_id}/index/scene/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "x-access-token: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.videodb.io/video/{video_id}/index/scene/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "x-access-token: <api-key>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}");

CURLcode ret = curl_easy_perform(hnd);

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"scene_type\": \"shot\",\n  \"segmentation_threshold\": 0.8,\n  \"callback_url\": \"https://webhook.example.com/callback\"\n}")
val request = Request.Builder()
  .url("https://api.videodb.io/video/{video_id}/index/scene/")
  .post(body)
  .addHeader("x-access-token", "<api-key>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "success": true,
  "status": "processing",
  "data": {
    "id": "job-123",
    "output_url": "https://api.videodb.io/async-response/job-123"
  }
}

Create an AI-powered index of scenes in the video with descriptions, enabling visual search and scene understanding.

import videodb

conn = videodb.connect(api_key="your_api_key")
coll = conn.get_collection()
video = coll.get_videos()[0]

# Index scenes for visual search
scene_index_id = video.index_scenes()

print(f"Scene index created: {scene_index_id}")

import { connect } from 'videodb';

const conn = connect({ apiKey: 'your_api_key' });
const coll = await conn.getCollection();
const videos = await coll.getVideos();
const video = videos[0];

// Index scenes for visual search
const sceneIndexId = await video.indexScenes();

console.log(`Scene index created: ${sceneIndexId}`);

Analyzes video frames and creates AI descriptions for scenes
Supports shot-based and time-based extraction strategies
Can use custom prompts to guide scene description
Generates visual embeddings for semantic search
Returns scene index ID for later retrieval and searching
Extraction configuration controls frame sampling and scene detection

Open-weight model with Sandbox Compute

For open-weight VLM models, create a compatible sandbox first and pass sandbox_id with model_name.

from videodb import SandboxTier, SceneExtractionType

sandbox = conn.create_sandbox(
    tier=SandboxTier.medium,
    models=["google/gemma-4-31B-it-FP8"],
)
sandbox.wait_for_ready()

scene_index_id = video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 10, "frame_count": 1},
    model_name="google/gemma-4-31B-it-FP8",
    prompt="Describe the scene in a clear, concise way.",
    sandbox_id=sandbox.id,
)

VideoDB validates that the sandbox is active, belongs to your workspace/account, supports the requested model tier, and was created with a matching models or model_categories value when model selection was provided. See Sandbox Compute for sandbox setup.

Authorizations

x-access-token

string

header

required

API key for authentication (sk-xxx format)

Path Parameters

video_id

string

required

Pattern: ^m-

Example:

"m-12345"

Body

application/json

scene_type

enum<string>

Available options:

shot,

time_based

Example:

"shot"

segmentation_threshold

number

Example:

0.8

callback_url

string

Example:

"https://webhook.example.com/callback"

Response

200 - application/json

Scene index creation started

success

boolean

Example:

true

status

enum<string>

Available options:

processing,

done,

failed

Example:

"processing"

data

object

Show child attributes

⌘I

Overview

Authentication

Collections

Videos

Streaming & Playback

Transcription

Search V2 & Ask

Indexing & Search

Scene & Frame Analysis

Advanced Operations

Audio

Images

AI Generation

Timeline & Compilation

Billing

Downloads

Utilities

Assets

Editor

Transcode

Meeting

Capture

RTStream

RTStream Transcription

RTStream Scene Indexing

RTStream Events & Alerts

Open-weight model with Sandbox Compute

Authorizations

Path Parameters

Body

Response

​Open-weight model with Sandbox Compute

Authorizations

Path Parameters

Body

Response

Open-weight model with Sandbox Compute