resemble-detect

Resemble Detect — ディープフェイク検出とメディアの安全性

Resemble AI API の直接呼び出しを使用して、音声、画像、動画、テキストを分析し、合成による改ざん、AI 生成コンテンツ、メディアインテリジェンスを検出します。また、ウェブサイトの訪問者が人間か AI エージェントかを確認します。

基本原則 — 絶対に守るべきルール

「検出結果が完了するまで、メディアが本物か偽物かを決して断定しないでください。」

メディアの真正性について推測、推論、憶測をしないでください。真正性に関する主張はすべて、label、score、status: "completed" が返された Resemble Detect ジョブの完了結果で裏付ける必要があります。検出がまだ processing の場合は、完了を待ってください。failed の場合は、その旨を伝えてください。独自の判断で代用してはいけません。

同じルールはテキストにも適用されます。文体、口調、または「ChatGPT が書いたように読める」という印象から、文章を AI 生成または人間が書いたと断定してはいけません。テキストの判定には、prediction、confidence、status: "completed" を含む完了済みの POST /text_detect ジョブが必要です。

同じルールはウェブサイトの訪問者にも適用されます。ユーザーエージェント、リクエスト数、直感をもとに、サイトのトラフィックがエージェントか人間かを断定してはいけません。訪問者の判定は、Agent Detection（訪問時に settled と判定された結果、または GET /agent_detection/analytics の合計値）に基づきます。

使用する場面

ユーザーのリクエストに次のいずれかが含まれる場合は、このスキルを使用します。

• 音声、動画、画像が AI 生成または改ざんされたものかを確認する
• エッセイ、メール、投稿、レビュー、記事、カバーレター、コメントなどのテキストが AI モデルによって書かれたかを確認する（「スロップ検出」）
• あらゆるメディア形式のディープフェイクを検出する
• メディアの真正性または出所を検証する
• 音声を合成した AI プラットフォームを特定する（ソーストレーシング）
• 話者情報、感情、文字起こし、誤情報についてメディアを分析する
• 検出結果について自然言語で質問する
• 保険請求、速報ニュース、ID 確認、提出された証拠など、検出を複数の入力の一つとして扱う一連の調査ワークフローを実行する
• ウェブサイトの訪問者が人間か AI エージェントかを確認する、サイトに Agent Detection を追加する、またはサイトのトラフィックのうちエージェントが占める割合を調べる
• 次のいずれかに言及している場合：「ディープフェイク」「偽造検出」「合成メディア」「メディアフォレンジック」「真正性チェック」「ソーストレーシング」「これは本物か」「AI が書いた」「ChatGPT が書いた」「AI テキスト」「スロップ」「人間が書いたのか」「エージェント検出」「ボットトラフィック」「AI エージェントがサイトを訪問」「Porter」「この訪問者はボットか」

使用しないでください：テキスト読み上げの生成、音声クローン、音声の文字起こしには使用しないでください。これらは Resemble の別の機能です。（テキストが AI によって書かれたかの検出は対象です。Phase 5 を参照してください。ウェブサイトの訪問者が人間か AI エージェントかの判定も対象です。Phase 6 を参照してください。）

Agent Detection は Detect Agents ではありません。 Detect Agents（Phase 4）は、メディアを分析する Resemble の調査エージェントです。Agent Detection（Phase 6）は、ウェブサイトの各訪問者が人間か AI エージェントかを判定します。

必要なセットアップ

• API キー： Resemble ダッシュボードから取得するベアラートークン：https://app.resemble.ai/account/api
• 環境変数： RESEMBLE_API_KEY を推奨します
• ベース URL： https://app.resemble.ai/api/v2
• 認証ヘッダー： Authorization: Bearer $RESEMBLE_API_KEY
• メディア入力： POST /detect では、次のいずれか一つだけを指定できます。
  • file として直接アップロードする multipart/form-data ファイル（最大 150 MB）
  • 公開 HTTPS url
  • POST /secure_uploads から取得した media_token
• テキスト入力： POST /text_detect は、text 文字列を含む JSON ボディを受け取ります。25 語以上、最大 100,000 文字です。ファイルまたは URL は指定できません。

