完整 API 参考¶

VideoDB 技能的参考文档。使用指南和工作流选择请从 ../SKILL.md 开始。

连接¶

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)
)

返回值： Connection 对象

连接方法¶

方法	返回值	描述
`conn.get_collection(collection_id="default")`	`Collection`	获取集合（未指定 ID 时获取默认集合）
`conn.get_collections()`	`list[Collection]`	列出所有集合
`conn.create_collection(name, description, is_public=False)`	`Collection`	创建新集合
`conn.update_collection(id, name, description)`	`Collection`	更新集合
`conn.check_usage()`	`dict`	获取账户使用统计
`conn.upload(source, media_type, name, ...)`	`Video\\|Audio\\|Image`	上传到默认集合
`conn.record_meeting(meeting_url, bot_name, ...)`	`Meeting`	录制会议
`conn.create_capture_session(...)`	`CaptureSession`	创建采集会话（参见 capture-reference.md）
`conn.youtube_search(query, result_threshold, duration)`	`list[dict]`	搜索 YouTube
`conn.transcode(source, callback_url, mode, ...)`	`str`	转码视频（返回作业 ID）
`conn.get_transcode_details(job_id)`	`dict`	获取转码作业的状态和详细信息
`conn.connect_websocket(collection_id)`	`WebSocketConnection`	连接 WebSocket（参见 capture-reference.md）

转码¶

使用自定义分辨率、质量和音频设置，从 URL 转码视频。处理在服务器端完成——无需本地 ffmpeg。

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 参数¶

参数	类型	默认值	描述
`source`	`str`	必填	要转码的视频 URL（最好是可下载的 URL）
`callback_url`	`str`	必填	转码完成时接收回调的 URL
`mode`	`TranscodeMode`	`TranscodeMode.economy`	转码速度：`economy` 或 `lightning`
`video_config`	`VideoConfig`	`VideoConfig()`	视频编码设置
`audio_config`	`AudioConfig`	`AudioConfig()`	音频编码设置

返回作业 ID（str）。使用 conn.get_transcode_details(job_id) 检查作业状态。

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
)

字段	类型	默认值	描述
`resolution`	`int\\|None`	`None`	目标分辨率高度（像素）
`quality`	`int`	`23`	编码质量（数值越低质量越高）
`framerate`	`int\\|None`	`None`	目标帧率
`aspect_ratio`	`str\\|None`	`None`	目标宽高比（例如 `"16:9"`, `"9:16"`）
`resize_mode`	`str`	`ResizeMode.crop`	缩放策略：`crop`、`fit` 或 `pad`

AudioConfig¶

from videodb import AudioConfig

config = AudioConfig(mute=False)

字段	类型	默认值	描述
`mute`	`bool`	`False`	静音音频轨道

集合¶

coll = conn.get_collection()

集合方法¶

方法	返回值	描述
`coll.get_videos()`	`list[Video]`	列出所有视频
`coll.get_video(video_id)`	`Video`	获取特定视频
`coll.get_audios()`	`list[Audio]`	列出所有音频
`coll.get_audio(audio_id)`	`Audio`	获取特定音频
`coll.get_images()`	`list[Image]`	列出所有图片
`coll.get_image(image_id)`	`Image`	获取特定图片
`coll.upload(url=None, file_path=None, media_type=None, name=None)`	`Video\\|Audio\\|Image`	上传媒体
`coll.search(query, search_type, index_type, score_threshold, namespace, scene_index_id, ...)`	`SearchResult`	在集合内搜索（仅支持语义搜索；关键字和场景搜索会抛出 `NotImplementedError`）
`coll.generate_image(prompt, aspect_ratio="1:1")`	`Image`	使用 AI 生成图片
`coll.generate_video(prompt, duration=5)`	`Video`	使用 AI 生成视频
`coll.generate_music(prompt, duration=5)`	`Audio`	使用 AI 生成音乐
`coll.generate_sound_effect(prompt, duration=2)`	`Audio`	生成音效
`coll.generate_voice(text, voice_name="Default")`	`Audio`	从文本生成语音
`coll.generate_text(prompt, model_name="basic", response_type="text")`	`dict`	LLM 文本生成——通过 `["output"]` 访问结果
`coll.dub_video(video_id, language_code)`	`Video`	将视频配音为另一种语言
`coll.record_meeting(meeting_url, bot_name, ...)`	`Meeting`	录制实时会议
`coll.create_capture_session(...)`	`CaptureSession`	创建采集会话（参见 capture-reference.md）
`coll.get_capture_session(...)`	`CaptureSession`	获取采集会话（参见 capture-reference.md）
`coll.connect_rtstream(url, name, ...)`	`RTStream`	连接实时流（参见 rtstream-reference.md）
`coll.make_public()`	`None`	将集合设为公开
`coll.make_private()`	`None`	将集合设为私有
`coll.delete_video(video_id)`	`None`	删除视频
`coll.delete_audio(audio_id)`	`None`	删除音频
`coll.delete_image(image_id)`	`None`	删除图片
`coll.delete()`	`None`	删除集合

