resemble-detect

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

使用 直接调用 Resemble AI API 分析音频、图像、视频和文本，检测合成篡改、AI 生成内容并获取媒体情报；还可查明网站访客是人还是 AI Agent。

核心原则 — 铁律

“绝不在检测结果完成前，判定媒体是真实还是伪造。”

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

同一条铁律也适用于文本。绝不要仅凭文风、语气或“读起来像 ChatGPT”就判定文本由 AI 生成或由人类撰写。文本判定必须基于已完成的 POST /text_detect 任务，且任务返回了 prediction、confidence 和 status: "completed"。

同一条铁律也适用于网站访客。绝不要根据用户代理、请求量或直觉判断网站流量来自 Agent 还是人类。访客判定依据是 Agent Detection（访问记录上的 settled 状态，或 GET /agent_detection/analytics 返回的总数）。

使用时机

当用户请求涉及以下任一事项时，请使用此技能：

• 检查音频、视频或图像是否由 AI 生成或经过篡改
• 检查文本——如作文、电子邮件、帖子、评论、文章、求职信或评论内容——是否由 AI 模型撰写（“AI 垃圾内容检测”）
• 检测任何媒体格式中的深度伪造内容
• 验证媒体的真实性或来源
• 识别合成音频的 AI 平台（来源追踪）
• 分析媒体中的说话人信息、情绪、转录内容或错误信息
• 以自然语言询问检测结果
• 执行完整调查工作流——如保险理赔、突发新闻、身份核验、证据提交——其中检测只是多个输入之一
• 查明网站访客是人还是 AI Agent、为网站添加 Agent Detection，或查看网站流量中有多少来自 Agent
• 提及以下任一内容：“深度伪造”、“伪造检测”、“合成媒体”、“媒体取证”、“真实性检查”、“来源追踪”、“这是真的吗”、“AI 撰写”、“ChatGPT 撰写”、“AI 文本”、“AI 垃圾内容”、“这是人类写的吗”、“Agent 检测”、“机器人流量”、“AI Agent 访问我的网站”、“Porter”、“这个访客是机器人吗”

不要用于文本转语音生成、语音克隆或语音转文本转录——这些属于 Resemble 的其他功能。（检测文本是否由 AI 撰写属于适用范围——请参见阶段 5。在网站上区分人类访客与 AI Agent 也属于适用范围——请参见阶段 6。）

Agent Detection 不等同于 Detect Agents。 Detect Agents（阶段 4）是 Resemble 的调查员，用于分析媒体。Agent Detection（阶段 6）用于告知网站每位访客是人类还是 AI Agent。

必需设置

• **API 密钥：**从 Resemble 控制面板获取 Bearer 令牌：https://app.resemble.ai/account/api
• **环境变量：**优先使用 RESEMBLE_API_KEY
• 基础 URL：https://app.resemble.ai/api/v2
• 身份验证标头：Authorization: Bearer $RESEMBLE_API_KEY
• 媒体输入：POST /detect 接受以下输入中的一项，且只能有一项：
  • 直接通过 multipart/form-data 上传文件，字段名为 file（最大 150 MB）；
  • 公开的 HTTPS url；或
  • 通过 POST /secure_uploads 获取的 media_token。
• 文本输入：POST /text_detect 接受包含 text 字符串的 JSON 请求体——至少 25 个单词，最多 100,000 个字符。不接受文件或 URL。

绝不要打印 API 密钥，也不要在聊天中粘贴 Bearer 令牌。在示例和命令中使用环境变量。

能力决策树

用户想要……	使用此能力	API 端点
检查媒体是否由 AI 生成／是否为深度伪造	深度伪造检测	POST /detect，然后 GET /detect/{uuid}
上传私有／本地文件，而不公开托管	直接上传	POST /detect multipart file=@...
分析大于 150 MB 且没有公开 URL 的文件	安全上传	POST /secure_uploads，然后使用 media_token 调用 POST /detect
了解 哪个 AI 平台 制作了伪造音频	音频来源追踪	使用 audio_source_tracing: true 调用 POST /detect
获取媒体中的说话人信息、情绪和转录文本	智能分析	POST /intelligence
针对已完成的检测提问	检测智能分析	POST /detects/{uuid}/intelligence，然后轮询答案
运行带有结论的托管式多步骤调查	检测 Agent	GET /agents，然后运行 POST /agents/{preset_id}/run（SSE）
检查文本是否由 AI 模型撰写	文本检测	POST /text_detect，然后 GET /text_detect/{uuid}
为网站添加真人与 Agent 检测	Agent 检测	POST /agent_detection/sites，然后安装返回的 snippet
查看网站流量中有多少来自 AI Agent	Agent 检测	GET /agent_detection/analytics、GET /agent_detection/sessions

