tavus-replica-video

Tavus 数字人视频制作

当任务涉及 Tavus 头像、数字人、面孔、PAL/人物设定、生成的对口型视频文件、实时对话视频 Agent，或由 Tavus 驱动的对口型演示者输出时，请使用此技能。

此技能中记录的事实已于 2026-07-10 对照 Tavus 官方文档、政策和定价信息核实。API 名称、模型名称、套餐限制、可用的预置数字人、语言支持、定价和政策措辞都可能变化；在确定支出、发布范围或受监管工作流之前，请再次核实。

当前的 Tavus 对象模型

Tavus 文档现在使用以下术语：

• Face：由 Phoenix 呈现的屏幕形象和声音。可以通过视频 URL 或图片 URL 训练自定义 Face，也可以使用预置 Face/数字人。
• PAL：实时 CVI 的行为、知识、管线、LLM/TTS/感知/轮流发言/会议配置。
• Conversation：使用 PAL 和 Face 的实时视频通话/会话。

API 和生产请求中仍会出现旧术语：

• Video Generation API 中的 replica_id 是 /v2/faces 返回的 Face ID。
• /v2/personas、persona_id、/v2/replicas、default_replica_id 及相关别名可能仍为向后兼容而存在。

不要强迫用户改变他们的认知模型。清晰地转述：“你的 Tavus 数字人 ID 就是视频端点所需的 Face ID。”

先选择 Tavus 路径

根据交付内容选择路径，而不是凭习惯选择。

1. 单向口播视频文件：使用异步 Video Generation。调用 POST /v2/videos，提供 replica_id 以及 script 或 audio_url；轮询 GET /v2/videos/{video_id}，直到状态变为 ready，然后获取 download_url、stream_url 和 hosted_url。
2. 交互式 AI 真人 / 实时 Agent：使用 CVI。创建或选择 Face，创建或选择 PAL，然后调用 POST /v2/conversations 并提供 face_id 和 pal_id。
3. 需要新的形象：先使用 POST /v2/faces 创建/训练 Face。追求最高保真度或用于面向客户的场景时，使用视频训练；重视速度/设置简便性而非个性化表情时，使用图片训练。
4. 需要精确音频、已获批准的配音或非 Tavus TTS：使用异步 Video API 并提供 audio_url，而不是 script；或者在应用实时提供话语内容时，使用 CVI 回声模式。
5. 需要为现有说话者视频重新匹配口型：Tavus 条款将 LipSync 定义为平台功能，但不要凭记忆假设存在某个端点或架构。承诺采用此路径之前，请检查当前的 OpenAPI 契约。如果没有可用的已记录端点，请通过异步数字人生成并提供 audio_url，或选择其他有文档说明的对口型服务提供商。

同意与权利是硬性门槛

上传任何定制面孔、肖像、声音或生物识别材料前，必须要求提供证据，证明被描绘者已明确知情并同意以下事项：

• 创建面孔／复制形象；
• 使用训练媒体；
• 生成特定脚本、语言、语境和分发渠道的内容；
• 保留、备份和重复使用生成的输出；
• 撤销同意的处理方式。

如果缺少同意、同意含糊不清、已过期或超出授权范围，则应拒绝或暂停。未经明确同意，不得创建真实人物、公众人物、员工、客户、未成年人或私人个体的复制形象。除非 Tavus 已提供所需许可，否则不得以暗示演员本人认同某些观点、状况、身份属性、政治立场、筹款活动、新闻内容或敏感时事主张的方式使用 Tavus 库存复制形象。与最终用户互动时，须明确披露其正在接触 AI 生成的内容或由 AI 驱动的 Agent。

上线时须纳入的 Tavus 政策与隐私说明：

