resemble-detect

Resemble Detect — Deepfake 检测与媒体安全

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

核心原则 — 铁律

“绝不在检测结果完成前，宣称媒体内容真实或虚假。”

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

适用场景

当用户的请求涉及以下任一事项时，请使用此工具：

• 检查音频、视频、图像或文本是否由 AI 生成或经过篡改
• 检测任何媒体格式中的 deepfake
• 验证媒体的真实性或来源
• 识别合成音频所用的 AI 平台（来源追踪）
• 为媒体添加或检测水印
• 分析媒体中的说话人信息、情绪、转录内容或虚假信息
• 用自然语言询问检测结果
• 根据已知的语音档案匹配或验证说话人身份
• 检测 AI 生成或机器撰写的文本
• 提及以下任一内容：“deepfake”“虚假检测”“合成媒体”“语音验证”“水印”“媒体取证”“真实性检查”“来源追踪”“这是真的吗”“AI 撰写的文本”“文本检测”

不要将此工具用于文本转语音生成、语音克隆或语音转文本转录——这些属于 Resemble 的其他功能。

功能决策树

用户想要……	使用此功能	API 端点
检查媒体是否由 AI 生成 / 是否为 deepfake	Deepfake 检测	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

当多项功能都适用时（例如，用户既要检测 deepfake，也要进行情报分析），请使用 intelligence: true 标志，在一次 POST /detect 调用中组合这些功能，而不是分别发起请求。

必需设置

• API 密钥：来自 Resemble AI 控制面板的 Bearer 令牌
• 基础 URL：https://app.resemble.ai/api/v2
• 身份验证标头：Authorization: Bearer <RESEMBLE_API_KEY>
• 媒体要求：所有媒体都必须托管在可公开访问的 HTTPS URL 上

如果用户提供的是本地文件路径而非 URL，请告知他们必须先将文件托管到公开的 HTTPS URL 上。不要尝试将本地文件上传到 API。

可用的 MCP 工具

连接 Resemble MCP 服务后，请使用以下工具，而非直接调用 API：

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

工具使用模式：先使用主题为 "detect" 的 resemble_docs_lookup 全面了解相关信息，然后使用 resemble_api_endpoint 获取准确的请求／响应架构，再调用 API。

---

阶段 1：深度伪造检测

核心功能。提交任意音频、图像或视频，分析其中由 AI 生成的内容。

提交检测

POST /detect
Content-Type: application/json
Authorization: Bearer <API_KEY>

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

参数：

参数	类型	必填	描述
url	string	是	指向音频、图像或视频文件的 HTTPS URL
callback_url	string	否	用于异步完成通知的 Webhook URL
visualize	boolean	否	生成热力图／可视化结果
intelligence	boolean	否	在检测的同时运行多模态智能分析
audio_source_tracing	boolean	否	识别合成伪造音频的 AI 平台
frame_length	integer	否	音频／视频分析窗口大小，单位为秒（1–4，默认值为 2）
start_region	number	否	要分析片段的起始位置（秒）
end_region	number	否	要分析片段的结束位置（秒）
model_types	string	否	"image" 或 "talking_head"（用于人脸替换检测）
use_reverse_search	boolean	否	启用反向图像搜索（仅限图像）
use_ood_detector	boolean	否	启用分布外检测
zero_retention_mode	boolean	否	检测完成后自动删除媒体

支持的格式：

• 音频：WAV、MP3、OGG、M4A、FLAC
• 视频：MP4、MOV、AVI、WMV
• 图像：JPG、PNG、GIF、WEBP

轮询结果

检测为异步任务。轮询 GET /detect/{uuid}，直到 status 为 "completed" 或 "failed"。

GET /detect/{uuid}
Authorization: Bearer <API_KEY>

**轮询最佳实践：**先以 2 秒为间隔轮询，再逐渐延长至 5 秒，然后延长至 10 秒。根据媒体长度，大多数检测会在 10–60 秒内完成。

按媒体类型读取结果

音频结果——位于 metrics 中：

{
  "label": "fake",
  "score": ["0.92", "0.88", "0.95"],
  "consistency": "0.91",
  "aggregated_score": "0.92",
  "image": "https://..."
}

• label："fake" 或 "real"——判定结果
• score：每个片段的预测分数（数组）
• aggregated_score：总体置信度（0.0–1.0，数值越高，越可能是合成内容）
• consistency：各片段之间预测结果的一致程度
• image：可视化热力图 URL（如果 visualize: true）

图像结果——位于 image_metrics 中：

{
  "type": "ImageAnalysis",
  "label": "fake",
  "score": 0.87,
  "image": "https://...",
  "ifl": { "score": 0.82, "heatmap": "https://..." },
  "reverse_image_search_sources": [
    { "url": "...", "title": "...", "verdict": "known_fake", "similarity": 0.95 }
  ]
}