上传参数¶

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 = coll.get_video(video_id)

视频属性¶

属性	类型	说明
`video.id`	`str`	唯一视频ID
`video.collection_id`	`str`	父级集合ID
`video.name`	`str`	视频名称
`video.description`	`str`	视频描述
`video.length`	`float`	时长（秒）
`video.stream_url`	`str`	默认流URL
`video.player_url`	`str`	播放器嵌入URL
`video.thumbnail_url`	`str`	缩略图URL

视频方法¶

方法	返回值	说明
`video.generate_stream(timeline=None)`	`str`	生成流URL（可选的 `[(start, end)]` 元组时间线）
`video.play()`	`str`	在浏览器中打开流并返回播放器URL
`video.index_spoken_words(language_code=None, force=False)`	`None`	为语音搜索创建索引。如果已经索引，则使用 `force=True` 跳过。
`video.index_scenes(extraction_type, prompt, extraction_config, metadata, model_name, name, scenes, callback_url)`	`str`	索引视觉场景（返回 scene_index_id）
`video.index_visuals(prompt, batch_config, ...)`	`str`	索引视觉内容（返回 scene_index_id）
`video.index_audio(prompt, model_name, ...)`	`str`	使用 LLM 索引音频（返回 scene_index_id）
`video.get_transcript(start=None, end=None)`	`list[dict]`	获取带时间戳的转录文本
`video.get_transcript_text(start=None, end=None)`	`str`	获取完整转录文本
`video.generate_transcript(force=None)`	`dict`	生成转录文本
`video.translate_transcript(language, additional_notes)`	`list[dict]`	翻译转录文本
`video.search(query, search_type, index_type, filter, **kwargs)`	`SearchResult`	在视频内搜索
`video.add_subtitle(style=SubtitleStyle())`	`str`	添加字幕（返回流URL）
`video.generate_thumbnail(time=None)`	`str\\|Image`	生成缩略图
`video.get_thumbnails()`	`list[Image]`	获取所有缩略图
`video.extract_scenes(extraction_type, extraction_config)`	`SceneCollection`	提取场景
`video.reframe(start, end, target, mode, callback_url)`	`Video\\|None`	调整视频宽高比
`video.clip(prompt, content_type, model_name)`	`str`	基于 Prompt 生成剪辑（返回流URL）
`video.insert_video(video, timestamp)`	`str`	在时间戳处插入视频
`video.download(name=None)`	`dict`	下载视频
`video.delete()`	`None`	删除视频

调整宽高比¶

将视频转换为不同的宽高比。可选使用智能对象跟踪。处理在服务器端进行。

警告： 调整宽高比是较慢的服务器端操作。长视频可能需要几分钟，并可能超时。始终使用 start/end 限制片段，或为异步处理传递 callback_url。

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 参数¶

参数	类型	默认值	说明
`start`	`float\\|None`	`None`	开始时间（秒）（None = 开始）
`end`	`float\\|None`	`None`	结束时间（秒）（None = 视频结束）
`target`	`str\\|dict`	`"vertical"`	预设字符串（`"vertical"`, `"square"`, `"landscape"`）或 `{"width": int, "height": int}`
`mode`	`str`	`ReframeMode.smart`	`"simple"`（居中裁剪）或 `"smart"`（对象跟踪）
`callback_url`	`str\\|None`	`None`	异步通知的 Webhook URL

如果未提供 callback_url，则返回 Video 对象；否则返回 None。

音频对象¶

audio = coll.get_audio(audio_id)

音频属性¶

属性	类型	说明
`audio.id`	`str`	唯一音频ID
`audio.collection_id`	`str`	父级集合ID
`audio.name`	`str`	音频名称
`audio.length`	`float`	时长（秒）

音频方法¶

