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.

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

$
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

$
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

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.

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

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "BATCH_UUID",
5
    "status": "processing",
6
    "total_files": 3,
7
    "completed_count": 0,
8
    "failed_count": 0,
9
    "created_at": "2024-01-15T10:30:00Z",
10
    "detect_uuids": [
11
      "DETECT_UUID_1",
12
      "DETECT_UUID_2",
13
      "DETECT_UUID_3"
14
    ]
15
  }
16
}

The response is HTTP 202 Accepted. Use the returned detect_uuids to query individual detection results via GET /detect/{uuid}, 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

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.

$
curl --request GET 'https://app.resemble.ai/api/v2/detect/batch/BATCH_UUID' \
>
  -H 'Authorization: Bearer YOUR_API_TOKEN'

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "BATCH_UUID",
5
    "status": "completed",
6
    "total_files": 3,
7
    "completed_count": 3,
8
    "failed_count": 0,
9
    "created_at": "2024-01-15T10:30:00Z",
10
    "detect_uuids": [
11
      "DETECT_UUID_1",
12
      "DETECT_UUID_2",
13
      "DETECT_UUID_3"
14
    ]
15
  }
16
}

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