resemble-detect

Resemble Detect — 深度伪造检测与媒体安全

使用 Resemble AI 平台分析音频、图像、视频和文本，检测合成篡改、AI 生成内容、水印、说话人身份，并获取媒体情报。

核心原则 — 铁律

“未获得完整的检测结果之前，绝不宣称媒体为真实或伪造。”

不要猜测、推断或臆测媒体的真实性。任何真实性结论都必须有已完成的 Resemble 检测任务作为依据，并返回 label、score 和 status: "completed"。如果检测仍在 processing，请等待。如果检测 failed，请如实说明——不要用自己的判断来替代。

何时使用

只要用户的请求涉及以下任何一项，就使用本技能：

• 检查音频、视频、图像或文本是否为 AI 生成或被篡改
• 检测任何媒体格式中的深度伪造
• 验证媒体的真实性或来源
• 识别是哪个 AI 平台合成了音频（来源溯源）
• 为媒体添加或检测水印
• 分析媒体中的说话人信息、情绪、转录或错误信息
• 就检测结果提出自然语言问题
• 对照已知声纹档案匹配或验证说话人身份
• 检测 AI 生成或机器撰写的文本
• 任何提及：“deepfake”、“fake detection”、“synthetic media”、“voice verification”、“watermark”、“media forensics”、“authenticity check”、“source tracing”、“is this real”、“AI-written text”、“text detection”

不要用于文本转语音生成、声音克隆或语音转文本转录——这些属于 Resemble 的其他独立能力。

能力决策树

用户想要……	使用此项	API 端点
检查媒体是否为 AI 生成 / 深度伪造	深度伪造检测	POST /detect
了解是哪个 AI 平台制作了伪造音频	音频来源溯源	POST /detect 带标志
从媒体获取说话人信息、情绪、转录	情报	POST /intelligence
就已完成的检测提出问题	检测情报	POST /detects/{uuid}/intelligence
为媒体添加不可见水印	水印添加	POST /watermark/apply
检查媒体是否包含水印	水印检测	POST /watermark/detect
对照已知档案验证说话人身份	身份搜索	POST /identity/search
检查文本是否为 AI 生成	文本检测	POST /text_detect
创建声纹身份档案以供将来匹配	身份创建	POST /identity

当多种能力都适用时（例如用户同时需要深度伪造检测和情报），请在一次 POST /detect 调用中使用 intelligence: true 标志将它们组合起来，而不要发起多个独立请求。

所需配置

• API 密钥：来自 Resemble AI 控制面板的 Bearer token（设置为 RESEMBLE_API_KEY）
• 基础 URL：https://app.resemble.ai/api/v2
• 认证标头：Authorization: Bearer <RESEMBLE_API_KEY>
• 媒体要求：所有媒体必须位于可公开访问的 HTTPS URL

如果用户提供的是本地文件路径而不是 URL，请告知他们该文件必须先托管在可公开访问的 HTTPS URL 上。不要尝试将本地文件上传到 API。（例外：POST /text_detect 接受内联文本内容。）

可用的 MCP 工具

当 Resemble MCP 服务已连接时，使用这些工具，而不是直接调用原始 API：

工具	用途
resemble_docs_lookup	获取任何 detect 子主题的全面文档
resemble_search	在所有文档中搜索
resemble_api_endpoint	获取任何端点的精确 OpenAPI 规范
resemble_api_search	按关键字查找端点
resemble_get_page	阅读特定的文档页面
resemble_list_topics	列出所有可用主题

工具使用模式：使用 resemble_docs_lookup 并传入主题 "detect" 以获取全貌，然后在进行 API 调用之前使用 resemble_api_endpoint 获取精确的请求/响应 schema。

完整 API 参考

每个端点的详细请求/响应 schema 都在 references/api-reference.md 中。在进行任何 API 调用之前查阅它，以验证确切的参数名称和响应结构。以下各节涵盖决策；参考文档涵盖确切的字段格式。

---

阶段 1：深度伪造检测

核心能力。通过 POST /detect 提交音频、图像或视频以进行 AI 生成内容分析。

需要考虑的关键标志：

• visualize: true — 生成热力图/可视化产物
• intelligence: true — 在检测的同时运行多模态智能分析（节省一次往返）
• audio_source_tracing: true — 识别哪个 AI 平台合成了伪造音频（仅在 "fake" 音频上触发）
• use_reverse_search: true — 启用反向图像搜索（仅限图像）
• zero_retention_mode: true — 分析后自动删除媒体（用于敏感内容）