API キーを表示したり、ベアラートークンをチャットに貼り付けたりしないでください。例やコマンドでは環境変数を使用してください。

機能の選択フローチャート

ユーザーの目的	使用する機能	API エンドポイント
メディアが AI 生成／ディープフェイクかどうかを確認する	ディープフェイク検出	POST /detect の後、GET /detect/{uuid}
公開ホスティングせずにプライベート／ローカルファイルをアップロードする	直接アップロード	POST /detect multipart file=@...
公開 URL のない 150 MB 超のファイルを分析する	セキュアアップロード	POST /secure_uploads の後、media_token を指定して POST /detect
偽の音声を生成した AI プラットフォーム を特定する	音声ソース追跡	audio_source_tracing: true を指定して POST /detect
メディアから話者情報、感情、文字起こしを取得する	インテリジェンス	POST /intelligence
完了した検出について質問する	検出インテリジェンス	POST /detects/{uuid}/intelligence の後、回答をポーリング
判定結果を伴う複数ステップの調査をマネージド実行する	検出エージェント	GET /agents の後、POST /agents/{preset_id}/run（SSE）
テキストが AI モデルによって書かれたかどうかを確認する	テキスト検出	POST /text_detect の後、GET /text_detect/{uuid}
人物とエージェントの判定機能をウェブサイトに追加する	エージェント検出	POST /agent_detection/sites の後、返された snippet をインストール
サイトのトラフィックのうち、AI エージェントが占める割合を確認する	エージェント検出	GET /agent_detection/analytics、GET /agent_detection/sessions

複数のメディア機能を利用できる場合は、別々のジョブを実行するのではなく、intelligence: true、audio_source_tracing: true、visualize: true、use_reverse_search: true、zero_retention_mode: true などのフラグを使用して、1 回の POST /detect 呼び出しにまとめてください。テキスト検出は別のエンドポイントであり、メディア検出と組み合わせることはできません。

API の直接呼び出しに関するルール

1. まず HTTP リクエストを直接使用してください。 このスキルは MCP ツール呼び出しではなく、curl と Resemble REST API を中心に説明しています。
2. 同期結果で問題ない場合は Prefer: wait を使用してください。 指定しない場合は、ジョブを送信し、返された UUID を取得してからポーリングしてください。
3. 非同期ジョブは終端ステータスになるまでポーリングしてください。 終端ステータスは completed と failed です。
4. 機密性の高いメディアにはゼロ保持を使用してください。 プライバシーが重要な場合、メディア検出では zero_retention_mode: true を設定してください。
5. 完了した結果のみを報告してください。 保留中／処理中のジョブは判定結果ではありません。

再利用可能なシェルのセットアップ

コマンド列の開始時にこれを使用してください。

: "${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 のいずれか 1 つだけを指定する必要があります。

検出結果のポーリング

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：エージェントの検出

Detect Agents は、検出を複数ステップのワークフローで実行する、Resemble が管理する 6 つの調査エージェントです。Detect を実行し、裏付けとなる証拠やウェブ上の情報を集め、最後に書面による評価を提示します。「このファイルは合成か？」ではなく、「この主張／投稿／文書を信頼すべきか？」を判断する場合に使用してください。

エージェント	preset_id
ソーシャルメディアコンテンツを調査する	investigate_social_content
保険請求を審査する	review_insurance_claim
速報ニュースのメディアを検証する	verify_breaking_news
文書または領収書を検証する	verify_document
提出された証拠を検証する	verify_evidence
ID を検証する	verify_id

一覧を取得します（uuid は preset_id と同じ固定識別子です）。

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

調査を実行する

multipart/form-data を使用し、主なメディアソースは 1 つだけ（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	いずれか 1 つ	分析するメディア
url	いずれか 1 つ	公開 HTTPS メディア URL
query	いいえ	調査の質問または目的
evidence[]	いいえ	補足ファイル。複数の場合はフィールドを繰り返します
check_urls	いいえ	エージェントが確認する追加 URL

ストリームの読み取り

各フレームは data: {json} です。重要なフレームは次のとおりです。

