everything-claude-code/skills/videodb/reference/api-reference.md

Complete API Reference

Reference material for the VideoDB skill. For usage guidance and workflow selection, start with ../SKILL.md.

Connection

import videodb

conn = videodb.connect(
    api_key="your-api-key",      # or set VIDEO_DB_API_KEY env var
    base_url=None,                # custom API endpoint (optional)
)

Returns: Connection object

Connection Methods

Method	Returns	Description
conn.get_collection(collection_id="default")	Collection	Get collection (default if no ID)
conn.get_collections()	list[Collection]	List all collections
conn.create_collection(name, description, is_public=False)	Collection	Create new collection
conn.update_collection(id, name, description)	Collection	Update a collection
conn.check_usage()	dict	Get account usage stats
conn.upload(source, media_type, name, ...)	Video|Audio|Image	Upload to default collection
conn.record_meeting(meeting_url, bot_name, ...)	Meeting	Record a meeting
conn.create_capture_session(...)	CaptureSession	Create a capture session (see capture-reference.md)
conn.youtube_search(query, result_threshold, duration)	list[dict]	Search YouTube
conn.transcode(source, callback_url, mode, ...)	str	Transcode video (returns job ID)
conn.get_transcode_details(job_id)	dict	Get transcode job status and details
conn.connect_websocket(collection_id)	WebSocketConnection	Connect to WebSocket (see capture-reference.md)

Transcode

Transcode a video from a URL with custom resolution, quality, and audio settings. Processing happens server-side — no local ffmpeg required.

from videodb import TranscodeMode, VideoConfig, AudioConfig

job_id = conn.transcode(
    source="https://example.com/video.mp4",
    callback_url="https://example.com/webhook",
    mode=TranscodeMode.economy,
    video_config=VideoConfig(resolution=720, quality=23),
    audio_config=AudioConfig(mute=False),
)

transcode Parameters

Parameter	Type	Default	Description
source	str	required	URL of the video to transcode (preferably a downloadable URL)
callback_url	str	required	URL to receive the callback when transcoding completes
mode	TranscodeMode	TranscodeMode.economy	Transcoding speed: economy or lightning
video_config	VideoConfig	VideoConfig()	Video encoding settings
audio_config	AudioConfig	AudioConfig()	Audio encoding settings

Returns a job ID (str). Use conn.get_transcode_details(job_id) to check job status.

details = conn.get_transcode_details(job_id)

VideoConfig

from videodb import VideoConfig, ResizeMode

config = VideoConfig(
    resolution=720,              # Target resolution height (e.g. 480, 720, 1080)
    quality=23,                  # Encoding quality (lower = better, default 23)
    framerate=30,                # Target framerate
    aspect_ratio="16:9",         # Target aspect ratio
    resize_mode=ResizeMode.crop, # How to fit: crop, fit, or pad
)

Field	Type	Default	Description
resolution	int|None	None	Target resolution height in pixels
quality	int	23	Encoding quality (lower = higher quality)
framerate	int|None	None	Target framerate
aspect_ratio	str|None	None	Target aspect ratio (e.g. "16:9", "9:16")
resize_mode	str	ResizeMode.crop	Resize strategy: crop, fit, or pad

AudioConfig

from videodb import AudioConfig

config = AudioConfig(mute=False)

Field	Type	Default	Description
mute	bool	False	Mute the audio track

Collections

coll = conn.get_collection()

Collection Methods

