twelvelabs-video-understanding

TwelveLabs 视频理解

TwelveLabs 构建视频基础模型，能够像人类剪辑师一样解读影像素材，理解视觉内容、屏幕文字、动作、声音、语音和音乐，并通过 REST API、SDK（Python、Node）、MCP 服务和 NLE 插件提供这些理解能力。此技能用于驱动该平台，为制作工作记录、搜索、描述、分段和标记视频。它不是视频生成器；TwelveLabs 不会合成或编辑像素。

以下所有易变信息均标注了验证日期。这里变化很快——在向用户引用这些信息并声称其为最新信息之前，请先通过 docs.twelvelabs.io 再次核实模型名称、限制和定价。

何时使用此技能

遇到以下任一任务时，可使用 TwelveLabs：

• 档案 / 影像素材搜索——“找出 CEO 在舞台上的所有镜头”“夜间出现红色汽车的片段”“有人在哪儿说了‘季度收益’”。针对已索引视频进行自然语言、图像或组合查询。
• 记录与标记——为原始影像素材或每日拍摄影像自动生成可记录的元数据（人物、事物、地点、动作）。
• 分段——章节、场景切换、精彩片段、说话者变更、体育赛事中的比赛动作、广告插播点。
• 视频转文本——摘要、描述、字幕、针对片段的问答、结构化 JSON 提取（例如镜头列表、合规标记）。
• 嵌入——用于自定义推荐系统、去重、相似度分析或视频 RAG 存储的多模态向量。
• 合规 / 品牌安全审核——在素材库中查找徽标、屏幕文字、口语短语或敏感内容。

不要将其用于创作视频、应用视觉特效、转码，或将其用作通用语音转文本工具（它能进行语音理解，用于搜索和分析；但如果你只需要纯转录文本，专用 ASR 的成本更低）。

两个模型系列

[文档说明 — docs.twelvelabs.io/docs/concepts/models，验证于 2026-07-10]

TwelveLabs 不只有一个模型。请根据任务选择：

	Marengo	Pegasus
用途	搜索 + 嵌入（检索）	分析 + 文本生成
输出	排序后的视频片段；向量	自然语言 / 结构化文本
当前版本	Marengo 3.0（2025 年 11 月 GA）	Pegasus 1.5（2026 年 4 月）；仍可使用 1.2
调用接口	/search、/embed	/analyze
可读取的模态	视觉、音频、屏幕文字/OCR、徽标、语音、音乐	视觉、音频、语音、屏幕文字

经验法则：如果问题是“哪些时刻/视频？” → 使用 Marengo（搜索）。如果问题是“告诉我 / 描述 / 总结 / 提取” → 使用 Pegasus（分析）。如果要为自己的向量数据库生成嵌入 → 使用 Marengo（嵌入）。一个索引可以启用一个或两个模型；只启用你会使用的模型，因为每个启用的模型都会在索引时计费。

Marengo 3.0 事实 [文档说明，验证于 2026-07-10]

• 将视频、图像、音频和文本统一到一个表示空间中；嵌入维度为 512。
• 精细识别：可检测品牌徽标、小物体、屏幕文字、拍摄技巧，还能统计物体数量。
• 视频输入：4 秒至 4 小时、≤ 4 GB、分辨率 360×360 至 5184×2160，宽高比介于 1:1 和 1:2.4 之间（支持任一方向），容器格式须可由 FFmpeg 解码。
• 语音/搜索支持英语及另外 36 种语言。
• 文本查询 / 文本嵌入输入：最多 500 个 token（原为 77 个）。
• Marengo 2.7 已于 2026-03-30 停用——仅基于 2.7 构建的索引将无法再进行搜索或检索嵌入。如果你接手了旧索引，请先检查其模型版本。

Pegasus 1.5 的事实 [已记录，已于 2026-07-10 验证]

• 支持跨多种模态的视频转文本。相比 1.2，新增：结构化视频分段、最多支持 4 张参考图像的多模态提示词、每个片段的时间范围（start_time/end_time），以及大幅扩展的上下文窗口。
• 上下文窗口：261,120 个 token，由输入和输出共用。最大响应长度：98,304 个 token（于 2026-05-28 从 65,536 提高）。默认响应长度为 4,096 个 token，通过 max_tokens 设置。
• 视频输入：4 秒到 2 小时，≤ 2 GB（注意：限制比 Marengo 更严格）。同步 /analyze 端点接受最长 1 小时的视频片段；更长的内容需使用异步 analyze 任务。
• 仅支持直接视频 URL——不支持 YouTube 或云端共享链接。
• Pegasus 1.2 仍适用于常规分析；它的 token 限制更低（提示词约 2,000 个 token，响应 ≤4,096 个 token），输入价格也更低。需要分段、参考图像或较长的结构化输出时使用 1.5；短小简单的提示词则使用 1.2 以节省成本。

