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:
multipart/form-data request with the file attached as file. Best for one-off requests against files up to 150 MB.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.POST /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.
Optional parameters (callback_url, intelligence, visualize, etc.) are sent as additional form fields when uploading directly.
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.
First, upload the file to obtain a token (see Secure Upload):
Then submit the detect job using the returned token as media_token:
Provide exactly one of the following.
By default, the API responds immediately while processing continues in the background:
Use the UUID to check status via the Get Detection Result endpoint, or provide a callback_url to receive results automatically.
Prefer: wait header)When using the Prefer: wait header, the API returns complete results immediately:
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:
When zero_retention_mode=true, the API enables a privacy lifecycle for the submitted media:
url and audio_url are set to null in all responses, both during processing and after completion.redacted_abc123def4567890abcd1234.mp3).file_deleted_at timestamp is set once the purge succeeds.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.
Once the media file has been purged, file_deleted_at is populated with the purge timestamp:
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.