Method	Returns	Description
coll.get_videos()	list[Video]	List all videos
coll.get_video(video_id)	Video	Get specific video
coll.get_audios()	list[Audio]	List all audios
coll.get_audio(audio_id)	Audio	Get specific audio
coll.get_images()	list[Image]	List all images
coll.get_image(image_id)	Image	Get specific image
coll.upload(url=None, file_path=None, media_type=None, name=None)	Video|Audio|Image	Upload media
coll.search(query, search_type, index_type, score_threshold, namespace, scene_index_id, ...)	SearchResult	Search across collection (semantic only; keyword and scene search raise NotImplementedError)
coll.generate_image(prompt, aspect_ratio="1:1")	Image	Generate image with AI
coll.generate_video(prompt, duration=5)	Video	Generate video with AI
coll.generate_music(prompt, duration=5)	Audio	Generate music with AI
coll.generate_sound_effect(prompt, duration=2)	Audio	Generate sound effect
coll.generate_voice(text, voice_name="Default")	Audio	Generate speech from text
coll.generate_text(prompt, model_name="basic", response_type="text")	dict	LLM text generation — access result via ["output"]
coll.dub_video(video_id, language_code)	Video	Dub video into another language
coll.record_meeting(meeting_url, bot_name, ...)	Meeting	Record a live meeting
coll.create_capture_session(...)	CaptureSession	Create a capture session (see capture-reference.md)
coll.get_capture_session(...)	CaptureSession	Retrieve capture session (see capture-reference.md)
coll.connect_rtstream(url, name, ...)	RTStream	Connect to a live stream (see rtstream-reference.md)
coll.make_public()	None	Make collection public
coll.make_private()	None	Make collection private
coll.delete_video(video_id)	None	Delete a video
coll.delete_audio(audio_id)	None	Delete an audio
coll.delete_image(image_id)	None	Delete an image
coll.delete()	None	Delete the collection

Upload Parameters

video = coll.upload(
    url=None,            # Remote URL (HTTP, YouTube)
    file_path=None,      # Local file path
    media_type=None,     # "video", "audio", or "image" (auto-detected if omitted)
    name=None,           # Custom name for the media
    description=None,    # Description
    callback_url=None,   # Webhook URL for async notification
)

Video Object

video = coll.get_video(video_id)

Video Properties

Property	Type	Description
video.id	str	Unique video ID
video.collection_id	str	Parent collection ID
video.name	str	Video name
video.description	str	Video description
video.length	float	Duration in seconds
video.stream_url	str	Default stream URL
video.player_url	str	Player embed URL
video.thumbnail_url	str	Thumbnail URL

Video Methods

Method	Returns	Description
video.generate_stream(timeline=None)	str	Generate stream URL (optional timeline of [(start, end)] tuples)
video.play()	str	Open stream in browser, returns player URL
video.index_spoken_words(language_code=None, force=False)	None	Index speech for search. Use force=True to skip if already indexed.
video.index_scenes(extraction_type, prompt, extraction_config, metadata, model_name, name, scenes, callback_url)	str	Index visual scenes (returns scene_index_id)
video.index_visuals(prompt, batch_config, ...)	str	Index visuals (returns scene_index_id)
video.index_audio(prompt, model_name, ...)	str	Index audio with LLM (returns scene_index_id)
video.get_transcript(start=None, end=None)	list[dict]	Get timestamped transcript
video.get_transcript_text(start=None, end=None)	str	Get full transcript text
video.generate_transcript(force=None)	dict	Generate transcript
video.translate_transcript(language, additional_notes)	list[dict]	Translate transcript
video.search(query, search_type, index_type, filter, **kwargs)	SearchResult	Search within video
video.add_subtitle(style=SubtitleStyle())	str	Add subtitles (returns stream URL)
video.generate_thumbnail(time=None)	str|Image	Generate thumbnail
video.get_thumbnails()	list[Image]	Get all thumbnails
video.extract_scenes(extraction_type, extraction_config)	SceneCollection	Extract scenes
video.reframe(start, end, target, mode, callback_url)	Video|None	Reframe video aspect ratio
video.clip(prompt, content_type, model_name)	str	Generate clip from prompt (returns stream URL)
video.insert_video(video, timestamp)	str	Insert video at timestamp
video.download(name=None)	dict	Download the video
video.delete()	None	Delete the video

Reframe

Convert a video to a different aspect ratio with optional smart object tracking. Processing is server-side.

Warning: Reframe is a slow server-side operation. It can take several minutes for long videos and may time out. Always use start/end to limit the segment, or pass callback_url for async processing.

from videodb import ReframeMode

# Always prefer short segments to avoid timeouts:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# Async reframe for full-length videos (returns None, result via webhook):
video.reframe(target="vertical", callback_url="https://example.com/webhook")

# Custom dimensions
reframed = video.reframe(start=0, end=60, target={"width": 1080, "height": 1080})

reframe Parameters