当多个媒体能力适用时，请在单次 POST /detect 调用中通过 intelligence: true、audio_source_tracing: true、visualize: true、use_reverse_search: true 和 zero_retention_mode: true 等标志组合使用，而不要创建多个独立任务。文本检测使用单独的端点，不能与媒体检测合并。

直接 API 调用规则

1. 优先使用直接 HTTP 请求。 此技能旨在使用 curl 和 Resemble REST API，而不是 MCP 工具调用。
2. 可接受同步结果时使用 Prefer: wait。 不使用此选项时，请提交任务、记录返回的 UUID，然后轮询。
3. 轮询异步任务，直至状态结束。 结束状态为 completed 和 failed。
4. 对敏感媒体使用零留存模式。 涉及隐私时，请在媒体检测中设置 zero_retention_mode: true。
5. 仅报告已完成的结果。 处于待处理／处理中状态的任务不代表结论。

可复用的 Shell 设置

在任何命令序列开始时使用：

: "${RESEMBLE_API_KEY:?Set RESEMBLE_API_KEY first}"
BASE_URL="https://app.resemble.ai/api/v2"
AUTH_HEADER="Authorization: Bearer ${RESEMBLE_API_KEY}"

如果需要提取 JSON 且有 jq，请使用它。否则，请使用 python3 -c 'import json,sys; ...'。

---

阶段 1：深度伪造检测

提交任意音频、图像或视频，分析其中是否包含 AI 生成内容。

从公开 URL 提交检测

当媒体可通过 HTTPS 访问时使用：

curl --request POST "${BASE_URL}/detect" \
  -H "$AUTH_HEADER" \
  -H "Prefer: wait" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/media.mp4",
    "visualize": true,
    "intelligence": true,
    "audio_source_tracing": true,
    "use_reverse_search": true,
    "zero_retention_mode": true
  }'

对于异步模式，请省略 Prefer: wait，记录 .item.uuid，然后轮询 GET /detect/{uuid}。

从本地文件提交检测

支持直接上传不超过 150 MB 的文件：

curl --request POST "${BASE_URL}/detect" \
  -H "$AUTH_HEADER" \
  -H "Prefer: wait" \
  -F "file=@/path/to/media.mp4" \
  -F "intelligence=true" \
  -F "visualize=true" \
  -F "audio_source_tracing=true" \
  -F "frame_length=2"

允许直接上传的扩展名包括 .wav、.mp3、.m4a、.ogg、.aac、.flac、.amr、.3gp、.3gpp、.mp4、.mov、.avi、.mkv、.webm、.jpg、.jpeg、.png、.gif 和 .webp。

使用安全上传令牌提交检测

当文件大于 150 MB 或不应公开托管时，请使用安全上传。首先上传文件：

curl --request POST "${BASE_URL}/secure_uploads" \
  -H "$AUTH_HEADER" \
  -F "file=@/path/to/media.mp4"

然后将返回的令牌作为 media_token 提交：

curl --request POST "${BASE_URL}/detect" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  --data '{
    "media_token": "SECURE_UPLOAD_TOKEN",
    "intelligence": true,
    "visualize": true,
    "zero_retention_mode": true
  }'

安全上传令牌的有效期很短，请尽快使用。

检测参数

参数	类型	必填	描述
file	file	二选一	多部分文件上传，最大 150 MB
url	string	二选一	指向音频、图像或视频文件的公开 HTTPS URL
media_token	string	二选一	来自 POST /secure_uploads 的令牌
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	否	要分析片段的结束位置（秒）
max_video_secs	number	否	限制处理的视频时长
model_types	string	否	用于视频换脸检测的 "image" 或 "talking_head"
use_reverse_search	boolean	否	启用反向图像搜索（仅限图像）
use_ood_detector	boolean	否	启用分布外检测
zero_retention_mode	boolean	否	检测完成后自动删除提交的媒体

必须且只能提供 file、url 或 media_token 中的一项。

轮询检测结果

DETECT_UUID="..."
curl --request GET "${BASE_URL}/detect/${DETECT_UUID}" \
  -H "$AUTH_HEADER"

轮询最佳实践：先以 2 秒间隔开始，之后延长至 5 秒，再延长至 10 秒。当 item.status 为 completed 或 failed 时停止。

如果需要一个简单的轮询辅助函数：