• label / score：判定结果和置信度
• ifl：带热力图的隐形频率层分析
• reverse_image_search_sources：在线找到的已知来源（如果 use_reverse_search: true）

视频结果——位于 video_metrics 中：

{
  "label": "fake",
  "score": 0.89,
  "certainty": 0.91,
  "children": [
    {
      "type": "VideoResult",
      "conclusion": "Fake",
      "score": 0.89,
      "timestamp": 2.5,
      "children": [...]
    }
  ]
}

• 帧级和片段级结果组成的分层树结构
• 每个子项包含 timestamp、score、certainty，还可能包含嵌套的 children
• 带音轨的视频会同时返回 metrics（音频）和 video_metrics（视觉）

解读分数

分数范围	解读
0.0 – 0.3	强烈表明媒体真实可信
0.3 – 0.5	无法得出结论 — 建议进一步分析
0.5 – 0.7	可能为合成媒体 — 标记以供审核
0.7 – 1.0	高置信度判定为合成媒体／AI 生成内容

务必结合上下文说明分数。 应表述为“检测得分为 0.87，表明这段音频很可能由 AI 生成”，切勿只说“这是假的”。

---

第 2 阶段：智能分析 — 媒体分析

对媒体进行分析，获取丰富的结构化洞见，可独立于检测运行，也可与检测结合运行。

独立智能分析

POST /intelligence
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "url": "https://example.com/audio.mp3",
  "json": true
}

参数：

参数	类型	必填	描述
url	string	二选一	媒体文件的 HTTPS URL
media_token	string	二选一	安全上传所得的令牌（作为 URL 的替代项）
detect_id	string	否	要关联的现有检测的 UUID
media_type	string	否	"audio"、"video" 或 "image"（自动检测）
json	boolean	否	返回结构化字段（默认：音频／视频为 false，图像为 true）
callback_url	string	否	异步模式下使用的 Webhook

音频／视频结构化响应（json: true）：

• speaker_info — 说话者描述（年龄、性别）
• language / dialect — 检测到的语言
• emotion — 检测到的情绪状态
• speaking_style — 对话、正式等
• context — 推断出的讲话背景
• message — 内容摘要
• abnormalities — 媒体中检测到的异常
• transcription — 完整转录文本
• translation — 非英语内容的翻译
• misinformation — 错误信息分析

图像结构化响应：

• scene_description — 图像展示的内容
• subjects — 识别出的人物／物体
• authenticity_analysis — 视觉真实性评估
• context_and_setting — 环境描述
• abnormalities — 视觉异常
• misinformation — 错误信息分析

检测智能分析 — 针对结果提问

检测完成后，可用自然语言提出相关问题：

POST /detects/{detect_uuid}/intelligence
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "query": "How confident is the model that this audio is fake?"
}

此操作会返回一个问题 UUID。轮询 GET /detects/{detect_uuid}/intelligence/{question_uuid}，直到 status 为 "completed"，即可获取 answer。

建议提出的优质问题：

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

状态流转： pending → processing → completed（或 failed）

前提条件： 检测的 status 必须为 "completed"。针对正在处理或已失败的检测提交问题会返回 422 错误。

---

第 3 阶段：音频来源追踪

当音频被检测为合成内容（label: "fake"）时，识别生成该音频的 AI 平台。

在 POST /detect 请求中将 audio_source_tracing: true 设为启用此功能。

结果会显示在检测响应的 audio_source_tracing 字段下：

{
  "label": "elevenlabs",
  "error_message": null
}

已知来源标签包括：resemble_ai、elevenlabs、real 等，随着模型扩展还会增加其他标签。

重要： 仅当音频被标记为 "fake" 时才会运行来源追踪。如果音频被标记为 "real"，则不会显示来源追踪结果。

独立查询：

• GET /audio_source_tracings — 列出所有来源追踪报告
• GET /audio_source_tracings/{uuid} — 获取指定报告

---

阶段 4：水印

为媒体添加不可见水印以追踪来源，或检测现有水印。

添加水印

POST /watermark/apply
Content-Type: application/json
Authorization: Bearer <API_KEY>
Prefer: wait

{
  "url": "https://example.com/image.png",
  "strength": 0.3,
  "custom_message": "my-organization"
}

参数	类型	必填	描述
url	string	是	媒体文件的 HTTPS URL
strength	number	否	水印强度 0.0–1.0（仅适用于图像/视频，默认值为 0.2）
custom_message	string	否	要嵌入的自定义消息（仅适用于图像/视频，默认值为 "resembleai"）

• 添加 Prefer: wait 标头以获取同步响应
• 如果不添加，则轮询 GET /watermark/apply/{uuid}/result
• 响应包含 watermarked_media URL，可用于下载添加水印后的文件