• run_started — run_id が含まれます。保存しておいてください。接続を切断しても、実行はサーバー側に保存されます。
• detect — label と score を含む Resemble Detect の証拠です。Iron Law に基づく真正性の判定です。
• gate — 調査エージェントが検出後に処理を続行したかどうか（agent_ran）を示します。
• tool_call / tool_result — 調査および検出の各ステップが実行されるたびに表示されます。
• token / agent_message / message_end — エージェントのナレーションが逐次表示されます。
• final_verdict — 書面による評価です。intelligence は文字列であり、エージェントがスキーマを使用する場合はシリアライズされた JSON が含まれることがあります。
• done — 完了しました。error — ストリーム開始後に失敗しました（HTTP は 200 のままです）。

Iron Law は変更なく適用されます。 final_verdict はエージェントの推論であり、検出結果ではありません。ナレーションだけを根拠に、メディアが本物か偽物かを決して報告しないでください。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"

実行の詳細には、イベントの全記録、設定のスナップショット、実行前後のエージェントのメモリが追加されており、調査を再現するのに十分な情報が得られます。

アクセス

エージェントの一覧表示と実行履歴の読み取りには、有効な API キー以外は必要ありません。実行の開始には利用資格が必要です。チームに D-Agent ティアのバンドルがあるか、チームの生涯無料実行 5 回のいずれかが必要です。どちらにも該当しない場合、実行エンドポイントはストリーム開始前に、プレーンな JSON として 402 Payment Required を返します。ストリームが開始したと思い込む前に、この応答を確認してください。GET /agents も free_runs_remaining、free_runs_limit、entitled を返すため、402 を発生させるより、これらの値を確認することを推奨します。

エージェントの作成や編集は API からは利用できません。6 つのプリセットは Resemble が管理し、初回実行時に有効になります。

---

フェーズ 5：テキスト検出

文章が AI 言語モデルによって生成されたものか、人間が書いたものかを検出します。エンドポイントは 1 つで、1 回の呼び出しにつきテキストは 1 つです。JSON を入力し、JSON が返されます。

アクセス： 現在の請求プランを利用中のチーム（完了したジョブ 1 件につき Text Detection ユニット 1 つ分が課金されます）と、detect_beta_user アカウントで利用できます。アクセス権のないアカウントには "This feature is not available for your account" を含む 400 が返されます。利用資格を使い切ったチームには 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 語以上になるよう 1 つのリクエストにまとめます。これが短文の判定を得るためにサポートされている方法です。判定の対象がまとめたテキスト全体であることを明確に伝えてください。

モデルが読み取るのは、およそ最初の 350～400 語（512 トークン）です。それより長いテキストは、冒頭部分がスコアリングされます。文書全体を対象にするには、約 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	いいえ	完了時に { "success": true, "item": {...} }、失敗時に { "success": false, "item": {...}, "error": "..." } を送信する HTTPS Webhook です。
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 の場合、10 回の反復を行うヘルパーの後で諦めないでください。ループを延長してください。

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": "…"
  }
}

Field	Meaning
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に適用しないでください。 テキストの場合は、次の2つのフィールドを合わせて読み取ってください。

prediction	confidence	表示方法
ai	≥ 0.90	「Resemble Detectは、このテキストをAI生成と高い確信度で判定しました（0.97）。」
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：エージェント検出 — ウェブサイト上の人と AI エージェント

エージェント検出は、各訪問者が人なのか、本人に代わって行動する AI エージェントなのかをウェブサイトに知らせます。たとえば、本人に代わって閲覧、比較、購入を行うパーソナルアシスタントなどです。訪問者が自分を何者だと名乗るかではなく、どのように行動するか（ポインター、クリック、入力、スクロール）を基に判定します。

これはエージェントをブロックするための機能ではありません。エージェントのトラフィックの多くは、実際の顧客によるものです。目的は訪問者が誰なのかを把握し、サイトが次のことをできるようにすることです。

• 実際のトラフィックを把握する：すべての訪問にラベルを付け、ファネルやダッシュボードで再び人の数を集計できるようにします。
• 役立つエージェント向けに改善する：エージェントが利用するページや離脱する場所を特定し、API、構造化データ、より簡単なフォームなどを用意して、そうした経路を利用しやすくします。
• 望ましくないエージェントを阻止する：登録、チェックアウト、1 人 1 回限りのオファーなど、人だけが利用できるようにすべきフローでエージェントにチャレンジを行います。

エージェント検出は判定結果を報告するだけです。単独で誰かをブロックすることはありません。それぞれの判定結果に対して何をするかは、サイトが決定します。

2 つのキー — 決して混同しないでください

キー	保存場所	できること
Resemble API キー（RESEMBLE_API_KEY）	自分のサーバー、環境変数	インテグレーションの作成と管理、分析データの読み取り
パブリッシャブルキー（pk_live_...）	ウェブサイトの HTML	1 つのサイトのテレメトリーを送信。登録済みドメインからのみ利用可能

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	判定済みの訪問数に占めるエージェントの割合。まだ判定済みの訪問がない場合は null。

トラフィック結果の提示

• 判定済みの訪問のうちエージェントが占める割合を最初に示し、対象となった訪問数も伝えます。未判定の訪問は人ではありません。
• エージェントを visitor_class 別、ページ別に分類します。エージェントが多くコンバージョンが少ないページは、エージェントにとってサイトの利用が最も難しいページです。
• 証拠がそう示していない限り、エージェントは攻撃者ではなく訪問者として扱います（たとえば、短時間に /signup へ多数のエージェントが訪れる場合など）。
• 判定は参考情報であることを伝えます。ブラウザーのシグナルに基づいており、強い意志を持つ攻撃者は偽装できます。

請求

各チームには、1日あたり10,000件の判定済み訪問が無料で提供されます（UTC）。それを超えると、判定済み訪問ごとに1回請求されます。判定に至らなかった訪問には請求されません。インテグレーションの作成と分析の閲覧は無料です。

---

推奨ワークフロー

メディアの完全なフォレンジック分析（最も詳細）

1. 便利なフラグをすべて有効にして、POST /detect ジョブを1つ送信します。

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

2. status: "completed" になるまで GET /detect/{uuid} をポーリングします。
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」）。テキストがフォーラムへの投稿、カジュアルなチャット、コードレビューの場合は、文体に応じた注意点を示し、結果は確率的なものであることを伝えます。

ユーザーのサイトにエージェント検出を追加する

1. コードベースからサイトのドメインを特定するか、ユーザーに確認します。
2. メインドメインを指定して POST /agent_detection/sites を実行し、追加のホストがあれば PATCH で登録します。
3. スタック全体で共有される <head> に item.snippet を配置します（フェーズ6を参照）。
4. ユーザーが判定を活用したい場合は、まず分析に resemble:verdict を接続します。ゲートは、ユーザーから依頼された箇所にのみ追加します。
5. 実際の訪問者がアクセスすると、アプリの エージェント検出 に結果が表示されることをユーザーに伝えます。

---

注意すべき兆候 — いったん停止して再評価

• 検出結果が確定していないのに真正性を断定する — 視覚または聴覚による確認だけを根拠に、メディアが本物または偽物だと言ってはいけません。
• ステータスを無視する — processing は判定ではありません。failed の場合は、失敗したことを報告する必要があります。
• スコアを無視してラベルだけを報告する — スコアが 0.51 の fake ラベルと、スコアが 0.95 の場合とでは大きく異なります。
• 複数のメディアソースを送信する — 検出では file、url、media_token は相互に排他的です。
• 150 MB を超えるファイルを直接アップロードする — セキュアアップロードまたは公開 URL を使用してください。
• 頻繁にポーリングしすぎる — 2 秒間隔から始めて徐々に間隔を延ばしてください。1 秒未満の間隔でループしてはいけません。
• 検出完了前に Detect Intelligence への質問を行う — 422 が返されることがあります。
• 本物の音声に対してソース追跡を期待する — ソース追跡は合成音声で最も役立ちます。
• 認証情報を漏らす — ベアラートークン、.env ファイル、実際のシークレットを含む認証ヘッダーを表示してはいけません。
• 文体でテキストを判定する — 「これは ChatGPT のような文章だ」は判定ではありません。判定となるのは、完了した POST /text_detect の結果だけです。
• 25 語未満のテキストを送信する — API は 400 を返して拒否します。まず語数を数え、必要であれば同一作者による短いメッセージをまとめてください。
• テキストの confidence を AI である確率と解釈する — これは prediction に対する確信度です。human の結果が 0.95 なら、人間が書いた可能性が高いという意味であり、AI である確率が 95% という意味ではありません。
• uncertain を判定として扱う — これは検出器が判定を保留したことを意味します。「判断するにはテキストが不十分です」と報告してください。
• テキストリクエストを早期にタイムアウトさせる — アイドル状態の後に行う最初のリクエストは 3～4 分かかることがあります。--max-time 320 を使用し、完了するまで待ってください。
• 2,000 語の文書を単一の数値でスコアリングする — 読み取られるのは最初の約 350～400 語だけです。分割してください。
• Resemble API キーをウェブページに記載する — HTML またはクライアントバンドルに含めてよいのは、公開可能なキー（pk_live_...）だけです。
• Agent Detection と Detect Agents を混同する — 一方はウェブサイトの訪問者を分類し、もう一方はメディアを調査します。
• すべてのエージェントを既定でブロックする — 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. ウェブサイトのトラフィックについて — 判定済みの訪問数に占めるエージェントの割合と、その内訳となる件数を報告します。また、不正行為を示す証拠がない限り、エージェントは訪問者として扱います。
8. テキストについて — 常に prediction と confidence を併記し、該当する場合は文体上の注意点（フォーラム、カジュアルなチャット、コードレビューなど）を示します。また、誰が書いたかの証明として判定を提示してはいけません。

エラー処理

エラー	原因	解決方法
400	リクエスト本文が無効、メディアソースがない、サポートされていないファイル、または複数のメディアソースが指定されています	ペイロードを確認し、file、url、media_token のいずれか1つだけを指定してください
400	テキスト検出：単語数が25未満、文字数が100,000を超過、または "This feature is not available for your account"	テキストを追加する（またはメッセージを集約する）、長いテキストを分割する、または Resemble に連絡して Text Detection を有効にしてください
401	API キーが無効、または指定されていません	RESEMBLE_API_KEY と認証ヘッダーを確認してください
401	Agent Detection のテレメトリ：公開可能キーがない、不明、または無効、あるいは API キーが送信されています	snippet に含まれるインテグレーションの pk_live_... キーを使用してください
403	Agent Detection のテレメトリ：キーがこのオリジンでは有効ではありません	PATCH /agent_detection/sites/{id} を実行して、ホストを domains に追加してください
402	Text Detection または Detect Agents の利用権限を超過しています	ペイウォールをユーザーに報告し、再試行しないでください
404	Detection／question／intelligence の UUID が見つかりません	UUID とエンドポイントのパスを確認してください
422	Detect Intelligence の検出が完了していない、またはリクエストの検証に失敗しました	完了を待つか、リクエストを修正してください
429	レート制限に達しました	待機時間を指数関数的に延ばしながら再試行してください
500	サーバーエラー	1回再試行してから、失敗を報告してください

プライバシーとコンプライアンスに関する注意事項

• ゼロ保持モード： メディア検出で zero_retention_mode: true を設定すると、分析後に送信されたメディアが自動的に削除されます。有効にすると、レスポンス内のメディア URL が伏せられます。テキスト検出では、同じフラグによって送信されたテキストの保存が停止され、レスポンスから text_content が省略されます。
• Agent Detection： キーストロークはカテゴリ（英字、数字、バックスペース）のみ記録され、キーや入力されたテキストは記録されません。また、ページコンテンツも取得されません。訪問者の IP アドレスは保存前にハッシュ化されます。未加工のイベントストリームは、エージェントの訪問とその他の一部のサンプルについてのみ保持され、期限が過ぎると削除されます。
• コールバック： callback_url を使用する場合は、HTTPS を使用し、受信側で認証を行ってください。
• シークレット： API キーは環境変数またはシークレットマネージャーに保存し、スキルファイルやプロンプトには決して記載しないでください。