实际使用 API

[已记录 — 基础地址为 https://api.twelvelabs.io，版本 v1.3，已于 2026-07-10 验证]

所有操作都围绕一个索引展开。索引是一个视频集合，并配置了用于处理这些视频的模型。

核心对象流程

Index  ──►  Asset / video upload  ──►  Indexing task (async)  ──►  ready video
                                                                      │
                     ┌────────────────────────────────────────────────┤
                     ▼                        ▼                        ▼
             /search (Marengo)        /analyze (Pegasus)        /embed (Marengo)

1. 创建索引

配置要启用哪些模型，以及每个模型要分析哪些模态。启用 Marengo 后即可搜索视频；启用 Pegasus 后即可分析视频。只有在两者都需要时才同时启用。

2. 上传并索引视频（异步）

截至 2026-07-10，以下两种方式都可用：

• 旧版单次调用 — 使用 index_id 以及 video_url（公共 URL，最大 4 GB）或 video_file（本地文件，最大 2 GB；更大的文件可通过 Multipart Upload API 上传，最大 10 GB），调用 POST /v1.3/tasks。可选的 enable_video_stream（默认值为 true；会存储 HLS 代理）和 user_metadata（包含字符串/整数/浮点数/布尔值标签的 JSON——请在上传时设置，以便之后筛选搜索结果）。返回任务 _id 和 video_id。
• 较新的基于资源的流程 — 调用 POST /assets 注册媒体，然后调用 POST /indexes/{index-id}/indexed-assets 对其进行索引。此流程将“文件已存在”与“将文件索引到此索引中”分开；同一资源需要用于多个索引时，这种方式更清晰。[已记录；文档将单次调用的 /tasks 路由标记为较旧的模式——已于 2026-07-10 验证。请确认你的 SDK 版本默认使用哪种方式。]

索引过程是异步的。轮询任务状态，直到状态变为 ready（其他状态还包括 validating、pending、indexing 和 failed）。SDK 提供了 task.wait_for_done()，因此无需自行编写轮询循环。处理需要实际的时间——每个视频预留数分钟，较长的视频需要更久；切勿假设刚上传的视频可以立即搜索。

3. 搜索（Marengo）— POST /v1.3/search

• 查询类型：文本（自然语言，≤500 个 token）、图像（查找视觉相似的片段；最多约 10 张图像），或文本与图像组合查询以提高精确度。
• **search_options：**要匹配的模态——visual 和/或 audio。可搭配 operator: "or"（默认值，召回范围更广）或 "and"（两者都必须匹配，精确度更高）。
• transcription_options：lexical、semantic 或两者兼用——用于控制语音匹配采用精确短语匹配还是基于语义的匹配。
• **范围：**每个请求只能指定一个索引。无法跨索引搜索——请根据需要一起查询的档案来设计索引。
• **结果：**按相关性排序的片段，包含 video_id、start/end（秒）、相关性 score/confidence 以及 rank（1 = 最佳）。请结合置信度等级和你自行设定的阈值，判断哪些结果值得展示给编辑；低置信度命中只是候选结果，并非答案。

4. 分析（Pegasus）—— POST /v1.3/analyze

自 /gist 和 /summarize 于 2026-02-15 移除后，这是唯一的生成式端点。/analyze 可以生成你提示的任何文本——摘要、章节列表、行动事项、镜头日志、合规备忘录——还可以通过 response_format（JSON 架构）返回结构化 JSON。

关键参数 [已记录，已于 2026-07-10 验证]：

参数	说明
video / video_id	来源：资源 ID、直接 URL 或 base64；video_id 用于预先索引的视频（Pegasus 1.2 路径）
prompt	指令
prompt_v2	带参考图像的结构化提示词（Pegasus 1.5）
temperature	0–1，默认值为 0.2——事实记录/合规场景应保持较低值
max_tokens	512–98,304（1.5）；2–4,096（1.2）
stream	NDJSON 流式传输，默认值为 true（stream_start → text_generation → stream_end）
response_format	用于确定性结构化输出的 JSON 架构
start_time/end_time	仅分析某个片段（1.5）

时长不超过 1 小时的片段可同步处理；对于更长的视频或批处理，请使用异步分析任务（每次调用的批处理最多支持 1,000 个请求）。

5. 嵌入（Marengo）—— Embed API v2

[已记录，已于 2026-07-10 验证] 两个端点：一个用于处理时长不足 10 分钟的文本、图像、音频和视频，可同步处理；另一个用于处理时长最长4 小时的音频/视频，可异步处理。异步流程：embed.v_2.tasks.create → 轮询 retrieve（processing → ready）→ 从 data 读取向量。按媒体类型定价（见下文）。将向量存储在你自己的数据库中（Qdrant、Elastic、pgvector 等）——TwelveLabs 为你提供嵌入向量；索引由你自行管理。

面向生产环境的 Pegasus 提示词编写

分析质量主要取决于提示词。以下经验法则是生产实践，并非供应商保证。

[经验法则]

• 说明要忽略什么，而不只是要寻找什么。“描述场上的动作；忽略观众镜头、回放和图形叠加层”比“描述视频”效果更好。
• **明确要求时间戳并进行交叉核对。**Pegasus 可以报告时间，但时间戳精度是已知的薄弱点——对于帧级精确剪辑，应使用 Marengo 搜索（它会返回真实片段边界），而不是相信 Pegasus 在文本中写出的时间。将分析得出的时间码视为近似值，直到通过搜索或对照素材核实。
• **为任何下游用途强制规定结构。**如果电子表格、素材箱或剪辑决策列表会使用输出，请使用 response_format，并提供明确的 JSON 架构和固定枚举。自由文本适合人类阅读；JSON 适合流水线处理。
• **事实内容使用低温度。**记录、合规和元数据使用 0.1–0.3；只有创意文案（营销简介、预告短句）才使用更高值。
• **精度很重要时，每次调用只问一个问题。**包含多个部分的长提示词会分散注意力；分别调用“列出章节”和“标记所有品牌 Logo”会更可靠，也能独立核查。
• **让陈述依据证据。**要求 Pegasus 引用支持每条陈述的视频内容（“引用屏幕上的文字”“说出你听到的声音”），这样审核者就能快速查证幻觉。

示例——将素材日志记录为结构化 JSON (仅为示例，不是必需格式)

意图：自动记录一段 30 分钟的访谈素材，以便助理剪辑师填充素材箱。 模型：Pegasus 1.5，temperature: 0.2，response_format = 以下架构。

提示词：

Log this interview footage for an editor. For each distinct segment, report:
the speaker (or "unknown"), the topic in <=8 words, whether the shot is a
close-up/medium/wide, and any on-screen lower-third text you can read verbatim.
Ignore color bars, slates, and dead air. If you cannot read text, use null —
do not guess names.

response_format 架构（节选）：

{ "type": "object", "properties": { "segments": { "type": "array", "items": {
  "type": "object",
  "properties": {
    "start": {"type":"number"}, "end": {"type":"number"},
    "speaker": {"type":["string","null"]},
    "topic": {"type":"string"},
    "shot_size": {"type":"string","enum":["close-up","medium","wide"]},
    "lower_third": {"type":["string","null"]}
  }, "required": ["start","end","topic","shot_size"] } } } }

原因：枚举值可确保 shot_size 内容规范；使用 null 而不是猜测名称，可以减少身份幻觉；“逐字记录/不要猜测”指令是防止自信捏造的主要手段。 可能的失效模式：编造字幕条中的姓名（通过 null 规则缓解）、时间戳偏差 1–3 秒（剪辑前通过搜索核实）、将单个连续镜头过度拆分。 变体：添加 "brand_logos": {"type":"array"}，同时用于品牌安全检查；或者移除 response_format，改为要求生成面向制片人的文字概要。

示例 — 为剪辑精确检索片段 (示意示例)

意图：找出特定产品出现的所有时刻，用于制作精彩集锦。 模型：Marengo 3.0 搜索（不是分析——你需要真实的片段边界）。

请求格式：

POST /v1.3/search
index_id: <reel_index>
query_text: "close-up of the blue running shoe, product clearly visible"
search_options: ["visual"]
operator: "and"          # tighten precision; drop to "or" if recall is low
threshold / page_limit applied client-side on the returned score

为何仅视觉 + and：目标是视觉对象，音频无关紧要，而且在精彩集锦中，精确度比捕捉所有边界模糊的画面更重要。 预期结果：按相关性排序的片段，带有可直接放入时间线的有效 start/end（这正是 Premiere 插件在底层执行的操作）。 失败情况：模型匹配到外观相似的鞋子（添加实际产品的图像查询以消除歧义——对于特定 SKU，文本 + 图像组合的效果要强得多）；极短暂的出镜排名较低（降低阈值并手动检查）。

媒体制作集成模式

[已记录并验证，2026-07-10]

• Adobe Premiere Pro 插件 — 提供包含 Project / Ingest / Search / Segment / Settings 选项卡的面板。Ingest 会上传并为 proxy 文件建立索引；Search 会返回缩略图网格，你可以在源监视器中预览，或将其放到时间线上（入点/出点已设置）；Segment 会自动生成章节/精彩片段，你可以将其作为剪辑添加。需要 Premiere Pro CC 2024–2025；只有通过插件摄取的素材可以搜索；在共享项目中请禁用自动扫描。对于不想接触 API 的剪辑师，这是最快的方式。
• Avid Media Composer 集成已推出 [第一方/社区报告，2026]，可在 Avid 工作室中完成相同的摄取→搜索→剪辑流程。
• MCP 服务 — 将索引、语义搜索、分析和嵌入作为 MCP 工具提供，让 Agent（Claude Desktop、Cursor、Windsurf、自定义 Agent 或 TwelveLabs Claude Code 插件）可以将“搜索视频”和“分析视频”作为一等操作。由你作为编排 Agent，而不是自己调用 REST 时，请使用此方式。
• Amazon Bedrock — Marengo 和 Pegasus 可通过 Bedrock 使用，适合已标准化使用 AWS/IAM 并希望采用托管访问方式的工作室。
• MASV、Mux、Elastic、Qdrant、n8n — 围绕核心模型提供传输（素材集→剪辑师交接）、流媒体/合规，以及向量存储/自动化胶水。

能力限制与注意事项

[除非特别标注，均为已记录]

• 格式/大小上限因模型而异 — Marengo 最长 4 h / 4 GB，Pegasus 最长 2 h / 2 GB，同步分析最长 1 h。上传限制：URL ≤ 4 GB，本地单次调用 ≤ 2 GB，分段上传 ≤ 10 GB。请按任务检查两项限制中更严格的一项。
• 重要操作都采用异步方式 — 索引和耗时较长的分析/嵌入均为任务，而非即时调用。请加入轮询/wait_for_done，并向用户展示“处理中”状态。
• 每次搜索只能使用一个索引。 请围绕需要共同查询的内容规划索引边界。
• 不输出像素内容。 不执行裁剪、转码或渲染——TwelveLabs 告诉你在哪里以及是什么；剪辑由你的 NLE 或 ffmpeg 完成。
• 免费套餐限制 (已于 2026-07-10 验证)：600 分钟免费索引时长，索引可访问 90 天，每个索引 100 个视频，5 个并发任务。不适用于持续的生产工作。
• 弃用影响重大 — /gist 和 /summarize 已移除（2026-02-15）；Marengo 2.7 已停止支持（2026-03-30）；云到云集成已弃用（2025-10-31）。旧教程会提到已失效的端点。

定价与配额计算

[有文档记录——Developer（按量付费）套餐，twelvelabs.io/pricing，已于 2026-07-10 核实。引用前请重新核实；如需实际估算，请使用官方定价计算器。]

操作	价格
视频索引（一次性）	$0.042 / 分钟
存储/基础设施（每月）	$0.0015 / 分钟
搜索 API	$4 / 1,000 次查询
分析 — 输入视频（Pegasus 1.5）	$0.0292 / 分钟（1.2：$0.021/分钟）
分析 — 输出文本	$0.0075 / 1,000 个令牌
嵌入 — 视频	$0.042 / 分钟
嵌入 — 音频	$0.0083 / 分钟
嵌入 — 图像	$0.10 / 1,000 次请求
嵌入 — 文本	$0.07 / 1,000 次请求

估算示例 (仅作说明，按 2026-07-10 的费率计算)：一次性为 100 小时的素材建立索引 = 6,000 分钟 × $0.042 ≈ $252，另加每月约 $9 的存储费。随后进行 1,000 次搜索 ≈ $4。为 20 分钟的片段生成摘要：20 × $0.0292（输入）+ 约 2k 个输出令牌 × $0.0075/1k ≈ $0.60/片段。日志记录工作流中的主要成本通常是分析输入分钟数，而不是输出令牌——只分析必要的片段；纯检索则优先使用按查询计费的搜索。

速率限制具有多维度（视频/音频/图像/文本分别设有预算），并按月度支出分级；添加付款方式后会从 Tier 1 开始，支出达到条件后自动升级，降级时有一个月的宽限期。各等级的确切 RPM 并未公布为固定数值——读取 429 响应头并进行退避，不要将假设写死。[分级结构有文档记录；具体数值未固定——已于 2026-07-10 核实。]

输出质量审查

切勿未经审查就交付模型输出。主要有两类问题：

1. 生成式（Pegasus）输出中的幻觉 [经验法则] 摘要和日志可能会以肯定、看似合理却错误的方式陈述事实——例如编造姓名、错误归属引言，或描述未曾发生的事件。防范方法：使用较低的温度；加入“不要猜测／使用 null”指令；要求提供证据锚点（逐字记录的屏幕文字、对声音的描述），以便审查者抽查；让提示词只专注于单一目的。凡涉及法律、合规或出版的内容，都应由人工对照素材核实——应将 Pegasus 视为快速初步记录工具，而非权威记录来源。

2. 时间戳准确性 [经验法则 + 有文档记录的限制] Pegasus 写入正文的时间为近似值，可能相差几秒——用于制作人员的章节列表尚可，但不适用于帧级精准剪辑。边界必须准确时，请从 Marengo 搜索结果（start/end）中获取时间，这些结果是模型实际检测到的片段，并在时间线上确认。搜索置信度是有效信号：设置阈值，将低于阈值的命中视为待审查线索，而不是结果。

还应审查：完整性（是否遗漏片段？长视频加上较小的 max_tokens 可能会静默截断——检查 finish_reason）、语言覆盖（支持 36 种以上语言，但应抽样验证非英语语音匹配情况），以及品牌／合规搜索中的误报（视觉相似不代表就是实际的徽标／产品；请使用图像查询确认）。

隐私、同意与权利

[有据可查 — twelvelabs.io/privacy-policy — 加上生产环境义务，已于 2026-07-10 核实]

索引包含真实人物的视频素材会产生与生物特征相关的处理（面部、声音、可识别个人）。TwelveLabs 的政策规定，客户有责任确保对其通过服务处理的个人数据具有合法依据并取得适当同意；TwelveLabs 作为处理者，为欧洲经济区／英国个人支持数据主体权利（访问、更正、删除、可携带）。

在索引包含可识别人物的视频素材之前，Agent 应：

• 确认用户拥有该视频素材的权利／授权书，并有合法依据处理面部／声音——生物识别法律（例如伊利诺伊州《生物特征信息隐私法》（BIPA）、GDPR 特殊类别数据）可能要求明确同意，并会带来实际处罚。这属于不得擅自假定的领域：没有提醒用户其义务时，不要仅凭用户的说法就索引第三方或抓取的人物视频素材。
• 优先采用最短保留期限——免费计划已将索引的有效期设为 90 天；对于生产环境，应在任务结束时删除索引／资源。请注意，截至 2026-04-26，默认会拒绝删除被引用资源的请求，因此应根据依赖关系规划删除。
• 避免在缺乏书面记录的合法依据和主体同意的情况下，建立长期身份数据库（“在所有视频素材中永久查找某个指定人物”）——这属于法律风险较高的面部识别用途，并非日常记录。
• 对生成的元数据（可能会断言某人的身份／言论），应采用与视频素材相同的审核和访问控制。

当用户要求索引或搜索他们可能无权处理的真实人物视频素材时，应提出同意／权利问题，而不是悄然继续操作。

主要来源

[均已于 2026-07-10 核实]

• 模型概览与概念 — https://docs.twelvelabs.io/docs/concepts/models，/models/marengo，/models/pegasus
• 发行说明（版本、停用、令牌限制）— https://docs.twelvelabs.io/docs/get-started/release-notes
• API 介绍、搜索指南、分析与嵌入参考 — https://docs.twelvelabs.io/api-reference/introduction，/docs/guides/search，/api-reference/analyze-videos/analyze，/api-reference/create-embeddings-v2
• 上传／任务 — https://docs.twelvelabs.io/api-reference/upload-content/tasks/create
• 定价与速率限制 — https://www.twelvelabs.io/pricing，https://docs.twelvelabs.io/docs/get-started/rate-limits
• Adobe Premiere 插件与合作伙伴集成 — https://docs.twelvelabs.io/docs/resources/partner-integrations/adobe-premiere-pro-plugin
• MCP 服务 — https://docs.twelvelabs.io/docs/advanced/model-context-protocol，https://www.twelvelabs.io/blog/twelve-labs-mcp-server
• Marengo 3.0 发布 — https://press.aboutamazon.com/aws/2025/12/twelvelabs-launches-its-most-powerful-video-understanding-model-marengo-3-0-on-twelvelabs-and-amazon-bedrock
• 隐私政策 — https://www.twelvelabs.io/privacy-policy
• Python SDK — https://github.com/twelvelabs-io/twelvelabs-python