DETECT_UUID="..."
for delay in 2 2 5 5 10 10 10 10 10 10; do
  response=$(curl -sS "${BASE_URL}/detect/${DETECT_UUID}" -H "$AUTH_HEADER")
  printf '%s\n' "$response"
  status=$(printf '%s' "$response" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("item",{}).get("status",""))')
  [ "$status" = "completed" ] && break
  [ "$status" = "failed" ] && break
  sleep "$delay"
done

按媒体类型读取结果

音频结果 — 位于 item.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：当 visualize: true 时提供的可视化热力图 URL

图像结果 — 位于 item.image_metrics 中：

{
  "type": "FinalResult",
  "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 }
  ]
}

视频结果 — 位于 item.video_metrics 中；如果视频带有音频，音频指标位于 item.metrics 中：

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

解读分数

分数范围	解读
0.0 – 0.3	媒体真实／未经篡改的强烈迹象
0.3 – 0.5	无法确定 — 建议进行额外分析
0.5 – 0.7	可能为合成内容 — 标记以供审查
0.7 – 1.0	高置信度判定为合成／AI 生成内容

始终结合上下文呈现分数。请说“检测结果分数为 0.87，表明有很高的置信度认为该媒体由 AI 生成”，不要只说“这是假的”。

---

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

独立分析媒体，或在检测的同时分析媒体，以获取丰富的结构化洞见。

独立智能分析

curl --request POST "${BASE_URL}/intelligence" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/audio.mp3",
    "media_type": "audio"
  }'

默认情况下，POST /intelligence 为同步请求。如果提供 callback_url，则会变为异步请求，并返回一条智能分析记录，你可以通过 GET /intelligences/{uuid} 轮询该记录。

参数：

参数	类型	必填	描述
url	string	二选一	媒体文件的 HTTPS URL
media_token	string	二选一	安全上传返回的令牌
detect_id	string	否	要关联的现有检测的 UUID
media_type	string	否	"audio"、"video" 或 "image"（省略时自动检测）
callback_url	string	否	用于异步完成通知的 Webhook

**音频／视频智能分析可能包含：**说话人信息、语言／方言、情绪、说话风格、语境、消息摘要、异常、转录、翻译和错误信息分析。

**图像智能分析可能包含：**场景描述、主体、真实性分析、语境／场景、异常和错误信息分析。

获取智能分析结果

INTELLIGENCE_UUID="..."
curl --request GET "${BASE_URL}/intelligences/${INTELLIGENCE_UUID}" \
  -H "$AUTH_HEADER"

检测智能分析 — 针对已完成的检测提问

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

DETECT_UUID="..."
curl --request POST "${BASE_URL}/detects/${DETECT_UUID}/intelligence" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  --data '{"query": "Summarize the detection results in plain language."}'

此请求会返回一个问题 UUID。轮询直到问题状态为 completed 或 failed：

QUESTION_UUID="..."
curl --request GET "${BASE_URL}/detects/${DETECT_UUID}/intelligence/${QUESTION_UUID}" \
  -H "$AUTH_HEADER"

可建议提出以下问题：

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

前置条件：检测的 status 必须为 "completed"。针对正在处理或失败的检测提问可能会返回 422。

---

第 3 阶段：音频来源追踪

当音频被检测为合成音频时，可识别生成该音频的 AI 平台。

在 POST /detect 请求中启用此功能：

{
  "url": "https://example.com/audio.wav",
  "audio_source_tracing": true
}

结果会显示在检测响应的 item.audio_source_tracing 下：

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

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

独立查询端点：

curl --request GET "${BASE_URL}/audio_source_tracings" -H "$AUTH_HEADER"
curl --request GET "${BASE_URL}/audio_source_tracings/${TRACE_UUID}" -H "$AUTH_HEADER"

重要提示：音频标记为 fake 时，来源追踪最有用。如果音频为 real，来源追踪结果可能不存在，也可能将媒体识别为真实内容。

---

第 4 阶段：检测 Agent

Detect Agent 是由 Resemble 管理的六个调查 Agent，它们通过多步骤工作流执行检测：运行 Detect、收集佐证并进行网络调查，最后给出书面评估。如果要回答的问题是“这条声明／帖子／文档是否可信？”，而不是“这个文件是否为合成内容？”，请使用它们。

Agent	preset_id
调查社交媒体内容	investigate_social_content
审查保险理赔	review_insurance_claim
验证突发新闻媒体	verify_breaking_news
验证文档或收据	verify_document
验证提交的证据	verify_evidence
验证身份证件	verify_id

列出它们（uuid 与 preset_id 是相同的稳定标识符）：

curl --request GET "${BASE_URL}/agents" -H "$AUTH_HEADER"

运行调查

multipart/form-data，且只能包含一个主要媒体来源（file 或 url）。响应是 Server-Sent Events 流，因此请传入 --no-buffer：

