> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.resemble.ai/llms.txt. > For full documentation content, see https://docs.resemble.ai/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server. # 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. You can supply media in one of three ways: * **Direct file upload** — POST a `multipart/form-data` request with the file attached as `file`. Best for one-off requests against files up to 150 MB. * **Public URL** — pass `url` when the media is already hosted at a publicly reachable HTTPS address. No upload size limit on this path because the API fetches the URL itself. * **Secure upload token** — upload the file first via [`POST /secure_uploads`](/detect/secure-uploads) and pass the returned token as `media_token`. Use this when you do not want to host the source file publicly, or when the file is larger than the 150 MB direct-upload cap. The token is a short-lived JWT that expires 1 hour after issuance. Exactly one of `file`, `url`, or `media_token` must be provided per request. ### Using a direct file upload ```bash curl --request POST 'https://app.resemble.ai/api/v2/detect' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Prefer: wait' \ -F 'file=@/path/to/media.mp4' \ -F 'callback_url=https://example.com/webhooks/detect' \ -F 'intelligence=true' \ -F 'visualize=true' \ -F 'frame_length=2' ``` Optional parameters (`callback_url`, `intelligence`, `visualize`, etc.) are sent as additional form fields when uploading directly. #### File constraints | Constraint | Value | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum size | **150 MB**. Larger files must use the [Secure Uploads API](/detect/secure-uploads) instead. | | Allowed extensions | `.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`, `.amr`, `.3gp`, `.3gpp`, `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp` | | Allowed content types | `audio/*`, `video/*`, `image/*` matching the extensions above. `application/octet-stream` is accepted when paired with a recognized extension. | | Empty files | Rejected with HTTP 400. | Requests outside these constraints are rejected with HTTP 400 before any analysis or billing runs. The size-limit error response includes a pointer to the Secure Uploads API as the recommended path for larger uploads. ### Using a public URL ```bash 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 }' ``` ### Using a secure upload token First, upload the file to obtain a token (see [Secure Upload](/detect/secure-uploads)): ```bash curl --request POST 'https://app.resemble.ai/api/v2/secure_uploads' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -F 'file=@/path/to/media.mp4' ``` Then submit the detect job using the returned `token` as `media_token`: ```bash curl --request POST 'https://app.resemble.ai/api/v2/detect' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ --data '{ "media_token": "eyJhbGciOiJIUzI1NiJ9...", "callback_url": "https://example.com/webhooks/detect" }' ``` ## Media Source Provide exactly one of the following. | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `file` | A media file uploaded as `multipart/form-data`. Maximum 150 MB; allowed extensions are `.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`, `.amr`, `.3gp`, `.3gpp`, `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`. For files over 150 MB, use `media_token`. | | `url` | Public HTTPS URL to the media to analyze (wav, mp3, ogg, m4a, aac, flac, amr, 3gp, 3gpp, mp4, mov, avi, mkv, webm, jpg, jpeg, png, gif, webp). | | `media_token` | Token returned by [`POST /secure_uploads`](/detect/secure-uploads). Valid for 1 hour after upload. | ## Optional Parameters | Field | Applies To | Description | | ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callback_url` | All | POST destination when analysis completes. Payload matches the standard response. | | `visualize` | All | Generate visualization artifacts (images/treeview). | | `frame_length` | Audio & Video | Window size in seconds (`1`–`4`, default `2`). | | `start_region` / `end_region` | Audio & Video | Analyze a segment (seconds). | | `max_video_secs` | Video | Cap processed duration. | | `model_types` | Video | `image` or `talking_head`. Use `talking_head` for face-swaps. | | `intelligence` | All | Boolean. Run multimodal intelligence analysis on the media. Returns speaker info, transcription, emotion, abnormalities, misinformation, and anti-cheating indicators. Default: `false`. | | `audio_source_tracing` | Audio | Boolean. Enable audio source tracing to identify the origin of synthetic audio (e.g., Resemble AI, ElevenLabs). Default: `false`. | | `use_reverse_search` | Image | Boolean. 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_detector` | Audio | Boolean. Enable out-of-distribution detection. Default: `false`. | | `zero_retention_mode` | All | Boolean. 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: ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "metrics": {}, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "media_type": "audio", "intelligence": null } } ``` 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 ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "metrics": { "image": "", "label": "fake", "score": ["0.9", "0.8", "0.7"], "consistency": "0.85", "aggregated_score": "0.80" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:05Z", "duration": "5.2", "media_type": "audio", "intelligence": { "description": "Adult male speaker with confident tone...", "created_at": "2024-01-15T10:30:05Z" } } } ``` #### Image File Response ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "metrics": {}, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:02Z", "url": "https://example.com/image.jpg", "duration": "5.0", "media_type": "image", "image_metrics": { "ifl": { "score": 1, "heatmap": "https://..." }, "type": "FinalResult", "image": "https://...", "label": "Fake", "score": 1, "children": [] }, "intelligence": { "uuid": "INTELLIGENCE_UUID", "description": "...", "created_at": "2024-01-15T10:30:02Z", "detect_uuid": "DETECTION_UUID" }, "visualize": false, "audio_source_tracing_enabled": false, "use_ood_detector": false, "filename": "image.jpg", "extra_params": { "search_identity_requested": false }, "status": "completed", "audio_url": "https://example.com/image.jpg", "zero_retention_mode": false, "file_deleted_at": null } } ``` #### Image File Response (with Reverse Image Search) 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: ```bash 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 }' ``` ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "metrics": {}, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:12Z", "url": "https://example.com/image.jpg", "duration": "5.0", "media_type": "image", "image_metrics": { "ifl": { "score": 1, "heatmap": "https://..." }, "type": "FinalResult", "image": "https://...", "label": "Fake", "score": 1, "children": [], "reverse_image_search_sources": [ { "url": "https://example-stock-site.com/ai-generated-images/", "title": "example-stock-site.com", "reason": "This exact image is hosted on a stock photography site and labeled as a 'Premium AI-generated image'.", "verdict": "known_fake", "similarity": 1 }, { "url": "https://another-stock-site.com/search/ai-art", "title": "another-stock-site.com", "reason": "The site lists near-identical variations of this image, explicitly labeling them as AI generated.", "verdict": "known_fake", "similarity": 0.9 } ] }, "intelligence": { "uuid": "INTELLIGENCE_UUID", "description": "...", "created_at": "2024-01-15T10:30:12Z", "detect_uuid": "DETECTION_UUID" }, "visualize": false, "audio_source_tracing_enabled": false, "use_ood_detector": false, "filename": "image.jpg", "extra_params": { "use_reverse_search": true, "search_identity_requested": false }, "status": "completed", "audio_url": "https://example.com/image.jpg", "zero_retention_mode": false, "file_deleted_at": null } } ``` #### Video File Response ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "metrics": { "image": "https://...", "label": "fake", "score": ["0.9", "0.8", "0.7"], "consistency": "0.85", "aggregated_score": "0.80" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:10Z", "duration": "10.5", "media_type": "video", "video_metrics": { "label": "Fake", "score": 0.95, "certainty": 0.93, "treeview": "...", "children": [ { "type": "VideoResult", "conclusion": "Fake", "score": 0.99, "certainty": 0.9, "certainty (%)": "90.0", "children": [ { "type": "ImageResult", "conclusion": "Fake", "score": 0.9, "certainty": 0.95, "certainty (%)": "95.0", "timestamp": 0.23, "children": [ { "type": "Segment", "conclusion": "Fake", "score": 0.9, "certainty": 0.995, "certainty (%)": "99.5" } ] } ] } ] }, "intelligence": { "description": "Video contains an adult male speaker with confident tone...", "created_at": "2024-01-15T10:30:10Z" } } } ``` ### 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 ```bash 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 ```json { "success": true, "item": { "uuid": "DETECTION_UUID", "zero_retention_mode": true, "file_deleted_at": null, "url": null, "audio_url": null, "filename": "redacted_abc123def4567890abcd1234.mp3", "metrics": { "label": "fake", "score": ["0.9", "0.8", "0.7"], "consistency": "0.85", "aggregated_score": "0.80" }, "media_type": "audio", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:05Z" } } ``` Once the media file has been purged, `file_deleted_at` is populated with the purge timestamp: ```json { "zero_retention_mode": true, "file_deleted_at": "2024-01-15T10:31:00Z", "url": null, "audio_url": null, "filename": "redacted_abc123def4567890abcd1234.mp3" } ``` ### 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.