• Tavus 要求对上传的肖像、声音和内容拥有必要的权利、许可证、同意和许可。
• 可接受使用政策要求创建客户复制形象须取得明确知情同意，并禁止创建描绘或看似描绘未成年人的复制形象。
• Tavus 表示，某些提交的音频／视频样本可能包含生物识别数据，例如声纹和面部几何信息。
• 客户须对生成媒体的使用、备份、API 密钥以及分发造成的后果负责。

面孔创建与训练工作流

当用户需要自己的演示者、品牌角色或经过同意的人物，而非库存面孔时，请使用 Face creation。

视频转面孔

已记录的事实，核实于 2026-07-10：

• API：POST https://tavusapi.com/v2/faces
• 请求正文中的字段：train_video_url
• 不要在同一请求中发送 train_image_url。
• 训练视频 URL 必须是可公开访问的直接下载链接，例如预签名 S3 URL。
• Tavus 建议提交后，所提供的素材 URL 至少保持有效 24 小时。
• 文档中的默认面孔模型为 phoenix-4；如有需要，可通过 model_name 请求 phoenix-3。
• 视频转面孔指南指出，训练通常需要 3-4 小时，可通过轮询或回调获取结果。
• 故障排除文档指出，上传媒体必须为 H.264 格式；文件大小错误表示训练视频或音频文件的上限为 750 MB。
• 面孔训练错误文档列出了常见故障：下载 URL 为私有链接或无效、文件过大、非 MP4 格式、非 H.264 格式、时长过短、FPS 过低、包含多张面孔或存在遮挡。

生产启发式建议：

• 对客户服务、高管演示、销售、教育、支持，或任何对肖像还原度有要求的输出，优先使用视频训练。
• 录制／选择干净的肩部以上训练视频：一名同意参与的成年人、面部清晰可见、光线稳定、阴影极少、无遮挡、画面中没有其他面孔、背景中性、声音清晰且没有音乐。
• 训练后，不要将源素材和同意文件保存在公开存储桶中。使用会过期的签名 URL，并在生产台账中记录过期时间。

API 示例框架：

{
  "face_name": "consented-founder-presenter",
  "train_video_url": "https://example-bucket.s3.amazonaws.com/founder-training.mp4?...",
  "callback_url": "https://example.com/tavus/webhook",
  "model_name": "phoenix-4"
}

图像转面孔

已记录的事实，核实于 2026-07-10：

• API：POST /v2/faces
• 请求正文中的字段：train_image_url
• 使用 train_image_url 时，必须提供 voice_name。
• 不要在同一请求中发送 train_video_url。
• Tavus 文档提到可用于基于图像训练的 auto_fix_training_image 选项。

生产启发式建议：

• 对原型、合成／非人类品牌角色、内部演示稿，或用户无法使用网络摄像头拍摄的情况，使用图像训练。
• 与视频训练相比，预期面部表情行为会更加通用。
• 确认所选的 voice_name 可在 Tavus 当前语音列表中使用，并已获准用于该角色／人物设定。

异步视频生成

如果需要生成可供分享、嵌入、用于广告、主动销售、赋能、产品支持或本地化变体的成品视频文件，请使用异步视频生成。

已核实的文档事实（2026-07-10）：

• API：POST https://tavusapi.com/v2/videos
• 必填请求体：replica_id，以及 script 或 audio_url 二者之一。
• replica_id 是 Face ID，尽管该端点仍使用旧字段名称。
• 可选项：video_name、callback_url、background_url、background_source_url、fast、transparent_background、watermark_image_url 和 properties。
• background_url 会将公开网站设为背景。
• background_source_url 会使用可公开下载的视频作为背景。
• 如果未设置背景字段，输出内容将只有全屏人脸。
• transparent_background: true 仅在 fast: true 时有效，并会生成 .webm 文件。
• fast: true 使用更快的精简渲染流程，并会禁用某些功能，例如背景生成、缩略图和流式 URL。
• GET /v2/videos/{video_id} 的状态值包括 queued、generating、ready、deleted 和 error。

文本脚本的 API 框架：

