Safety & Detection

Detect Your First Deepfake

Submit an audio, image, or video file to Resemble Detect, wait for the analysis to finish, and read the authenticity verdict.

What You Will Build

This walkthrough uses the asynchronous API workflow:

  1. Submit a local media file.
  2. Save the detection UUID.
  3. Poll the detection until it reaches a terminal status.
  4. Read the result for the submitted media type.

Prerequisites

  • A Resemble API token with Deepfake Detection access
  • A local audio, image, or video file smaller than 150 MB
  • curl and jq

Set your API token and the path to your test file:

$export RESEMBLE_API_TOKEN="YOUR_API_TOKEN"
$export MEDIA_PATH="/path/to/media.mp4"

1. Submit the Media

Send the file as multipart/form-data:

$DETECT_RESPONSE=$(curl --silent --show-error --fail-with-body \
>  --request POST 'https://app.resemble.ai/api/v2/detect' \
>  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
>  -F "file=@${MEDIA_PATH}")
$
$echo "${DETECT_RESPONSE}" | jq

The API returns immediately while the analysis runs. Save the detection UUID from the response:

$export DETECT_UUID=$(echo "${DETECT_RESPONSE}" | jq -r '.item.uuid')
$echo "Detection UUID: ${DETECT_UUID}"

Provide exactly one media source per request. In addition to a direct file upload, the API accepts a public url or a token from Secure Upload.

2. Wait for the Result

Poll the detection endpoint until the job is complete or has failed:

$while true; do
$  DETECT_RESULT=$(curl --silent --show-error --fail-with-body \
>    --request GET \
>    "https://app.resemble.ai/api/v2/detect/${DETECT_UUID}" \
>    -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}")
$
$  STATUS=$(echo "${DETECT_RESULT}" | jq -r '.item.status')
$  echo "Status: ${STATUS}"
$
$  case "${STATUS}" in
$    completed) break ;;
$    failed)
$      echo "${DETECT_RESULT}" | jq
$      exit 1
$      ;;
$  esac
$
$  sleep 3
$done

Print the completed response:

$echo "${DETECT_RESULT}" | jq

For production workloads, use a callback_url instead of polling continuously. For a one-off synchronous request, add the Prefer: wait header when submitting the detection.

3. Read the Verdict

The result fields depend on the media type:

MediaPrimary resultUseful fields
Audioitem.metricslabel, aggregated_score, consistency
Imageitem.image_metricslabel, score, heatmap when visualization is enabled
Videoitem.metrics and item.video_metricsSeparate audio and visual findings when both modalities are analyzed

For audio, print a compact summary:

$echo "${DETECT_RESULT}" | jq '{
>  uuid: .item.uuid,
>  media_type: .item.media_type,
>  label: .item.metrics.label,
>  score: .item.metrics.aggregated_score
>}'

For an image:

$echo "${DETECT_RESULT}" | jq '{
>  uuid: .item.uuid,
>  media_type: .item.media_type,
>  label: .item.image_metrics.label,
>  score: .item.image_metrics.score
>}'

For a video, inspect both audio and visual findings. If the request used modality=audio or modality=video, the skipped result object is absent.

Use the returned label and supporting metrics together with your application context. Detection scores should inform a review workflow rather than act as the only basis for a consequential decision.

Troubleshooting

ResponseWhat to check
400 Bad RequestThe file is empty, unsupported, larger than 150 MB, or more than one media source was supplied.
401 UnauthorizedThe API token is missing or invalid.
403 ForbiddenThe account does not have Deepfake Detection access.
status: failedInspect the response for the job’s error message and confirm that the source media is readable.

Extend the Workflow