Submit file

Once you have created an API key (Client ID + token) you can use the batch API to send audio recordings or video files for analysis.

🔉 Audio files

Audio submissions accept .wav and .mp3 recordings.

🌐 cURL Example

You can use the low-level REST API if you want to integrate our API to your application, in your language of choice (Java, nodeJS, etc.). For Python we recommend using the SDK as shown in the next section.

You can call the https://api.behavioralsignals.com/v5/detection/clients/your-cid-here/processes/audioendpoint to submit a .wav/.mp3 recording.

Example using curl:

curl --request POST \
     --url https://api.behavioralsignals.com/v5/detection/clients/<your-cid>/processes/audio \
     --header 'X-Auth-Token: <your-api-token>' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form file='@/path/to/audio.wav'

Response:

{
  "pid": <process-id>,
  "cid": <your-cid>,
  "name": null,
  "status": 0,
  "statusmsg": "Pending",
  "duration": 0.0,
  "datetime": "2025-07-29T09:14:18.261564618",
  "meta": null
}

See the notes in the relevant section of Behavioral API for error codes.

🐍 Python SDK Example

You can submit a recording using the following method:

from behavioralsignals import Client

client = Client()

process = client.deepfakes.upload_audio(file_path="audio.wav")

Client() reads your credentials from the BEHAVIORALSIGNALS_CID and BEHAVIORALSIGNALS_API_KEY environment variables (see setup).

The response is an object of class ProcessItem, defined here

🎥 Video files

🚧
Video deepfake detection is experimental
The endpoints and the response schema may still change, the models behind it are being tuned. Please get in touch before you build a production workflow on it.

A video submission runs two detectors on the one file. The picture is scored second by second, and the audio deepfake detector runs on the sound track extracted from the same file. Both sets of predictions come back from a single results call.

📋 What we accept


Containers	`mp4`, `avi`, `mov`, `mkv`, `webm`
Maximum resolution	1920x1080
Maximum upload size	100 MB per request
Video stream	Must be decodable. A corrupted file, or one with no video stream, is rejected with `400`.
Audio track	Optional. A video with no audio track is analyzed for the picture only, and the audio results come back empty.

🌐 cURL Example

Call the https://api.behavioralsignals.com/v5/detection/clients/your-cid-here/processes/video endpoint to submit a video file:

curl --request POST \
     --url https://api.behavioralsignals.com/v5/detection/clients/<your-cid>/processes/video \
     --header 'X-Auth-Token: <your-api-token>' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form file='@/path/to/video.mp4'

Response:

{
  "pid": <process-id>,
  "cid": <your-cid>,
  "name": "video.mp4",
  "status": 0,
  "statusmsg": "Pending",
  "duration": 0.0,
  "datetime": "2026-09-01T09:14:18.261564618",
  "meta": null
}

🐍 Python SDK Example

Video support requires SDK version >= 0.5.0.

from behavioralsignals import Client

client = Client()

process = client.deepfakes.upload_video(file_path="video.mp4")