检测是异步的。以 2s → 5s → 10s 的间隔轮询 GET /detect/{uuid}，直到 status 为 "completed" 或 "failed"。大多数在 10–60 秒内完成。

支持的格式： 音频（WAV、MP3、OGG、M4A、FLAC）· 视频（MP4、MOV、AVI、WMV）· 图像（JPG、PNG、GIF、WEBP）

读取结果

• 音频 — 判定结果在 metrics 中 — 使用 label 和 aggregated_score
• 图像 — 判定结果在 image_metrics 中 — 使用 label 和 score；ifl 具有 Invisible Frequency Layer 热力图
• 视频 — 判定结果在 video_metrics 中 — 帧/片段结果的层级树；带音频的视频会同时返回 metrics 和 video_metrics

有关完整的响应 schema，请参见 references/api-reference.md。

解读分数

分数范围	解读
0.0 – 0.3	强烈表明媒体是真实的/真实的
0.3 – 0.5	不确定 — 建议进行额外分析
0.5 – 0.7	可能是合成的 — 标记以供审查
0.7 – 1.0	高置信度为合成/AI 生成

始终结合上下文呈现分数。 说“检测返回了 0.87 的分数，表明该音频高度确信为 AI 生成”——绝不要只说“它是假的”。

---

阶段 2：Intelligence — 媒体分析

关于媒体的丰富结构化洞察：说话人信息、情绪、转录、翻译、虚假信息、异常。

运行 Intelligence 的两种方式：

1. 与检测结合 — 在 POST /detect 中添加 intelligence: true（推荐；一次调用）
2. 独立运行 — 使用 URL 调用 POST /intelligence（当你只需要分析，而不需要深度伪造判定时）

音频/视频结构化字段包括： speaker_info、language、dialect、emotion、speaking_style、context、message、abnormalities、transcription、translation、misinformation。

图像结构化字段包括： scene_description、subjects、authenticity_analysis、context_and_setting、abnormalities、misinformation。

检测 Intelligence — 针对结果提问

检测完成后，通过 POST /detects/{detect_uuid}/intelligence 并附带 { "query": "..." } 提出自然语言问题。返回一个问题的 UUID — 轮询 GET /detects/{detect_uuid}/intelligence/{question_uuid} 直到 completed。

建议提出的好问题：

• “用通俗语言总结检测结果”
• “有哪些具体指标表明这是 AI 生成的？”
• “音频和视频检测结果有何不同？”
• “置信水平是多少，它意味着什么？”
• “分析中是否存在任何不一致之处？”

前提条件： 检测必须具有 status: "completed"。对正在处理或失败的检测提交问题会返回 422。

完整参数请参见 references/api-reference.md。

---

阶段 3：音频来源追踪

当音频被标记为 "fake" 时，识别是哪个 AI 平台生成了它。

启用方式：在 POST /detect 请求中设置 audio_source_tracing: true。结果会出现在检测响应的 audio_source_tracing.label 下。

已知标签：resemble_ai、elevenlabs、real，以及随着模型扩展而增加的更多标签。

重要： 来源追踪仅对标记为 "fake" 的音频运行。真实音频不会产生来源追踪结果。

独立查询：GET /audio_source_tracings 和 GET /audio_source_tracings/{uuid}。

---

阶段 4：水印

为媒体应用不可见水印以进行来源追踪，或检测现有的水印。

• 应用：使用 url、可选的 strength（0.0–1.0）、可选的 custom_message 调用 POST /watermark/apply。添加 Prefer: wait 以同步获取响应，或轮询 GET /watermark/apply/{uuid}/result。响应包含 watermarked_media URL。
• 检测：使用 url 调用 POST /watermark/detect。音频返回 { has_watermark, confidence }；图像/视频返回 { has_watermark }。

确切的参数规则请参见 references/api-reference.md。

---

阶段 5：身份 — 说话人验证（Beta）

创建语音身份档案，并将传入的音频与它们进行匹配。

Beta 功能 — 需要加入预览计划。如果用户遇到访问错误，请告知他们。

• 创建档案：使用 { audio_url, name } 调用 POST /identity
• 搜索：使用 { audio_url, top_k } 调用 POST /identity/search

响应返回带排序的匹配结果，包含 confidence（越高 = 越匹配）和 distance（越低 = 越接近）。

完整 schema 请参见 references/api-reference.md。

---

第 6 阶段：文本检测

通过 POST /text_detect 检测文本内容是 AI 生成还是人类撰写。