{
  "replica_id": "r90bbd427f71",
  "script": "Hi Maya, I reviewed your onboarding workflow and saw three places where we can remove manual follow-up...",
  "video_name": "maya-onboarding-followup",
  "background_url": "https://example.com/product",
  "callback_url": "https://example.com/tavus/video-webhook"
}

经批准音频的 API 框架：

{
  "replica_id": "r90bbd427f71",
  "audio_url": "https://example-bucket.s3.amazonaws.com/approved-es-mx-voiceover.wav?...",
  "video_name": "support-intro-es-mx",
  "background_source_url": "https://example-bucket.s3.amazonaws.com/product-loop.mp4?..."
}

Tavus 生成语音的脚本写作

这些是制作方面的经验法则，并非 Tavus API 要求。

• 准确写出需要说出的内容。除非希望模型读出方括号中的舞台指示，否则应避免使用。
• 尽量使用短句、清晰的标点和口语化表达。化身视频会立刻暴露生硬的文案。
• 如果必须确保发音准确，请将不熟悉的姓名、缩略语和产品术语改写为注音形式或通俗表达；也可以使用经外部批准的音轨。
• 个性化主动联系脚本应简短具体：说明一个关联原因、一项价值主张和一个行动号召。
• 对于培训或支持内容，采用“先展示，再讲解”的方式：将简短口播与网站或产品循环视频背景搭配，而不是让讲解者承担过多内容。
• 应将情绪语气写进台词，而不是作为隐藏指示。“这件事给您带来了困扰，我很抱歉——我们一起解决”比“[共情]”效果更好。
• 本地化时，不要只做翻译。应调整脚本以适应口语节奏、本地化惯用表达、检查发音，并在品牌声音至关重要时，使用经批准的本地化音频重新生成。

CVI / PAL 对话

当虚拟形象需要在实时房间中聆听、观看、回应、记忆、指导、支持、面试、筛选或互动时，请使用 CVI。

已记录事实，已于 2026-07-10 核实：

• API：POST /v2/pals 会创建一个用于配置 CVI 行为的 PAL。
• POST /v2/pals 必须提供 default_face_id。
• 除非使用回声模式，否则必须提供 system_prompt。
• PAL 的 pipeline_mode 可以是 full 或 echo。
• full 提供默认的端到端体验。
• echo 会关闭大多数步骤，并让 PAL 将视频与通过 Echo 事件传入的音频／文本同步。
• PAL 层可配置感知、STT、对话流程、LLM、TTS 和会议功能。
• POST /v2/conversations 使用 face_id 和 pal_id 启动实时视频对话。
• 对话请求可以包含 callback_url、conversation_name、conversational_context、custom_greeting、memory_stores、document_ids、document_tags、document_retrieval_strategy、test_mode、meeting_url、require_auth 和 max_participants。
• 根据 Tavus 文档，test_mode: true 会在不让 PAL 加入对话的情况下创建对话，并避免影响并发限制。

PAL 编写的生产实践：

• 将身份与行为分开。Face 负责呈现形象；PAL 提示词定义角色、边界、语气、目标和升级处理方式。
• 将 PAL 提示词写成实时 Agent 操作手册：包括角色、待完成的任务、受众、允许声明的内容、拒绝／升级规则、数据处理、对话成功标准和结束方式。
• 产品／公司事实资料应使用知识文档，而不是把所有事实都写进系统提示词。
• PAL 面向用户部署时，应使用防护措施和目标，而不能只依赖提示词。
• 对于自定义应用编排、外部 ASR／LLM／TTS、确定性脚本，或需要 Tavus 负责渲染语音而非决定语音内容的工作流，请使用回声模式。
• 私密房间请使用 require_auth 和会议令牌。
• 对于 Google Meet 或第三方会议，在承诺部署之前，请核实当前会议层的要求和凭据。

PAL 规划载荷示例：

