媒体生成指南¶

VideoDB 提供 AI 驱动的图像、视频、音乐、音效、语音和文本内容生成。所有生成方法都位于 Collection 对象上。

前提条件¶

在调用生成方法之前，需要连接和集合引用：

import videodb

conn = videodb.connect()
coll = conn.get_collection()

图像生成¶

从文本提示生成图像：

image = coll.generate_image(
    prompt="a futuristic cityscape at sunset with flying cars",
    aspect_ratio="16:9",
)

# Access the generated image
print(image.id)
print(image.generate_url())  # returns a signed download URL

generate_image 参数¶

参数	类型	默认值	说明
`prompt`	`str`	必填	要生成图像的文本描述
`aspect_ratio`	`str`	`"1:1"`	宽高比：`"1:1"`、`"9:16"`、`"16:9"`、`"4:3"` 或 `"3:4"`
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

返回包含 .id、.name、.collection_id 的 Image 对象。生成图像的 .url 属性可能为 None——始终使用 image.generate_url() 获取可靠的签名下载 URL。

注意： 与 Video 对象（使用 .generate_stream()）不同，Image 对象使用 .generate_url() 获取图像 URL。.url 属性仅针对特定图像类型（例如缩略图）设置。

视频生成¶

从文本提示生成短视频片段：

video = coll.generate_video(
    prompt="a timelapse of a flower blooming in a garden",
    duration=5,
)

stream_url = video.generate_stream()
video.play()

generate_video 参数¶

参数	类型	默认值	说明
`prompt`	`str`	必填	要生成视频的文本描述
`duration`	`int`	`5`	时长（秒）（整数值，必须为 5 到 8）
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

返回 Video 对象。生成的视频会自动添加到集合中，并像上传的视频一样可用于时间线、搜索和编译。

音频生成¶

VideoDB 为不同的音频类型提供 3 个独立方法。

音乐¶

从文本描述生成背景音乐：

music = coll.generate_music(
    prompt="upbeat electronic music with a driving beat, suitable for a tech demo",
    duration=30,
)

print(music.id)

参数	类型	默认值	说明
`prompt`	`str`	必填	音乐的文本描述
`duration`	`int`	`5`	时长（秒）
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

音效¶

生成特定音效：

sfx = coll.generate_sound_effect(
    prompt="thunderstorm with heavy rain and distant thunder",
    duration=10,
)

参数	类型	默认值	说明
`prompt`	`str`	必填	音效的文本描述
`duration`	`int`	`2`	时长（秒）
`config`	`dict`	`{}`	附加配置
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

语音（文本朗读）¶

从文本生成语音：

voice = coll.generate_voice(
    text="Welcome to our product demo. Today we'll walk through the key features.",
    voice_name="Default",
)

参数	类型	默认值	说明
`text`	`str`	必填	要转换为语音的文本
`voice_name`	`str`	`"Default"`	要使用的语音
`config`	`dict`	`{}`	附加配置
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

3 个音频方法均返回包含 .id、.name、.length、.collection_id 的 Audio 对象。

文本生成（LLM 集成）¶

使用 coll.generate_text() 执行 LLM 分析。这是一个集合级别的方法——可以直接将任意上下文（转录文本、描述）传入提示字符串。

# Get transcript from a video first
transcript_text = video.get_transcript_text()

# Generate analysis using collection LLM
result = coll.generate_text(
    prompt=f"Summarize the key points discussed in this video:\n{transcript_text}",
    model_name="pro",
)

print(result["output"])

generate_text 参数¶

参数	类型	默认值	说明
`prompt`	`str`	必填	包含 LLM 上下文的提示
`model_name`	`str`	`"basic"`	模型层级：`"basic"`、`"pro"` 或 `"ultra"`
`response_type`	`str`	`"text"`	响应格式：`"text"` 或 `"json"`

返回带有 output 键的 dict。当 response_type="text" 时，output 为 str。当 response_type="json" 时，output 为 dict。

result = coll.generate_text(prompt="Summarize this", model_name="pro")
print(result["output"])  # access the actual text/dict

使用 LLM 的场景分析¶

结合场景提取和文本生成：

from videodb import SceneExtractionType

# First index scenes
scenes = video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 10},
    prompt="Describe the visual content in this scene.",
)