curl --no-buffer --request POST "${BASE_URL}/agents/verify_document/run" \
  -H "$AUTH_HEADER" \
  -H "Accept: text/event-stream" \
  -F "file=@/path/to/receipt.pdf" \
  -F "query=Is this receipt genuine?" \
  -F "evidence[]=@/path/to/order-confirmation.png" \
  -F "check_urls=https://example.com/original-listing"

字段	必填	说明
file	二选一	要分析的媒体
url	二选一	公开的 HTTPS 媒体 URL
query	否	调查问题或目标
evidence[]	否	支持材料；有多个文件时重复此字段
check_urls	否	供 Agent 检查的其他 URL

读取流

每个数据帧的格式为 data: {json}。需要关注的数据帧：

• run_started — 包含 run_id。请保存它；即使断开连接，运行记录也会保存在服务端。
• detect — Resemble Detect 的证据，包含 label 和 score。这是 Iron Law 下的真实性判定。
• gate — 调查 Agent 是否通过检测继续执行（agent_ran）。
• tool_call / tool_result — 研究和检测步骤的实时记录。
• token / agent_message / message_end — Agent 逐步生成的叙述内容。
• final_verdict — 书面评估。intelligence 是一个字符串；Agent 使用架构时，其中可能包含序列化 JSON。
• done — 已完成。error — 流开启后发生错误（HTTP 状态仍为 200）。

Iron Law 仍然适用。 final_verdict 是 Agent 的推理，而非检测结果。切勿仅凭叙述就将媒体判定为真实或伪造——请引用 detect 数据帧中的 label 和 score。如果没有收到 detect 数据帧，请说明检测未完成。

获取过往运行记录

curl --request GET "${BASE_URL}/agents/verify_document/runs" -H "$AUTH_HEADER"
curl --request GET "${BASE_URL}/agents/verify_document/runs/${RUN_ID}" -H "$AUTH_HEADER"

运行详情会额外提供完整事件记录、配置快照，以及 Agent 执行前后的记忆——足以重现调查过程。

访问权限

列出 Agent 和读取运行历史记录只需有效的 API 密钥。启动运行需要相应权限：团队须拥有 D-Agent 层级套餐，或尚有团队的 5 次终身免费运行次数。两者都不满足时，运行端点会在流开启前以普通 JSON 返回 402 Payment Required——请先检查这一情况，不要贸然认为流已开启。GET /agents 还会返回 free_runs_remaining、free_runs_limit 和 entitled，因此建议先检查这些字段，而不要触发 402。

无法通过 API 创建或编辑 Agent；六个预设由 Resemble 管理，并在首次运行时启用。

---

第 5 阶段：文本检测

检测一段文字是由 AI 大模型生成还是由人类撰写。一个端点，每次调用检测一段文本，输入和输出均为 JSON。

访问权限： 面向使用当前计费套餐的团队（每个完成的任务计为一个 Text Detection 单位）以及 detect_beta_user 账户开放。无权访问的账户会收到 400 错误，内容为 "This feature is not available for your account"；权限额度不足的团队会收到 402。

调用前——统计词数

检测器不会对少于 25 个词的文本评分。文本长度低于此值时，没有任何模型或阈值能够区分随意的人类写作与 AI 文本，因此 API 会拒绝请求并返回 400，而不会给出猜测。请先进行检查，避免发送注定失败的请求：

TEXT="$(cat /path/to/text.txt)"
WORDS=$(printf '%s' "$TEXT" | wc -w | tr -d ' ')
if [ "$WORDS" -lt 25 ]; then
  echo "Only ${WORDS} words — the detector needs at least 25. Not enough text to judge."
fi

如果用户有同一作者的多条短消息（聊天内容、推文、评论），请将它们合并成一次请求，确保总词数达到 25 词或以上。这是获取短文本判定结果的受支持方式——请明确说明判定针对的是合并后的文本。

模型大约会读取前 350–400 个词（512 个 token）。更长的文本只会根据开头部分评分。若要覆盖整篇文档，请拆分成约 300 词的文本块，分别提交，并报告每块的结果，而不要只给出一个总数。

提交文本检测

curl --request POST "${BASE_URL}/text_detect" \
  -H "$AUTH_HEADER" \
  -H "Prefer: wait" \
  -H "Content-Type: application/json" \
  --max-time 320 \
  --data "$(python3 -c 'import json,sys; print(json.dumps({"text": sys.stdin.read()}))' < /path/to/text.txt)"

使用 jq -n --arg text "$TEXT" '{text: $text}' 或上面的 python3 单行命令构建 JSON 请求体——切勿将原始文本粘贴到手写的 JSON 字符串中，因为引号和换行符会导致请求出错。