{
  "pal_name": "returns-support-pal",
  "pipeline_mode": "full",
  "default_face_id": "r90bbd427f71",
  "system_prompt": "You are a calm retail returns specialist. Help customers understand return eligibility, collect only the minimum needed order context, never promise refunds outside policy, and escalate billing disputes to a human agent.",
  "document_tags": ["returns_policy", "shipping_policy"],
  "guardrail_tags": ["customer_support_safety"]
}

对话载荷示例：

{
  "face_id": "r90bbd427f71",
  "pal_id": "pcb7a34da5fe",
  "conversation_name": "returns-support-demo",
  "custom_greeting": "Hi, I can help you check return options. What did you order?",
  "callback_url": "https://example.com/tavus/conversation-webhook",
  "require_auth": true,
  "max_participants": 2
}

Webhook、生命周期与保管

运行生产任务前，务必制定生命周期计划。

对于异步视频：

• 保存请求载荷、video_id、video_name、replica_id／Face ID、脚本或音频 URL、背景 URL、创建／更新时间戳、状态、进度、download_url、hosted_url、stream_url、状态详情和回调载荷。
• 使用退避机制轮询，或接收 callback_url 事件。不要无限期阻塞在 generating 状态。
• 当 status 为 ready 时，按照项目的资源保管规则下载并归档文件；Tavus 托管链接适合作为便捷的交付链接，但不应作为唯一存档。
• 当 status 为 error 时，在重试前，先记录 status_details，并将错误归类为身份验证、ID 无效、URL 无法访问、媒体格式、提供商错误、策略／安全问题或后端临时故障。

对于人脸训练：

• 保存同意凭证引用、源媒体清单、签名 URL 有效期、face_id、face_name、模型名称、训练路径、回调载荷和最终状态。
• 妥善保管 Face ID，避免其在应用中被未授权使用。API 密钥应作为机密信息处理。

对于 CVI：

• 保存 PAL ID、Face ID、PAL 提示词／版本、知识文档 ID／标签、防护措施／目标、对话 ID、对话 URL、会议令牌、回调、转录文本、录制内容，以及删除／保留决定。
• 根据用户同意情况和部署所在地的司法管辖区，决定是否允许录制对话和保存转录文本。

QA 检查清单

对媒体和治理记录都进行 QA。

身份与同意

• 确认人物已正确同意，或使用获准的库存人脸。
• 同意范围涵盖脚本、语言、使用场景、受众、分发、保留和撤销。
• 不得使用未成年人或未经批准的公众人物。
• 在用户／观看者与虚拟形象互动或可能依赖其提供的信息时，应披露 AI 身份。

表现与语音

• 人名、公司名、产品术语和缩写的发音正确。
• 全程口型同步效果良好；检查爆破音、摩擦音、停顿和非英语短语。
• 面部动作自然，不显得僵硬、过度夸张或情绪不符。
• 音频清晰、不失真，且适合发布平台。
• 脚本听起来像真人在说话，而不是在朗读一段文字。

画面取景、背景与交付

• 面部取景、着装和背景符合品牌与渠道要求。
• 网站背景可公开访问，并能按预期滚动。
• 仅在 fast: true 时请求透明背景 .webm。
• 按需提供字幕、说明字幕和无障碍资源。
• 下载最终文件，为其命名、按需计算校验和，并存储在本地。

CVI 专项质量检查

• PAL 能在目标环境中可靠加入。
• 问候、轮流发言、打断能力、延迟、背景噪声处理和升级机制均符合体验承诺。
• 知识检索能够提供准确答案，且不会编造政策。
• 防护机制能安全拦截不允许的请求。
• 如有承诺，私密房间必须要求身份验证。
• Webhook 接收端能处理 event_type、message_type、重试、重复事件和缺少的可选字段。

常见故障及修复方法