Parameter	Type	Default	Description
start	float|None	None	Start time in seconds (None = beginning)
end	float|None	None	End time in seconds (None = end of video)
target	str|dict	"vertical"	Preset string ("vertical", "square", "landscape") or {"width": int, "height": int}
mode	str	ReframeMode.smart	"simple" (centre crop) or "smart" (object tracking)
callback_url	str|None	None	Webhook URL for async notification

Returns a Video object when no callback_url is provided, None otherwise.

Audio Object

audio = coll.get_audio(audio_id)

Audio Properties

Property	Type	Description
audio.id	str	Unique audio ID
audio.collection_id	str	Parent collection ID
audio.name	str	Audio name
audio.length	float	Duration in seconds

Audio Methods

Method	Returns	Description
audio.generate_url()	str	Generate signed URL for playback
audio.get_transcript(start=None, end=None)	list[dict]	Get timestamped transcript
audio.get_transcript_text(start=None, end=None)	str	Get full transcript text
audio.generate_transcript(force=None)	dict	Generate transcript
audio.delete()	None	Delete the audio

Image Object

image = coll.get_image(image_id)

Image Properties

Property	Type	Description
image.id	str	Unique image ID
image.collection_id	str	Parent collection ID
image.name	str	Image name
image.url	str|None	Image URL (may be None for generated images — use generate_url() instead)

Image Methods

Method	Returns	Description
image.generate_url()	str	Generate signed URL
image.delete()	None	Delete the image

Timeline & Editor

Timeline

from videodb.timeline import Timeline

timeline = Timeline(conn)

Method	Returns	Description
timeline.add_inline(asset)	None	Add VideoAsset sequentially on main track
timeline.add_overlay(start, asset)	None	Overlay AudioAsset, ImageAsset, or TextAsset at timestamp
timeline.generate_stream()	str	Compile and get stream URL

Asset Types

VideoAsset

from videodb.asset import VideoAsset

asset = VideoAsset(
    asset_id=video.id,
    start=0,              # trim start (seconds)
    end=None,             # trim end (seconds, None = full)
)

AudioAsset

from videodb.asset import AudioAsset

asset = AudioAsset(
    asset_id=audio.id,
    start=0,
    end=None,
    disable_other_tracks=True,   # mute original audio when True
    fade_in_duration=0,          # seconds (max 5)
    fade_out_duration=0,         # seconds (max 5)
)

ImageAsset

from videodb.asset import ImageAsset

asset = ImageAsset(
    asset_id=image.id,
    duration=None,        # display duration (seconds)
    width=100,            # display width
    height=100,           # display height
    x=80,                 # horizontal position (px from left)
    y=20,                 # vertical position (px from top)
)

TextAsset

from videodb.asset import TextAsset, TextStyle

asset = TextAsset(
    text="Hello World",
    duration=5,
    style=TextStyle(
        fontsize=24,
        fontcolor="black",
        boxcolor="white",       # background box colour
        alpha=1.0,
        font="Sans",
        text_align="T",         # text alignment within box
    ),
)

CaptionAsset (Editor API)

CaptionAsset belongs to the Editor API, which has its own Timeline, Track, and Clip system:

from videodb.editor import CaptionAsset, FontStyling

asset = CaptionAsset(
    src="auto",                    # "auto" or base64 ASS string
    font=FontStyling(name="Clear Sans", size=30),
    primary_color="&H00FFFFFF",
)

See editor.md for full CaptionAsset usage with the Editor API.

Video Search Parameters

results = video.search(
    query="your query",
    search_type=SearchType.semantic,       # semantic, keyword, or scene
    index_type=IndexType.spoken_word,      # spoken_word or scene
    result_threshold=None,                 # max number of results
    score_threshold=None,                  # minimum relevance score
    dynamic_score_percentage=None,         # percentage of dynamic score
    scene_index_id=None,                   # target a specific scene index (pass via **kwargs)
    filter=[],                             # metadata filters for scene search
)

Note: filter is an explicit named parameter in video.search(). scene_index_id is passed through **kwargs to the API.

Important: video.search() raises InvalidRequestError with message "No results found" when there are no matches. Always wrap search calls in try/except. For scene search, use score_threshold=0.3 or higher to filter low-relevance noise.