参数：

参数	类型	必填	描述
text	string	是	要分析的文本。至少 25 个单词，最多 100,000 个字符。按原样发送；服务端会规范化 Unicode、不可见字符和弯引号。
threshold	float	否	模型 AI 概率的判定阈值，范围为 0.0–1.0（默认值为 0.5）。除非用户测得了不同的工作点，否则请保留默认值。
thinking	string	否	"low"（默认值）、"medium" 或 "high"。请保持为 "low"。
callback_url	string	否	HTTPS Webhook；完成时会调用，并传入 { "success": true, "item": {...} }，失败时则传入 { "success": false, "item": {...}, "error": "..." }。
zero_retention_mode	boolean	否	如果为 true，提交的文本不会被存储，响应中也会省略 text_content。也接受别名 privacy_mode。

同步与异步——此端点有所不同

Prefer: wait 会以内联方式运行推理，并在同一响应中返回已完成的条目。热请求大约需要 2 秒，但文本模型在空闲时会缩至零；空闲后首次请求可能需要 3–4 分钟来加载。因此示例使用了 --max-time 320。不要把长时间等待当作请求卡住；耐心等待一次，仅在确实超时或收到 5xx 时重试。

如果不使用 Prefer: wait，响应会立即返回，状态为 status: "processing"。使用与媒体相同的 2 秒 → 5 秒 → 10 秒退避策略，轮询 GET /text_detect/{uuid}，但请做好准备：冷启动时，首次轮询周期可能持续数分钟。如果十次迭代的辅助脚本结束后状态仍为 processing，不要放弃——请延长循环。

TEXT_UUID="..."
curl --request GET "${BASE_URL}/text_detect/${TEXT_UUID}" -H "$AUTH_HEADER"

响应

{
  "success": true,
  "item": {
    "uuid": "8452e246-…",
    "status": "completed",
    "prediction": "ai",
    "confidence": 0.9973,
    "text_content": "…",
    "privacy_mode": false,
    "created_at": "…",
    "updated_at": "…"
  }
}

字段	含义
status	"processing"、"completed" 或 "failed"。只有 completed 会提供判定结果。
prediction	"ai" 或 "human"。少数情况下会是 "uncertain"，表示模型拒绝为文本评分——应报告为“文本太少，无法判断”，绝不能报告为人类或 AI。
confidence	0.0–1.0。表示模型对 prediction 的确信程度，而非文本由 AI 生成的概率。 prediction: "human" 且 confidence: 0.97 表示模型有 97% 的把握认为文本由人类撰写。
text_content	提交的文本，会原样返回。设置了 zero_retention_mode 时不会返回。

不要将媒体评分表用于 confidence。 对于文本，应结合这两个字段来解读：

prediction	confidence	呈现方式
ai	≥ 0.90	“Resemble Detect 以高置信度（0.97）将此文本判定为 AI 生成。”
ai	0.50 – 0.90	“Resemble Detect 倾向于认为此文本由 AI 生成，但置信度中等（0.68）；应将其视为提示，而非证据。”
human	≥ 0.90	“Resemble Detect 以高置信度（0.95）将此文本判定为人类撰写。”
human	0.50 – 0.90	“Resemble Detect 倾向于认为此文本由人类撰写，置信度中等（0.61）。”
uncertain	—	“检测器无法为此文本评分——文本太少，无法判断。”

列出文本检测结果

curl --request GET "${BASE_URL}/text_detect" -H "$AUTH_HEADER"

返回团队的文本检测结果，按时间从新到旧排列，分页方式与 GET /detect 相同。

设定预期

适用时请说明以下注意事项——这些是当前模型经过测量的表现，并非谨慎措辞：

• 长篇文本（文章、论文、博客文章、商务写作、学术文本）：非常可靠——被误判的人类文本低于 0.2%，检测到的 AI 文本超过 99%。
• 论坛和社交媒体帖子：约有 2–3% 的人类帖子会被标记为 AI。输入内容类似 Reddit 帖子时请说明这一点。
• 刚超过 25 个词的日常聊天内容：人类文本的误报率约为 4%。对于长度处于临界值的日常消息，应给出更温和的判定。
• 代码审查评论和 PR 描述：约有 5% 的人类撰写内容会被标记。正式的技术性文字是模型在人类文本检测中最不擅长的文体。
• 少于 150 个词的简短 AI 摘要：有些内容可能漏检（检测率约为 85%）。
• 经人工润色或“打磨”的 AI 文本：模型经过这类文本的训练，但经过大量人工编辑的 AI 输出属于混合创作情形——应说明判定针对的是提交的文本。

