Skillintermediate

完整 API 参考

VideoDB 技能参考材料。关于使用指南和工作流选择，请从 [../SKILL.md](../SKILL.md) 开始。

Claude Code Knowledge Pack7/10/2026

Overview

完整 API 参考

VideoDB 技能参考材料。关于使用指南和工作流选择，请从 ../SKILL.md 开始。

连接


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\
`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`
`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\
`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`	根据提示生成剪辑（返回流 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`
`end`	`float\	None`	`None`
`target`	`str\	dict`	`"vertical"`
`mode`	`str`	`ReframeMode.smart`	`"simple"`（中心裁剪）或 `"smart"`（对象跟踪）
`callback_url`	`str\	None`	`None`

当未提供 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`

图像方法

方法	返回	描述
`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() 在没有匹配项时会引发 InvalidRequestError，并附带消息 "No results found"。请始终将搜索调用包装在 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`	如果正在初始化或处理中则为真
`meeting.is_completed`	`bool`	如果已完成则为真

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 s