• 访问令牌无效：检查 API 密钥、环境和请求头名称 x-api-key。
• replica_id / face_id 无效：确认端点要求旧版 replica_id 还是当前的 face_id；验证该 ID 是否属于当前 Tavus 账户。
• 无法下载训练 URL：使用可直接下载的公开／签名 URL，而非网页预览页；确保该 URL 的有效期足以让 Tavus 获取文件。
• 训练视频被拒绝：确认格式为 MP4/H.264，时长、FPS 和文件大小符合要求；画面中只有一张无遮挡的人脸，且没有其他人脸。
• 视频生成卡住：设置轮询超时，检查 Webhook 和 Tavus 状态，然后提交 video_id 和请求负载进行升级处理，不要反复提交重复请求。
• 背景缺失或不正确：确认网站／视频 URL 可公开访问、稳定且允许被录制；使用自定义视频背景时，请使用 background_source_url，而不是 background_url。
• 发音或语言不佳：将 script 改为已批准的 audio_url，缩短句子，或使用可用的语音／发音功能。
• CVI 对背景噪声作出响应：在对话流程层配置语音隔离，并在真实环境中测试。
• PAL 无法加入：检查 Tavus 状态、对话回调事件、会议配置、并发限制、test_mode，以及是否配置了有效的 PAL／默认人脸。

完整示例：个性化外呼产品视频

示例制作意图：使用经批准的 Tavus 库存 Face 或公司自有 Face，制作简短、符合同意要求的个性化销售视频。

方法：

1. 确认该 Face 已获准用于商业外呼，且不会让人误以为展示者在获批角色范围之外作出个人背书。
2. 由于交付内容是可分享的文件，请使用异步 Video Generation，而非 CVI。
3. 先生成一个试用版本；通过 QA 后再批量生成。
4. 只有在公开的产品落地页稳定且可安全抓取时，才将其用作 background_url。
5. 将每次请求和响应记录在活动台账中。

示例脚本：

Jordan，你好——我看到你的团队正在招聘入职专员，这通常意味着客户交接流程变得更加复杂。Acme Flow 可以将每次启动会转化为引导式清单，让你的团队减少追踪进度所花的时间，把更多精力用于帮助客户顺利上线。如果你愿意，我可以发送一段以你的入职页面为基础制作的两分钟演示。

示例请求：

{
  "replica_id": "r90bbd427f71",
  "script": "Hi Jordan - I saw your team is hiring onboarding specialists, which usually means your customer handoffs are getting more complex. Acme Flow can turn each kickoff into a guided checklist, so your team spends less time chasing updates and more time helping customers launch. If you want, I can send over a two-minute walkthrough built around your onboarding page.",
  "video_name": "jordan-acme-flow-outbound-pilot",
  "background_url": "https://example.com/onboarding",
  "callback_url": "https://example.com/webhooks/tavus-video"
}

QA 重点：

• 脚本听起来是否个性化，但不会让人感到毛骨悚然？
• 库存/自定义 Face 是否获得在此销售场景中使用的许可？
• 网站背景是否正确抓取？
• 是否已存档托管/下载 URL？
• 交付场景中是否披露视频由 AI 生成？

完整示例：实时支持 PAL

示例制作意图：部署一个能回答基本支持问题，并将无法确定的问题转交人工处理的 AI 虚拟人。

方法：

1. 创建或选择获准用于支持场景的 Face。
2. 创建一个 PAL，配置专用于支持场景的系统提示词、知识文档、防护措施和目标。
3. 先使用 test_mode: true 开始测试对话以验证负载，然后创建真实的私有房间进行 QA。
4. 只有在用户同意且隐私保护措施允许的情况下，才收集回调和转录内容供审核。

示例 PAL 提示词：

你是 Nova，Acme Flow 的客户支持 PAL。你的工作是帮助用户了解入职清单、集成和计费方案的适用范围。对于产品事实声明，只能使用附带的知识文档。如果客户询问法律建议、政策范围之外的退款、账户删除、安全事件，或任何涉及你无法核实的个人数据的问题，请说明需要由人工专员协助，并提出创建支持工单。除非用户要求详细说明，否则回答不得超过 90 个英文单词。