检测结果具有概率性。判定结果是证据，而非创作来源的证明，不得单独作为指控或纪律处分的依据。

---

第 6 阶段：Agent 检测——网站上的真人与 AI Agent

Agent 检测会告诉网站每位访客是真人，还是代表真人行事的 AI Agent，例如代表他人浏览、比较和购买商品的个人助手。它根据访客的行为（指针移动、点击、输入、滚动）来判断，而不是根据访客自称的身份来判断。

这不是为了屏蔽 Agent。大多数 Agent 流量都来自真实客户。关键是了解谁在访问，这样网站就能：

• 查看真实流量：为每次访问添加标签，让漏斗和仪表板重新统计真人。
• 为有帮助的 Agent 提供便利：了解 Agent 使用哪些页面、在哪些地方放弃，然后让这些路径更便捷（例如提供 API、结构化数据或更简单的表单）。
• 阻止不该继续的 Agent：在只有真人才能操作的流程中对 Agent 进行验证，例如注册、结账和限每人一次的优惠。

Agent 检测只会报告结果。它本身绝不会屏蔽任何人；网站自行决定如何处理每个判定结果。

两种密钥——绝不可混用

密钥	存放位置	功能
Resemble API 密钥（RESEMBLE_API_KEY）	你的服务端、环境变量	创建和管理集成、读取分析数据
可发布密钥（pk_live_...）	网站的 HTML	仅从列出的域名为单个网站发送遥测数据

**绝不要将 Resemble API 密钥放在网页、客户端包或 NEXT_PUBLIC_* / VITE_* 变量中。**遥测端点无论如何都会拒绝 API 密钥，但泄露 API 密钥会让他人获得该账户的全部权限。

设置网站

1. 为域名创建集成。如果团队已为该域名创建集成，则会返回现有集成，而不会创建重复项：

   curl --request POST "${BASE_URL}/agent_detection/sites" \
     -H "$AUTH_HEADER" \
     -H "Content-Type: application/json" \
     --data '{"domain": "example.com", "name": "Example"}'
   

2. 从响应中获取 item.snippet。它是一个带有网站可发布密钥的脚本标签：

   <script async src="..." data-resemble-key="pk_live_..." data-resemble-endpoint="https://app.resemble.ai/api/v2/agent_detection/telemetry"></script>
   

3. 将代码片段放入每个需要覆盖的页面的 <head> 中。请原样使用返回的代码片段，不要手动重新编写。具体位置取决于所用技术栈：
   • Next.js App Router：放入 app/layout.tsx，使用 next/script，并设置 strategy="afterInteractive" 和相同的 data-* 属性。
   • Next.js Pages Router：放入 pages/_document.tsx。
   • 纯 HTML / 静态网站：放入共享的 <head> 片段或每个 HTML 文件中。
   • WordPress：放入主题的 header.php，或使用页眉脚本插件。
4. 如果网站也运行在 www.、暂存主机或预览域名上，请添加这些主机。domains 会替换整个列表，因此请包含所有需要保留的主机：

   curl --request PATCH "${BASE_URL}/agent_detection/sites/${SITE_ID}" \
     -H "$AUTH_HEADER" \
     -H "Content-Type: application/json" \
     --data '{"domains": ["example.com", "www.example.com", "staging.example.com"]}'
   

在页面中根据判定结果采取行动

仅当用户要求页面根据判定结果执行某项操作时才这样做。SDK 会为每次访问的最终判定结果发送一次通知：

window.addEventListener('resemble:verdict', (e) => {
  const { verdict, kind, sessionId } = e.detail  // verdict: "human" | "agent" | "review"
})

// Or a callback, which still fires if the verdict came before it was registered.
ResembleAgentDetection.onVerdict(({ verdict, kind }) => { /* ... */ })

默认采用标记方式（将判定结果发送到网站的分析系统）。仅在用户指定的流程中添加验证或屏蔽，绝不要应用到整个网站。

查看流量

# Totals: visits, settled, agents, people, agent_share, gated; plus by_class, by_page, by_day
curl --request GET "${BASE_URL}/agent_detection/analytics?site_id=${SITE_ID}&from=2026-09-01T00:00:00Z" -H "$AUTH_HEADER"

# Individual visits, newest first (per_page max 100)
curl --request GET "${BASE_URL}/agent_detection/sessions?site_id=${SITE_ID}&settled=agent&per_page=25" -H "$AUTH_HEADER"

# One visit with its evidence: features, observations, reads, recording
curl --request GET "${BASE_URL}/agent_detection/sessions/${SESSION_ID}" -H "$AUTH_HEADER"

