Skip to main content
POST
/
video
/
{video_id}
/
frame
/
{frame_id}
/
describe
/
Describe video frame
curl --request POST \
  --url https://api.videodb.io/video/{video_id}/frame/{frame_id}/describe/ \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "prompt": "Describe this frame",
  "model_name": "gpt-4-vision"
}
'
{
  "success": true,
  "data": {
    "description": "Frame description text"
  }
}
Generate an AI-powered description of a specific video frame’s visual content. 
import videodb

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

# Get scene collection
scene_collection = video.get_scene_collection("scene_collection_id")

# Get a frame from a scene
scene = scene_collection.scenes[0]
frame = scene.frames[0]

# Describe the frame
description = frame.describe()

print(f"Frame description: {description}")
print(f"Frame time: {frame.frame_time}s")

# Describe with custom prompt
custom_desc = frame.describe(prompt="List all objects visible")

# Describe with custom model configuration
description = frame.describe(
    prompt="Describe this frame in detail",
    model_name="pro",
    model_config={"temperature": 0.5}
)
  • Generates detailed visual description using AI vision models
  • Can use custom prompts to focus description on specific aspects
  • Optional model_config dict accepts model_name (e.g., "pro") and temperature (0.0-2.0) to control the vision model
  • Overwrites existing frame description
  • Frame IDs start with fr- prefix
  • Each frame includes timestamp (frame_time) in the video
  • Useful for generating captions or accessibility descriptions

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"

​
frame_id
string
required
Example:

"frame-123"

Body

application/json
​
prompt
string
Example:

"Describe this frame"

​
model_name
string
Example:

"gpt-4-vision"

Response

200 - application/json

Frame description generated

​
success
boolean
Example:

true

​
data
object