示例对话上下文：

{
  "face_id": "r90bbd427f71",
  "pal_id": "pcb7a34da5fe",
  "conversation_name": "support-qa-session-001",
  "conversational_context": "The user is testing whether Acme Flow supports Slack notifications for onboarding checklist changes.",
  "custom_greeting": "Hi, I'm Nova. I can help with Acme Flow onboarding questions. What would you like to check?",
  "require_auth": true,
  "max_participants": 2,
  "callback_url": "https://example.com/webhooks/tavus-cvi"
}

QA 重点：

• PAL 是否依据文档作答，并坦承不确定之处？
• 是否避免作出缺乏依据的政策承诺？
• 轮流发言是否自然？
• 转录内容/录音是否按照同意要求进行处理？

完整示例：使用获批音频进行本地化

示例制作意图：为创始人讲解视频制作西班牙语和法语版本，使用经过审核的精确译文和配音。

方法：

1. 确认创始人的同意涵盖本地化版本和目标分发渠道。
2. 翻译并进行创译；请母语审核人员确认对发音敏感的人名。
3. 如果需要确保配音、语速和法律文案精确无误，请在外部生成或录制最终本地化音频。
4. 为每种语言使用异步 Video API 的 audio_url。
5. 针对每种语言分别 QA 口型同步、字幕和本地化 CTA。

示例请求：

{
  "replica_id": "r90bbd427f71",
  "audio_url": "https://example-bucket.s3.amazonaws.com/founder-explainer-es-mx-approved.wav?...",
  "video_name": "founder-explainer-es-mx-v1",
  "background_source_url": "https://example-bucket.s3.amazonaws.com/product-loop-16x9.mp4?...",
  "callback_url": "https://example.com/webhooks/tavus-video"
}

QA 重点：

• 本地化的人名和法律声明是否与获批文本一致？
• 口型与语言的匹配程度是否可以接受？
• 字幕/隐藏字幕是否经过本地化，而非未经检查地直接机器翻译？
• 存档是否注明语言区域、音频版本和审核人员的批准情况？

来源说明

文档中所述内容采用的官方／权威来源：

• Tavus API 概览：https://docs.tavus.io/api-reference/overview
• Tavus 简介及 PAL／Face 术语：https://docs.tavus.io/sections/introduction
• Create Face API：https://docs.tavus.io/api-reference/faces/create-face
• Face 训练路径对比：https://docs.tavus.io/sections/faces/which-training-path
• Video-to-Face 指南：https://docs.tavus.io/sections/faces/video-to-face-quickstart
• Face 概览及平台政策说明：https://docs.tavus.io/sections/faces/overview
• Generate Video API：https://docs.tavus.io/api-reference/video-request/create-video
• 视频快速入门：https://docs.tavus.io/sections/video/quickstart
• Get Video API：https://docs.tavus.io/api-reference/video-request/get-video
• 背景自定义：https://docs.tavus.io/sections/video/background-customizations
• Create PAL API：https://docs.tavus.io/api-reference/pals/create-pal
• Create Conversation API：https://docs.tavus.io/api-reference/conversations/create-conversation
• Webhook 和回调：https://docs.tavus.io/sections/webhooks-and-callbacks
• 错误和状态详情：https://docs.tavus.io/sections/errors-and-status-details
• 故障排除：https://docs.tavus.io/sections/troubleshooting
• 可接受使用政策：https://www.tavus.io/acceptable-use-policy
• 服务条款：https://www.tavus.io/terms-of-service
• 隐私政策／生物识别数据政策：https://www.tavus.io/privacy-policy
• 定价页面，仅用于说明可能变动的套餐／语言／并发背景信息：https://www.tavus.io/pricing