列表和分析数据都支持以下筛选条件：site_id、settled（human 或 agent）、page_path、from、to、q。

字段	含义
settled	最终判定结果：human 或 agent。null 表示访问仍在进行，或已结束但互动不足以作出判断——这不是判定结果。
visitor_class	human、computer_use_agent（通过屏幕操作浏览器的 AI）、browser_automation（Playwright、Puppeteer、Selenium）或 scripted_client（不使用真实浏览器的请求）。
p_person	模型判断现场有真人的概率，范围为 0.0–1.0。
action	页面收到的操作指令：observing、hint、gate 或 none。
totals.agent_share	Agent 数量占已作出判定的访问次数的比例。如果尚无判定结果，则为 null。

呈现流量结果

• 先说明已判定访问中 Agent 所占的比例，并注明依据的访问次数。未判定的访问不代表用户。
• 按 visitor_class 和页面细分 Agent。Agent 较多而转化较少的页面，是最难让 Agent 使用的网站页面。
• 将 Agent 描述为访客，而非攻击者，除非证据另有表明（例如，/signup 上同时出现大量 Agent）。
• 说明判定仅供参考：结论来自浏览器信号，决心坚定的攻击者可以伪造这些信号。

计费

每个团队每天（UTC）可免费获得 10,000 次已判定访问。超过此数量后，每次已判定访问只计费一次。未得出判定结果的访问永不计费。创建集成和查看分析数据均免费。

---

推荐工作流

完整媒体取证（最全面）

1. 提交一个启用所有有用标志的 POST /detect 任务：

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

2. 轮询 GET /detect/{uuid}，直到 status: "completed"。
3. 查看 metrics、image_metrics 或 video_metrics，获取判定结果。
4. 如果请求了情报分析，请查看 intelligence.description。
5. 如果音频是合成的，请查看 audio_source_tracing.label，了解可能的来源平台。
6. 仅在检测完成后，才通过 POST /detects/{uuid}/intelligence 提出后续请求。

快速真实性检查（最快）

1. 使用 Prefer: wait 提交最简检测：

   curl --request POST "${BASE_URL}/detect" \
     -H "$AUTH_HEADER" \
     -H "Prefer: wait" \
     -H "Content-Type: application/json" \
     --data '{"url": "https://example.com/media.wav"}'
   

2. 确认 item.status 为 completed。
3. 对于音频，检查 item.metrics.label 和 item.metrics.aggregated_score；对于图像/视频，检查 item.image_metrics.label / item.video_metrics.label 和 score。
4. 结合分数背景和检测器注意事项，报告结果。

快速 AI 文本检查

1. 统计字数。少于 25 个词 → 停止，并告知用户文本不足以作出判断（或合并同一作者的多条消息）。
2. 使用 Prefer: wait 和 --max-time 320 提交：

   curl --request POST "${BASE_URL}/text_detect" \
     -H "$AUTH_HEADER" \
     -H "Prefer: wait" \
     -H "Content-Type: application/json" \
     --max-time 320 \
     --data "$(jq -n --arg text "$TEXT" '{text: $text}')"
   

3. 确认 item.status 为 completed。
4. 将 item.prediction 与 item.confidence 一并查看。成对呈现（“AI 生成，置信度 0.97”）；如果文本是论坛帖子、随意聊天或代码审查内容，请指出相应语体的注意事项，并提醒用户结果是概率性的。

为用户的网站添加 Agent 检测

1. 从代码库中查找网站域名，或询问用户。
2. 使用 POST /agent_detection/sites 添加主域名；使用 PATCH 添加其他主机。
3. 将 item.snippet 放入适用于该技术栈的共享 <head> 中（参见阶段 6）。
4. 如果用户希望使用判定结果，请先将 resemble:verdict 接入其分析系统；只有在用户提出要求时才添加拦截规则。
5. 告知用户：真实访客到来后，结果会显示在应用的 Agent 检测下。

---

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

