> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server. # Batch Detection `POST https://app.resemble.ai/api/v2/detect/batch` Submit up to 50 files in a single request and process them as a single logical group. The API returns a batch UUID immediately; each file is analyzed in the background, and you can poll the batch endpoint or supply a `callback_url` to receive results. Batch is asynchronous only. The `Prefer: wait` header is **not** supported and returns HTTP 400 if sent. Watermark analysis is also single-file only; sending `detect_watermark=true` to this endpoint returns HTTP 400. You can submit batches in one of two ways: * **Multiple media files** — attach each file as a repeated `files[]` field in a `multipart/form-data` request. * **Single zip archive** — upload a `.zip` containing the media files; the API extracts and analyzes each entry. Exactly one of `files[]` or a single `file=<...>.zip` must be provided per request. ### Submitting multiple files ```bash curl --request POST 'https://app.resemble.ai/api/v2/detect/batch' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -F 'files[]=@/path/to/clip1.mp3' \ -F 'files[]=@/path/to/clip2.mp4' \ -F 'files[]=@/path/to/clip3.jpg' \ -F 'callback_url=https://example.com/webhooks/detect-batch' \ -F 'intelligence=true' \ -F 'infer_from_intelligence=true' \ -F 'face_only=true' \ -F 'visualize=true' ``` ### Submitting a zip archive ```bash curl --request POST 'https://app.resemble.ai/api/v2/detect/batch' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -F 'file=@/path/to/batch.zip' \ -F 'callback_url=https://example.com/webhooks/detect-batch' \ -F 'intelligence=true' ``` The zip is extracted server-side. Non-media entries inside the archive are skipped; subdirectories are flattened. ## Batch Constraints | Constraint | Value | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum files per batch | **50** | | Maximum total upload size | **500 MB** across all files combined | | Allowed extensions | `.wav`, `.mp3`, `.m4a`, `.ogg`, `.aac`, `.flac`, `.amr`, `.3gp`, `.3gpp`, `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm`, `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp` | | Synchronous mode | Not supported. `Prefer: wait` returns 400. | | Watermark analysis | Not supported. `detect_watermark=true` returns 400. | Requests outside these constraints are rejected with HTTP 400 before any analysis runs. If your team has insufficient wallet balance to cover the full batch, the request returns HTTP 402 with a per-file cost breakdown — no detects are created in that case (all-or-nothing). ## Shared Settings Settings supplied at the batch level are applied to every file in the batch. Per-file overrides are not currently supported. | Field | Applies To | Description | | ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `callback_url` | All | POST destination invoked when the batch reaches a terminal state (all detects completed or failed). | | `intelligence` | All | Boolean. Run multimodal intelligence analysis on every file. Default: `false`. | | `infer_from_intelligence` | All | Boolean. Opt in to let a strong intelligence finding escalate an otherwise non-fake verdict to *Likely Fake*. Has no effect unless `intelligence` is also `true`. Default: `false`. | | `search_identity` | Audio & Video | Boolean. Run identity search against your team's saved identities. Default: `false`. | | `visualize` | All | Boolean. Generate visualization artifacts. Default: `true`. | | `audio_source_tracing_enabled` | Audio | Boolean. Enable audio source tracing on each audio file. Default: `false`. | | `frame_length` | Audio & Video | Window size in seconds (`1`–`4`). | | `start_region` / `end_region` | Audio & Video | Analyze a segment (seconds). | | `max_video_secs` | Video | Cap processed duration. | | `use_llm` | Video | Boolean. Use LLM-assisted video analysis. | | `face_only` | Video | Boolean. Focus detection on faces for video children by masking non-face regions. Default: `false`. | | `zero_retention_mode` | All | Boolean. Apply Zero Retention Mode to every file in the batch. See [Create Detection](/detect/create) for behavior details. | When `face_only=true`, only video children use face-only mode. Audio and image children are processed normally and report an effective `face_only` value of `false`. The setting does not alter audio analysis, billing, or the batch aggregate response. ## Response ```json { "success": true, "item": { "uuid": "BATCH_UUID", "status": "processing", "total_files": 3, "completed_count": 0, "failed_count": 0, "created_at": "2024-01-15T10:30:00Z", "detect_uuids": [ "DETECT_UUID_1", "DETECT_UUID_2", "DETECT_UUID_3" ] } } ``` The response is HTTP 202 Accepted. Use the returned `detect_uuids` to query individual detection results via [`GET /detect/{uuid}`](/detect/get), including each child's effective `face_only` value, or poll the batch endpoint described below for aggregate status. The aggregate batch payload does not include `face_only`. ### Status values | Status | Meaning | | ------------------ | ------------------------------------------------------------ | | `processing` | One or more child detects are still running. | | `completed` | Every child detect completed successfully. | | `partially_failed` | At least one child detect succeeded and at least one failed. | | `failed` | Every child detect failed. | # Get Batch Status `GET https://app.resemble.ai/api/v2/detect/batch/{uuid}` Retrieve the latest aggregate status for a batch. Returns the same shape as the create response, with `status`, `completed_count`, and `failed_count` updated as child detects progress. ```bash curl --request GET 'https://app.resemble.ai/api/v2/detect/batch/BATCH_UUID' \ -H 'Authorization: Bearer YOUR_API_TOKEN' ``` ```json { "success": true, "item": { "uuid": "BATCH_UUID", "status": "completed", "total_files": 3, "completed_count": 3, "failed_count": 0, "created_at": "2024-01-15T10:30:00Z", "detect_uuids": [ "DETECT_UUID_1", "DETECT_UUID_2", "DETECT_UUID_3" ] } } ``` If the batch UUID does not belong to your team or doesn't exist, the API returns HTTP 404. ## Callback Payload When `callback_url` is provided, the API invokes it with the aggregate batch payload once the batch reaches a terminal state (`completed`, `partially_failed`, or `failed`). The payload mirrors the GET response shown above and does not include `face_only`. To retrieve each child's effective setting and detection result, follow up with `GET /detect/{uuid}` for every entry in `detect_uuids`. ## Errors | Status | Reason | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Missing `files[]` and zip `file`; both supplied; batch exceeds 50 files; total size exceeds 500 MB; unsupported file type detected; `Prefer: wait` header sent; or `detect_watermark=true`. | | 402 | Insufficient wallet balance for the projected batch cost. Response includes `details.per_file_estimates` and `details.total_estimated_cost_cents`. | | 403 | Intelligence detect limit reached on the Default plan. Response includes `details.limit`, `details.used`, `details.requested`. | | 404 | Batch UUID not found (on `GET /detect/batch/{uuid}`). |