用途：当任务涉及 Tavus 虚拟人、Replica/Face、PAL/Persona、生成式口播视频、实时对话视频智能体或唇形同步主播输出时使用。资料基于 2026-07-10 官方文档核对，API 名称、模型、套餐限制、库存形象、语言支持与价格易变，投入前需重新核实。
对象模型：Face 是 Phoenix 渲染的屏幕形象与声音，可用视频或图片 URL 训练，也可用库存形象；PAL 配置实时 CVI 的行为、知识、LLM/TTS/感知/轮次与会议参数；Conversation 是与 PAL 和 Face 的实时视频会话。旧术语仍存在：视频生成 API 的 replica_id 即 /v2/faces 返回的 Face ID；/v2/personas、persona_id、/v2/replicas 等为向后兼容别名。
路径选择：单向口播文件用异步视频生成，POST /v2/videos 传 replica_id 加 script 或 audio_url，轮询 GET /v2/videos/{video_id} 至 ready，取 download_url、stream_url、hosted_url。交互式实时智能体用 CVI：先建/选 Face 与 PAL，再 POST /v2/conversations 传 face_id 与 pal_id。需新形象先 POST /v2/faces 训练，视频训练保真度更高，图片训练更快但表情更泛化。需精确音频或非 Tavus TTS 时用 audio_url 或 CVI echo 模式。
同意与权利是硬门槛：上传任何自定义形象、声音或生物特征前，须有被描绘者明确知情同意，覆盖创建、训练素材、脚本/语言/场景/渠道、留存备份复用与撤回处理。缺失、模糊、过期或超范围时应暂停。不得未经同意创建真人、公众人物、员工、客户、未成年人或私人个体形象；不得用库存形象暗示演员本人背书观点、身份、政治、募资、新闻或敏感时事。须向终端用户披露 AI 生成内容。Tavus 要求上传素材具备必要权利与许可，禁止描绘未成年人，部分音视频样本可能含声纹与面部几何等生物数据，客户自行负责生成内容使用、备份、API 密钥与分发后果。
Face 训练：POST https://tavusapi.com/v2/faces，视频用 train_video_url，图片用 train_image_url 且必须带 voice_name，二者不可同请求。训练视频须为公开可直下链接（如预签名 S3），建议提交后至少 24 小时有效。默认模型 phoenix-4，可请求 phoenix-3。视频训练通常 3-4 小时，可轮询或回调。素材须 H.264，文件上限 750 MB；常见失败含私有/坏链接、过大、非 MP4、非 H.264、过短、帧率过低、多张脸或遮挡。
异步视频：POST https://tavusapi.com/v2/videos，必填 replica_id 与 script 或 audio_url。可选 video_name、callback_url、background_url（网页背景）、background_source_url（视频背景）、fast、transparent_background、watermark_image_url、properties。无背景字段则全屏人脸。transparent_background 仅与 fast:true 同用并输出 .webm；fast 会禁用背景生成、缩略图与流地址等。状态含 queued、generating、ready、deleted、error。
CVI/PAL：POST /v2/pals 创建 PAL，default_face_id 必填，system_prompt 除 echo 模式外必填；pipeline_mode 可为 full 或 echo，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。test_mode:true 不加入 PAL 且不影响并发限制。
生命周期与 QA：为异步视频保存请求载荷、video_id、Face ID、脚本或音频 URL、背景、时间戳、状态、进度、各类 URL 与回调；用退避轮询或消费回调，ready 后下载归档，error 时先分类再重试。Face 训练保存同意凭证、素材清单、签名 URL 到期、face_id、模型与状态。CVI 保存 PAL/Face ID、提示版本、知识文档、护栏、会话 ID、令牌、回调、转录与录制及留存决策。QA 覆盖身份同意、发音与唇形、画面背景、透明 webm 条件、字幕可访问性、CVI 加入与延迟、知识检索准确性、护栏触发、私有房间鉴权与 webhook 重试去重。常见故障含无效令牌（检查 x-api-key）、ID 不匹配、训练 URL 不可下载、素材被拒、视频卡生成等。
限制：资料未提供具体价格、套餐额度、库存形象清单与语言支持明细，需以官方最新文档为准。