• 尚未完成检测就宣称内容真实与否 — 切勿仅凭视觉或听觉检查就认定媒体内容是真的或伪造的。
• 忽略状态 — processing 不是判定结果；failed 表示必须报告失败。
• 忽略分数，只报告标签 — fake 标签对应 0.51 的分数，与 0.95 的分数有很大区别。
• 提交多个媒体来源 — 检测时，file、url 和 media_token 互斥。
• 直接上传超过 150 MB 的文件 — 请使用安全上传或公开 URL。
• 轮询过于频繁 — 从 2 秒开始并逐步延长间隔；不要以低于 1 秒的间隔循环轮询。
• 检测完成前就向 Detect Intelligence 提问 — 这可能会返回 422。
• 期待对真实音频进行来源追踪 — 来源追踪对合成音频最有用。
• 泄露凭据 — 切勿打印 bearer 令牌、.env 文件，或包含真实机密的授权标头。
• 凭文风判断文本 — “这听起来像 ChatGPT 写的”不构成判定结果。只有已完成的 POST /text_detect 结果才是。
• 提交少于 25 个词的文本 — API 会以 400 拒绝。请先计数；必要时汇总同一作者的短消息。
• 将文本 confidence 当作 AI 概率 — 它表示对 prediction 的置信度。human 结果为 0.95，表示高度确信是人类撰写，而不是 95% 的 AI 概率。
• 把 uncertain 当作判定结果 — 这表示检测器放弃判定。请报告“文本不足以作出判断”。
• 过早让文本请求超时 — 空闲后发起的第一个请求可能需要 3–4 分钟。请使用 --max-time 320 并耐心等待。
• 将一份 2,000 词的文档作为单个数字评分 — 系统只读取前约 350–400 个词。请将其分块。
• 将 Resemble API 密钥放入网页 — HTML 或客户端包中只能放置可公开的密钥（pk_live_...）。
• 混淆 Agent Detection 和 Detect Agents — 前者用于标记网站访客，后者用于调查媒体。
• 默认屏蔽所有 Agent — Agent Detection 用于了解访客身份。仅对用户指定的流程设置门控。
• 将尚未确定的访问计为人员 — settled: null 不是判定结果。

结果呈现指南

向用户呈现结果时：

1. 先说明检测器的判定结果 — “Resemble Detect 将这段音频判定为可能由 AI 生成。”
2. 包含状态和分数 — 仅当状态为 completed 时才报告内容是否真实。
3. 说明所用字段 — 例如 item.metrics.aggregated_score、item.image_metrics.score、item.video_metrics.score，或者文本检测中的 item.prediction 和 item.confidence。
4. 说明局限性 — 检测结果具有概率性，不能作为绝对证明或法律证据。
5. 包含操作详情 — 说明是否使用了 intelligence、反向搜索、OOD、来源追踪或零留存。
6. 对于无法定论的分数（0.3–0.5） — 明确指出结果无法定论，并建议进一步分析或人工复核。
7. 对于网站流量 — 报告 Agent 占已判定访问的比例及对应数量；除非证据表明存在滥用，否则应将 Agent 描述为访客。
8. 对于文本 — 始终同时呈现 prediction 和 confidence；适用时说明语域方面的注意事项（论坛、随意聊天、代码审查），绝不可将判定结果说成是谁撰写文本的证明。

错误处理

错误	原因	解决方法
400	请求正文无效、缺少媒体来源、文件不受支持，或媒体来源不止一个	检查请求负载，并且只提供一个 file、url 或 media_token
400	文本检测：少于 25 个单词、超过 100,000 个字符，或出现 "This feature is not available for your account"	添加文本（或汇总消息）、将长文本分块，或联系 Resemble 启用文本检测
401	API 密钥无效或缺失	验证 RESEMBLE_API_KEY 和身份验证标头
401	Agent Detection 遥测：缺少、未知或未激活的可发布密钥，或发送了 API 密钥	使用 snippet 中该集成的 pk_live_... 密钥
403	Agent Detection 遥测：此密钥在该来源上无效	使用 PATCH /agent_detection/sites/{id} 将主机添加到 domains
402	文本检测或 Detect Agents 的使用额度不足	将付费墙提示告知用户；不要重试
404	未找到检测、问题或智能分析 UUID	验证 UUID 和端点路径
422	Detect Intelligence 的检测尚未完成，或请求验证失败	等待完成或修正请求
429	请求受到速率限制	延迟后重试，并逐步延长等待时间
500	服务器错误	重试一次，然后报告失败

隐私与合规说明

• 零保留模式： 在媒体检测中设置 zero_retention_mode: true，以便在分析后自动删除提交的媒体。启用后，响应会隐去媒体 URL。在文本检测中，同一标志会阻止存储提交的文本，并从响应中省略 text_content。
• Agent Detection： 击键仅记录为类别（字母、数字、退格键），不会记录具体按键或输入的文本，也不会采集页面内容。访客 IP 在存储前会进行哈希处理。原始事件流仅为 Agent 访问和其余访问中的抽样数据保留，并会过期。
• 回调： 如果使用 callback_url，请确保其使用 HTTPS，且已在你的一侧进行身份验证。
• 密钥： 将 API 密钥保存在环境变量或密钥管理器中，切勿放入技能文件或提示词中。