Beta 功能 — 需要 detect_beta_user 角色，或包含 dfd_text 产品的计费方案。

关键参数：

• text（必填，最多 100,000 字符）
• threshold（默认 0.5）
• privacy_mode: true — 分析后不存储文本内容
• callback_url — 异步通知 webhook

添加 Prefer: wait 以获取同步响应，或轮询 GET /text_detect/{uuid}。响应包含 prediction（"ai" 或 "human"）和 confidence（0.0–1.0）。

完整 schema 和回调格式请参阅 references/api-reference.md。

---

推荐工作流

完整媒体取证（最全面）

如需进行全面分析，请组合使用所有能力：

1. 提交检测并启用所有标志：

   {
     "url": "https://example.com/suspect.mp4",
     "visualize": true,
     "intelligence": true,
     "audio_source_tracing": true,
     "use_reverse_search": true
   }
   

2. 轮询直到 status: "completed"
3. 读取 metrics / image_metrics / video_metrics 获取判定结果
4. 读取 intelligence.description 获取结构化媒体分析
5. 如果音频被标记为 "fake"，检查 audio_source_tracing.label 获取来源平台
6. 如有任何需要澄清的地方，通过 Detect Intelligence 提出后续问题
7. 如果来源溯源相关，通过 POST /watermark/detect 检查水印

快速真实性检查（最快）

1. 提交最小检测：{ "url": "..." }
2. 轮询直到完成
3. 检查 label 和 aggregated_score（音频）或 label 和 score（图像/视频）
4. 结合分数上下文报告结果

来源溯源流水线（内容创作者）

1. 为原始内容添加水印：POST /watermark/apply
2. 分发带水印的媒体
3. 之后验证来源：对任意副本执行 POST /watermark/detect

---

危险信号 — 停下来重新评估

• 在没有检测结果的情况下宣称真实性 — 绝不要仅凭视觉/听觉检查就断定媒体是真实还是虚假
• 忽略分数只报告标签 — 标记为 "fake" 且分数 0.51 与分数 0.95 的含义截然不同
• 向 API 提交本地文件路径 — API 要求可公开访问的 HTTPS URL（不适用于文本检测）
• 向文本检测发送超过 100,000 字符的文本 — 分成多个块或告知用户该限制
• 过于频繁地轮询 — 从 2 秒间隔开始，指数退避；不要以 <1s 的频率循环
• 在检测完成前向 Detect Intelligence 提问 — 会导致 422 错误
• 期望对 "real" 音频进行来源溯源 — 来源溯源仅对标记为 "fake" 的音频运行
• 将 beta 功能（Identity、Text Detection）视为生产就绪 — 警告用户 beta 状态
• 对敏感媒体忽略 zero_retention_mode — 当用户表示媒体敏感或私密时，始终建议使用此标志
• 在标志可以组合时进行多次单独的 API 调用 — 在检测调用中使用 intelligence: true 和 audio_source_tracing: true，而不是单独的请求

响应呈现指南

向用户呈现结果时：

1. 先给出判定 — “检测表明此音频很可能是 AI 生成的（分数：0.87）”
2. 提供分数上下文 — 使用上文的分数解读表
3. 说明局限性 — 检测是概率性的，并非绝对证据
4. 包含可操作的后续步骤 — 视情况建议 intelligence 查询、来源溯源或水印检查
5. 对于无定论的结果（0.3–0.5） — 明确说明结果无定论，并建议使用不同参数进行额外分析或人工审查
6. 绝不将检测结果作为法律证据呈现 — 检测结果是分析工具，而非取证认证

错误处理

错误	原因	解决方案
400	请求体无效或缺少 url	检查必需参数
401	API key 无效或缺失	验证 RESEMBLE_API_KEY
404	未找到检测 UUID	验证创建响应中的 UUID
422	检测未完成（用于 Intelligence）	等待检测达到 completed 状态
429	触发速率限制	退避并使用指数延迟重试
500	服务器错误	重试一次，然后向用户报告

隐私与合规说明

• 零保留模式：设置 zero_retention_mode: true 以在分析后自动删除媒体。URL 会被脱敏，且完成后 media_deleted 会被设为 true。
• 文本隐私模式：在文本检测时设置 privacy_mode: true，以防止分析后存储文本内容。
• 数据处理：媒体 URL 和文本内容默认会被存储。对于 GDPR/合规敏感的工作流，请启用零保留（媒体）或隐私模式（文本）。
• 回调安全：如果使用 callback_url，请确保该端点使用 HTTPS，并在接收端进行身份验证。