方法	返回值	说明
`audio.generate_url()`	`str`	生成用于播放的签名URL
`audio.get_transcript(start=None, end=None)`	`list[dict]`	获取带时间戳的转录文本
`audio.get_transcript_text(start=None, end=None)`	`str`	获取完整转录文本
`audio.generate_transcript(force=None)`	`dict`	生成转录文本
`audio.delete()`	`None`	删除音频

图像对象¶

image = coll.get_image(image_id)

图像属性¶

属性	类型	说明
`image.id`	`str`	唯一图像ID
`image.collection_id`	`str`	父级集合ID
`image.name`	`str`	图像名称
`image.url`	`str\\|None`	图像URL（如果是生成的图像，则可能为 `None`——请改用 `generate_url()`）

图像方法¶

方法	返回值	说明
`image.generate_url()`	`str`	生成签名URL
`image.delete()`	`None`	删除图像

时间线和编辑器¶

时间线¶

from videodb.timeline import Timeline

timeline = Timeline(conn)

方法	返回值	说明
`timeline.add_inline(asset)`	`None`	按顺序将 `VideoAsset` 添加到主轨道
`timeline.add_overlay(start, asset)`	`None`	在时间戳处叠加 `AudioAsset`、`ImageAsset` 或 `TextAsset`
`timeline.generate_stream()`	`str`	编译并获取流URL

资产类型¶

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（编辑器 API）¶

CaptionAsset 属于编辑器 API，拥有独立的时间线、轨道和剪辑系统：

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",
)

关于 CaptionAsset 的完整用法，请参阅 editor.md 中的编辑器 API。

视频搜索参数¶

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
)

注意： filter 是 video.search() 的显式命名参数。scene_index_id 通过 **kwargs 传递给 API。

重要： 当没有匹配结果时，video.search() 会抛出带有 "No results found" 消息的 InvalidRequestError。请始终使用 try/except 包裹搜索调用。对于场景搜索，请使用 score_threshold=0.3 或更高值以过滤低相关性噪声。

场景搜索请使用 search_type=SearchType.semantic 并设置 index_type=IndexType.scene。若要针对特定场景索引，请传入 scene_index_id。详情参见 search.md。

SearchResult 对象¶

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

方法	返回值	说明
`results.get_shots()`	`list[Shot]`	获取匹配剪辑的列表
`results.compile()`	`str`	将所有镜头编译为流 URL
`results.play()`	`str`	在浏览器中打开编译后的流

Shot 属性¶

属性	类型	说明
`shot.video_id`	`str`	源视频 ID
`shot.video_length`	`float`	源视频时长
`shot.video_title`	`str`	源视频标题
`shot.start`	`float`	开始时间（秒）
`shot.end`	`float`	结束时间（秒）
`shot.text`	`str`	匹配的文本内容
`shot.search_score`	`float`	搜索相关分数

方法	返回值	说明
`shot.generate_stream()`	`str`	流式传输此特定镜头
`shot.play()`	`str`	在浏览器中打开镜头流

Meeting 对象¶

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 属性¶

属性	类型	说明
`meeting.id`	`str`	唯一会议 ID
`meeting.collection_id`	`str`	父级集合 ID
`meeting.status`	`str`	当前状态
`meeting.video_id`	`str`	录制视频 ID（完成后）
`meeting.bot_name`	`str`	机器人名称
`meeting.meeting_title`	`str`	会议标题
`meeting.meeting_url`	`str`	会议 URL
`meeting.speaker_timeline`	`dict`	发言人时间线数据
`meeting.is_active`	`bool`	初始化中或处理中时为 true
`meeting.is_completed`	`bool`	完成时为 true

Meeting 方法¶

方法	返回值	说明
`meeting.refresh()`	`Meeting`	从服务器刷新数据
`meeting.wait_for_status(target_status, timeout=14400, interval=120)`	`bool`	轮询直到达到指定状态

RTStream 与 Capture¶

关于 RTStream（实时摄取、索引创建、转录），请参阅 rtstream-reference.md。

关于捕获会话（桌面录制、CaptureClient、频道），请参阅 capture-reference.md。

枚举类型和常量¶

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,
)

其他常量¶

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,
)

异常¶

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
)

异常	常见原因
`AuthenticationError`	缺失或无效的 `VIDEO_DB_API_KEY`
`InvalidRequestError`	无效 URL、不支持的格式、非法参数
`RequestTimeoutError`	服务器响应超时
`SearchError`	索引创建前搜索、无效搜索类型
`VideodbError`	服务器错误、网络问题、一般故障

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC