Safety & DetectionDeepfake Detection

Submit Detection Job

POST https://app.resemble.ai/api/v2/detect

By default the request is asynchronous. The API responds immediately with a job UUID while analysis continues in the background. Include Prefer: wait to block until completion.

$curl --request POST 'https://app.resemble.ai/api/v2/detect' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Prefer: wait' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/media.mp4",
>    "callback_url": "https://example.com/webhooks/detect",
>    "intelligence": true,
>    "visualize": true,
>    "frame_length": 2
>  }'

Required Field

FieldDescription
urlPublic HTTPS URL to the media to analyze (wav, mp3, ogg, m4a, flac, mp4, mov, avi, wmv, jpg, jpeg, png, gif, webp).

Optional Parameters

FieldApplies ToDescription
callback_urlAllPOST destination when analysis completes. Payload matches the standard response.
visualizeAllGenerate visualization artifacts (images/treeview).
frame_lengthAudio & VideoWindow size in seconds (1–4, default 2).
start_region / end_regionAudio & VideoAnalyze a segment (seconds).
pipelineImage & VideoSequence of detectors (general, facial, object) separated by ->. Default general->facial->object.
max_video_fpsVideoDownsample high-frame-rate media.
max_video_secsVideoCap processed duration.
model_typesVideoimage or talking_head. Use talking_head for face-swaps.
intelligenceAllBoolean. Run multimodal intelligence analysis on the media. Returns speaker info, transcription, emotion, abnormalities, misinformation, and anti-cheating indicators. Default: false.
audio_source_tracingAudioBoolean. Enable audio source tracing to identify the origin of synthetic audio (e.g., Resemble AI, ElevenLabs). Default: false.
use_ood_detectorAudioBoolean. Enable out-of-distribution detection. Default: false.
privacy_modeAllBoolean. Enable privacy mode to automatically delete the submitted media file after detection completes. When enabled, media URLs are redacted from all responses and the filename is tokenized. Default: false.

Response

Asynchronous Response

By default, the API responds immediately while processing continues in the background:

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "metrics": {},
6    "created_at": "2024-01-15T10:30:00Z",
7    "updated_at": "2024-01-15T10:30:00Z",
8    "media_type": "audio",
9    "intelligence": null
10  }
11}

Use the UUID to check status via the Get Detection Result endpoint, or provide a callback_url to receive results automatically.

Synchronous Response (with Prefer: wait header)

When using the Prefer: wait header, the API returns complete results immediately:

Audio File Response

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "metrics": {
6      "image": "",
7      "label": "fake",
8      "score": ["0.9", "0.8", "0.7"],
9      "consistency": "0.85",
10      "aggregated_score": "0.80"
11    },
12    "created_at": "2024-01-15T10:30:00Z",
13    "updated_at": "2024-01-15T10:30:05Z",
14    "duration": "5.2",
15    "media_type": "audio",
16    "intelligence": {
17      "description": "Adult male speaker with confident tone...",
18      "created_at": "2024-01-15T10:30:05Z"
19    }
20  }
21}

Image File Response

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "metrics": {},
6    "created_at": "2024-01-15T10:30:00Z",
7    "updated_at": "2024-01-15T10:30:02Z",
8    "url": "https://example.com/image.jpg",
9    "duration": "0",
10    "media_type": "image",
11    "image_metrics": {
12      "type": "facial",
13      "image": "https://...",
14      "label": "fake",
15      "score": 0.92,
16      "children": []
17    },
18    "intelligence": {
19      "description": "Image shows a person in professional attire...",
20      "created_at": "2024-01-15T10:30:02Z"
21    }
22  }
23}

Video File Response

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "metrics": {
6      "image": "https://...",
7      "label": "fake",
8      "score": ["0.9", "0.8", "0.7"],
9      "consistency": "0.85",
10      "aggregated_score": "0.80"
11    },
12    "created_at": "2024-01-15T10:30:00Z",
13    "updated_at": "2024-01-15T10:30:10Z",
14    "duration": "10.5",
15    "media_type": "video",
16    "video_metrics": {
17      "label": "Fake",
18      "score": 0.95,
19      "certainty": 0.93,
20      "treeview": "...",
21      "children": [
22        {
23          "type": "VideoResult",
24          "conclusion": "Fake",
25          "score": 0.99,
26          "certainty": 0.9,
27          "certainty (%)": "90.0",
28          "children": [
29            {
30              "type": "ImageResult",
31              "conclusion": "Fake",
32              "score": 0.9,
33              "certainty": 0.95,
34              "certainty (%)": "95.0",
35              "timestamp": 0.23,
36              "children": [
37                {
38                  "type": "Segment",
39                  "conclusion": "Fake",
40                  "score": 0.9,
41                  "certainty": 0.995,
42                  "certainty (%)": "99.5"
43                }
44              ]
45            }
46          ]
47        }
48      ]
49    },
50    "intelligence": {
51      "description": "Video contains an adult male speaker with confident tone...",
52      "created_at": "2024-01-15T10:30:10Z"
53    }
54  }
55}

Privacy Mode

When privacy_mode=true, the API enables a privacy lifecycle for the submitted media:

  • URL redaction: url and audio_url are set to null in all responses, both during processing and after completion.
  • Filename tokenization: The original filename is replaced with a tokenized value (e.g., redacted_abc123def4567890abcd1234.mp3).
  • Media deletion: After detection completes (including any downstream tasks like intelligence or source tracing), the uploaded file is permanently deleted from storage. The file_deleted_at timestamp is set once the purge succeeds.
  • Downstream records: Related records (intelligence, source tracing, identity) are still created but do not store copies of the media.

Privacy mode is request-driven only — team-level or UI defaults are not applied to API requests. You must explicitly pass privacy_mode: true on each request.

Privacy Mode Request Example

$curl --request POST 'https://app.resemble.ai/api/v2/detect' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Prefer: wait' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "url": "https://example.com/media.mp4",
>    "privacy_mode": true,
>    "intelligence": true
>  }'

Privacy Mode Response Example

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "privacy_mode": true,
6    "media_redacted": true,
7    "media_deleted": false,
8    "file_deleted_at": null,
9    "url": null,
10    "audio_url": null,
11    "filename": "redacted_abc123def4567890abcd1234.mp3",
12    "metrics": {
13      "label": "fake",
14      "score": ["0.9", "0.8", "0.7"],
15      "consistency": "0.85",
16      "aggregated_score": "0.80"
17    },
18    "media_type": "audio",
19    "created_at": "2024-01-15T10:30:00Z",
20    "updated_at": "2024-01-15T10:30:05Z"
21  }
22}

Once the media file has been purged, media_deleted becomes true and file_deleted_at is populated:

1{
2  "privacy_mode": true,
3  "media_redacted": true,
4  "media_deleted": true,
5  "file_deleted_at": "2024-01-15T10:31:00Z",
6  "url": null,
7  "audio_url": null,
8  "filename": "redacted_abc123def4567890abcd1234.mp3"
9}

Callback URL

If you provide a callback_url when submitting a media file, you will receive a POST request to that URL with the same payload structure as the synchronous response shown above. When intelligence analysis was requested, the callback payload will include the intelligence field with the analysis results.