检测水印

POST /watermark/detect
Content-Type: application/json
Authorization: Bearer <API_KEY>
Prefer: wait

{
  "url": "https://example.com/suspect-image.png"
}

音频检测结果：

{ "has_watermark": true, "confidence": 0.95 }

图像/视频检测结果：

{ "has_watermark": true }

---

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

创建声音身份档案，并将传入音频与这些档案进行匹配。

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

创建身份档案

POST /identity
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "audio_url": "https://example.com/known-speaker.wav",
  "name": "Jane Doe"
}

与已知身份进行匹配

POST /identity/search
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "audio_url": "https://example.com/unknown-speaker.wav",
  "top_k": 5
}

响应：

{
  "success": true,
  "item": [
    { "uuid": "...", "name": "Jane Doe", "confidence": 0.92, "distance": 0.08 }
  ]
}

distance 越低，匹配度越高。confidence 越高，匹配结果越可靠。

---

阶段 6：文本检测

检测文本内容是由 AI 生成还是由人类撰写。

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

提交文本检测

POST /text_detect
Content-Type: application/json
Authorization: Bearer <API_KEY>

添加 Prefer: wait 标头以获取同步（阻塞）响应。如果不添加，任务将异步运行——请轮询或使用回调。

参数：

参数	类型	必填	描述
text	string	是	要分析的文本（最多 100,000 个字符）
thinking	string	否	始终使用 "low"（默认值）
threshold	float	否	判定阈值 0.0–1.0（默认值：0.5）
callback_url	string	否	用于异步完成通知的 Webhook URL
privacy_mode	boolean	否	如果为 true，分析后不会存储文本内容

响应：

{
  "success": true,
  "item": {
    "uuid": "abc-123",
    "status": "completed",
    "prediction": "ai",
    "confidence": 0.91,
    "text_content": "This is some text to analyze.",
    "privacy_mode": false,
    "created_at": "...",
    "updated_at": "..."
  }
}

• prediction："ai" 或 "human" — 判定结果
• confidence：0.0–1.0，数值越高，对预测结果的置信度越高
• status："processing"、"completed" 或 "failed"

轮询结果

如果未使用 Prefer: wait，请持续轮询，直到 status 为 "completed" 或 "failed"：

GET /text_detect/{uuid}
Authorization: Bearer <API_KEY>

列出文本检测记录

GET /text_detect
Authorization: Bearer <API_KEY>

返回团队的分页文本检测记录。

回调

如果提供了 callback_url，完成时会发送 POST 请求：

{ "success": true, "item": { ... } }

失败时：

{ "success": false, "item": { ... }, "error": "Error message here" }

---

推荐工作流

完整媒体取证（最全面）

如需全面分析，请结合所有功能：

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

---

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

• 未获得检测结果就宣称内容真实可信 — 绝不要仅凭视觉或听觉检查就断言媒体内容是真实或伪造的
• 忽略分数，只报告标签 — 分数为 0.51 的 "fake" 标签与分数为 0.95 时含义大不相同
• 向 API 提交本地文件路径 — API 要求提供可公开访问的 HTTPS URL（不适用于文本检测）
• 向文本检测提交超过 100,000 个字符的文本 — 将文本拆分成多个片段，或告知用户此限制
• 过于频繁地轮询 — 从 2s 间隔开始，然后按指数退避；不要以小于 1s 的间隔循环
• 在检测完成前询问 Detect Intelligence 问题 — 这会导致 422 错误
• 期待对“real”音频进行来源追踪 — 来源追踪仅适用于标签为 "fake" 的音频
• 将测试版功能（Identity）视为可用于生产环境 — 告知用户其测试版状态
• 对敏感媒体忽略 zero_retention_mode — 用户表示媒体敏感或私密时，始终建议启用此标志
• 标志可以组合使用时仍多次单独调用 API — 在检测调用中使用 intelligence: true 和 audio_source_tracing: true，而不是单独发送请求

结果呈现指南

向用户呈现结果时：

1. 先说明判定结果 — “检测结果表明，这段音频很可能由 AI 生成（分数：0.87）”
2. 说明分数的含义 — 使用上方的分数解读表
3. 提及局限性 — 检测结果是概率性的，并非绝对证据
4. 提供可执行的后续步骤 — 视情况建议查询智能信息、追踪来源或检查水印
5. 对于无法确定的结果（0.3–0.5） — 明确说明结果无法确定，并建议使用不同参数进行进一步分析或人工审核
6. 绝不要将检测结果作为法律证据 — 检测结果是分析工具，不是法证认证

错误处理

错误	原因	解决方法
400	请求正文无效或缺少 url	检查必需参数
401	API 密钥无效或缺失	验证 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 并经过身份验证。