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).
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_reverse_searchImageBoolean. Enable reverse image search to improve detection accuracy. Searches the web for matching images and uses AI to classify whether the match indicates a known fake. Default: false.
use_ood_detectorAudioBoolean. Enable out-of-distribution detection. Default: false.
zero_retention_modeAllBoolean. Enable zero retention 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": "5.0",
10    "media_type": "image",
11    "image_metrics": {
12      "ifl": {
13        "score": 1,
14        "heatmap": "https://..."
15      },
16      "type": "FinalResult",
17      "image": "https://...",
18      "label": "Fake",
19      "score": 1,
20      "children": []
21    },
22    "intelligence": {
23      "uuid": "INTELLIGENCE_UUID",
24      "description": "...",
25      "created_at": "2024-01-15T10:30:02Z",
26      "detect_uuid": "DETECTION_UUID"
27    },
28    "visualize": false,
29    "audio_source_tracing_enabled": false,
30    "use_ood_detector": false,
31    "filename": "image.jpg",
32    "extra_params": {
33      "search_identity_requested": false
34    },
35    "status": "completed",
36    "audio_url": "https://example.com/image.jpg",
37    "zero_retention_mode": false,
38    "media_redacted": false,
39    "media_deleted": false
40  }
41}

When use_reverse_search is enabled, the image_metrics object includes a reverse_image_search_sources array containing web sources that matched the submitted image, along with a verdict and similarity score for each:

$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/image.jpg",
>    "intelligence": true,
>    "use_reverse_search": true
>  }'
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:12Z",
8    "url": "https://example.com/image.jpg",
9    "duration": "5.0",
10    "media_type": "image",
11    "image_metrics": {
12      "ifl": {
13        "score": 1,
14        "heatmap": "https://..."
15      },
16      "type": "FinalResult",
17      "image": "https://...",
18      "label": "Fake",
19      "score": 1,
20      "children": [],
21      "reverse_image_search_sources": [
22        {
23          "url": "https://example-stock-site.com/ai-generated-images/",
24          "title": "example-stock-site.com",
25          "reason": "This exact image is hosted on a stock photography site and labeled as a 'Premium AI-generated image'.",
26          "verdict": "known_fake",
27          "similarity": 1
28        },
29        {
30          "url": "https://another-stock-site.com/search/ai-art",
31          "title": "another-stock-site.com",
32          "reason": "The site lists near-identical variations of this image, explicitly labeling them as AI generated.",
33          "verdict": "known_fake",
34          "similarity": 0.9
35        }
36      ]
37    },
38    "intelligence": {
39      "uuid": "INTELLIGENCE_UUID",
40      "description": "...",
41      "created_at": "2024-01-15T10:30:12Z",
42      "detect_uuid": "DETECTION_UUID"
43    },
44    "visualize": false,
45    "audio_source_tracing_enabled": false,
46    "use_ood_detector": false,
47    "filename": "image.jpg",
48    "extra_params": {
49      "use_reverse_search": true,
50      "search_identity_requested": false
51    },
52    "status": "completed",
53    "audio_url": "https://example.com/image.jpg",
54    "zero_retention_mode": false,
55    "media_redacted": false,
56    "media_deleted": false
57  }
58}

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}

Zero Retention Mode

When zero_retention_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.

Zero Retention Mode is request-driven only — team-level or UI defaults are not applied to API requests. You must explicitly pass zero_retention_mode: true on each request.

Zero Retention 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",
>    "zero_retention_mode": true,
>    "intelligence": true
>  }'

Zero Retention Mode Response Example

1{
2  "success": true,
3  "item": {
4    "uuid": "DETECTION_UUID",
5    "zero_retention_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  "zero_retention_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.