For scene search, use search_type=SearchType.semantic with index_type=IndexType.scene. Pass scene_index_id when targeting a specific scene index. See search.md for details.

SearchResult Object

results = video.search("query", search_type=SearchType.semantic)

Method	Returns	Description
results.get_shots()	list[Shot]	Get list of matching segments
results.compile()	str	Compile all shots into a stream URL
results.play()	str	Open compiled stream in browser

Shot Properties

Property	Type	Description
shot.video_id	str	Source video ID
shot.video_length	float	Source video duration
shot.video_title	str	Source video title
shot.start	float	Start time (seconds)
shot.end	float	End time (seconds)
shot.text	str	Matched text content
shot.search_score	float	Search relevance score

Method	Returns	Description
shot.generate_stream()	str	Stream this specific shot
shot.play()	str	Open shot stream in browser

Meeting Object

meeting = coll.record_meeting(
    meeting_url="https://meet.google.com/...",
    bot_name="Bot",
    callback_url=None,          # Webhook URL for status updates
    callback_data=None,         # Optional dict passed through to callbacks
    time_zone="UTC",            # Time zone for the meeting
)

Meeting Properties

Property	Type	Description
meeting.id	str	Unique meeting ID
meeting.collection_id	str	Parent collection ID
meeting.status	str	Current status
meeting.video_id	str	Recorded video ID (after completion)
meeting.bot_name	str	Bot name
meeting.meeting_title	str	Meeting title
meeting.meeting_url	str	Meeting URL
meeting.speaker_timeline	dict	Speaker timeline data
meeting.is_active	bool	True if initializing or processing
meeting.is_completed	bool	True if done

Meeting Methods

Method	Returns	Description
meeting.refresh()	Meeting	Refresh data from server
meeting.wait_for_status(target_status, timeout=14400, interval=120)	bool	Poll until status reached

RTStream & Capture

For RTStream (live ingestion, indexing, transcription), see rtstream-reference.md.

For capture sessions (desktop recording, CaptureClient, channels), see capture-reference.md.

Enums & Constants

SearchType

from videodb import SearchType

SearchType.semantic    # Natural language semantic search
SearchType.keyword     # Exact keyword matching
SearchType.scene       # Visual scene search (may require paid plan)
SearchType.llm         # LLM-powered search

SceneExtractionType

from videodb import SceneExtractionType

SceneExtractionType.shot_based   # Automatic shot boundary detection
SceneExtractionType.time_based   # Fixed time interval extraction
SceneExtractionType.transcript   # Transcript-based scene extraction

SubtitleStyle

from videodb import SubtitleStyle

style = SubtitleStyle(
    font_name="Arial",
    font_size=18,
    primary_colour="&H00FFFFFF",
    bold=False,
    # ... see SubtitleStyle for all options
)
video.add_subtitle(style=style)

SubtitleAlignment & SubtitleBorderStyle

from videodb import SubtitleAlignment, SubtitleBorderStyle

TextStyle

from videodb import TextStyle
# or: from videodb.asset import TextStyle

style = TextStyle(
    fontsize=24,
    fontcolor="black",
    boxcolor="white",
    font="Sans",
    text_align="T",
    alpha=1.0,
)

Other Constants

from videodb import (
    IndexType,          # spoken_word, scene
    MediaType,          # video, audio, image
    Segmenter,          # word, sentence, time
    SegmentationType,   # sentence, llm
    TranscodeMode,      # economy, lightning
    ResizeMode,         # crop, fit, pad
    ReframeMode,        # simple, smart
    RTStreamChannelType,
)

Exceptions

from videodb.exceptions import (
    AuthenticationError,     # Invalid or missing API key
    InvalidRequestError,     # Bad parameters or malformed request
    RequestTimeoutError,     # Request timed out
    SearchError,             # Search operation failure (e.g. not indexed)
    VideodbError,            # Base exception for all VideoDB errors
)

Exception	Common Cause
AuthenticationError	Missing or invalid VIDEO_DB_API_KEY
InvalidRequestError	Invalid URL, unsupported format, bad parameters
RequestTimeoutError	Server took too long to respond
SearchError	Searching before indexing, invalid search type
VideodbError	Server errors, network issues, generic failures