TwelveLabs

使用 TwelveLabs Python SDK（v1.2.1）搜索视频、生成摘要、章节、高光片段并分析视频内容。

设置

1. 1. 获取 API 密钥：https://api.twelvelabs.io
2. 安装 SDK：

1. 3. 设置环境变量：

重要提示：搜索或分析前需先建立索引

视频必须先建立索引，然后才能进行搜索或分析。在运行搜索或分析命令之前，务必先为视频建立索引并等待状态变为 Ready。

初始化客户端

以下所有代码片段均假设已进行此设置：

python
import os
from twelvelabs import TwelveLabs

client = TwelveLabs(apikey=os.environ[TWELVELABSAPIKEY])

列出索引

python
for index in client.indexes.list():
print(f{index.id}: {index.index_name})

创建索引

python
from twelvelabs.indexes import IndexesCreateRequestModelsItem

index = client.indexes.create(
index_name=my-index,
models=[
IndexesCreateRequestModelsItem(modelname=marengo3.0, modeloptions=[visual, audio]),
IndexesCreateRequestModelsItem(modelname=pegasus1.2, modeloptions=[visual, audio]),
],
addons=[thumbnail],
)
print(f已创建索引: {index.id})

同时使用两个模型：Marengo 3.0 用于搜索/嵌入，Pegasus 1.2 用于分析。

上传素材

从 URL 上传：
python
asset = client.assets.create(method=url, url=https://example.com/video.mp4)
print(f素材: {asset.id})

从本地文件上传：
python
with open(/path/to/video.mp4, rb) as f:
asset = client.assets.create(method=direct, file=f)
print(f素材: {asset.id})

素材可重复使用——上传一次，可索引到多个索引中。

为素材建立索引

python
indexed = client.indexes.indexed_assets.create(
index_id=,
asset_id=asset.id,
)
print(f已索引素材: {indexed.id})

检查索引状态

python
result = client.indexes.indexed_assets.retrieve(
index_id=,
indexedassetid=,
)
print(f状态: {result.status})

状态：pending → queued → indexing → ready（或 failed）。

轮询直至就绪

python
import time

while True:
result = client.indexes.indexed_assets.retrieve(
index_id=,
indexedassetid=indexed.id,
)
if result.status == ready:
print(f就绪。已索引素材 ID: {indexed.id})
break
if result.status == failed:
raise RuntimeError(索引失败)
print(f状态: {result.status} — 等待中...)
time.sleep(5)

列出已索引素材

python
for video in client.indexes.indexed_assets.list():
duration = video.systemmetadata.duration if hasattr(video, systemmetadata) and video.system_metadata else
filename = video.systemmetadata.filename if hasattr(video, systemmetadata) and video.system_metadata else
print(f{video.id} {filename} {duration}s)

搜索

python
results = client.search.query(
index_id=,
query_text=正在做演示的人,
search_options=[visual, audio],
)

for result in results:
print(f{result.start:.1f}s - {result.end:.1f}s 排名={result.rank} 视频={result.video_id})

结果包含时间戳（start/end，单位为秒）和相关度 rank（1 = 最相关）。

搜索选项

python
results = client.search.query(
index_id=,
query_text=你的查询,
search_options=[visual, audio], # 或 [transcription]
threshold=medium, # high, medium, low（默认）, none
group_by=video, # clip（默认）或 video
sortoption=clipcount, # score（默认）或 clip_count
page_limit=20, # 最多 50
)

转录搜索

python
results = client.search.query(
index_id=,
query_text=演讲者关于收入的说法,
search_options=[transcription],
transcription_options=[semantic], # semantic, lexical, 或两者（默认）
)

带过滤条件的搜索

python
import json

按时长范围过滤