# Get transcript for spoken context
transcript_text = video.get_transcript_text()
scene_descriptions = []
for scene in scenes:
    if isinstance(scene, dict):
        description = scene.get("description") or scene.get("summary")
    else:
        description = getattr(scene, "description", None) or getattr(scene, "summary", None)
    scene_descriptions.append(description or str(scene))

scenes_text = "\n".join(scene_descriptions)

# Analyze with collection LLM
result = coll.generate_text(
    prompt=(
        f"Given this video transcript:\n{transcript_text}\n\n"
        f"And these visual scene descriptions:\n{scenes_text}\n\n"
        "Based on the spoken and visual content, describe the main topics covered."
    ),
    model_name="pro",
)
print(result["output"])

配音与翻译¶

视频配音¶

使用集合方法将视频配音为另一种语言：

dubbed_video = coll.dub_video(
    video_id=video.id,
    language_code="es",  # Spanish
)

dubbed_video.play()

dub_video 参数¶

参数	类型	默认值	说明
`video_id`	`str`	必填	要配音的视频 ID
`language_code`	`str`	必填	目标语言代码（例如：`"es"`、`"fr"`、`"de"`）
`callback_url`	`str\\|None`	`None`	接收异步回调的 URL

返回包含配音内容的 Video 对象。

转录翻译¶

在不进行配音的情况下翻译视频转录文本：

translated = video.translate_transcript(
    language="Spanish",
    additional_notes="Use formal tone",
)

for entry in translated:
    print(entry)

支持的语言：en、es、fr、de、it、pt、ja、ko、zh、hi、ar 等。

完整工作流示例¶

生成视频旁白¶

import videodb

conn = videodb.connect()
coll = conn.get_collection()
video = coll.get_video("your-video-id")

# Get transcript
transcript_text = video.get_transcript_text()

# Generate narration script using collection LLM
result = coll.generate_text(
    prompt=(
        f"Write a professional narration script for this video content:\n"
        f"{transcript_text[:2000]}"
    ),
    model_name="pro",
)
script = result["output"]

# Convert script to speech
narration = coll.generate_voice(text=script)
print(f"Narration audio: {narration.id}")

从 Prompt 生成缩略图¶

thumbnail = coll.generate_image(
    prompt="professional video thumbnail showing data analytics dashboard, modern design",
    aspect_ratio="16:9",
)
print(f"Thumbnail URL: {thumbnail.generate_url()}")

向视频添加生成的音乐¶

import videodb
from videodb.timeline import Timeline
from videodb.asset import VideoAsset, AudioAsset

conn = videodb.connect()
coll = conn.get_collection()
video = coll.get_video("your-video-id")

# Generate background music
music = coll.generate_music(
    prompt="calm ambient background music for a tutorial video",
    duration=60,
)

# Build timeline with video + music overlay
timeline = Timeline(conn)
timeline.add_inline(VideoAsset(asset_id=video.id))
timeline.add_overlay(0, AudioAsset(asset_id=music.id, disable_other_tracks=False))

stream_url = timeline.generate_stream()
print(f"Video with music: {stream_url}")

结构化 JSON 输出¶

transcript_text = video.get_transcript_text()

result = coll.generate_text(
    prompt=(
        f"Given this transcript:\n{transcript_text}\n\n"
        "Return a JSON object with keys: summary, topics (array), action_items (array)."
    ),
    model_name="pro",
    response_type="json",
)

# result["output"] is a dict when response_type="json"
print(result["output"]["summary"])
print(result["output"]["topics"])

建议¶

生成的媒体是持久的：所有生成的内容都会保存到集合中，并可重复使用。
3 个音频方法：背景音乐使用 generate_music()，音效使用 generate_sound_effect()，文本朗读使用 generate_voice()。没有统一的 generate_audio() 方法。
文本生成是集合级别：coll.generate_text() 不会自动访问视频内容。使用 video.get_transcript_text() 获取转录文本，并传入 Prompt。
模型层："basic" 最快，"pro" 是平衡选项，"ultra" 是最高质量。大多数分析任务使用 "pro"。
组合生成类型：为叠加层生成图像，为背景生成音乐，为旁白生成语音，并使用时间线将它们组合起来（参见 editor.md）。
Prompt 质量很重要：描述性且具体的 Prompt 在所有生成类型中都能产生更好的结果。
图像宽高比：从 "1:1"、"9:16"、"16:9"、"4:3" 或 "3:4" 中选择。

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