Start a new process

Once you've registered with Behavioral Signals and created an API key, you have a unique Client ID (cid) and a Token. By including that token in the HTTP request header—and depending on the permissions assigned—you can send various REST requests to interact with the service.

🖥️ Submit an audio - without writing code

If you would rather not write any code yet, use the Deepfakes Dashboard. Upload a single audio file or a batch, and every file comes back with per-utterance behavioral insights and a deepfake verdict you can sort and filter.

It runs on this same API and draws on the same credit balance as your API keys, so anything you do there can be moved to an automated pipeline later without redoing the analysis.

Every upload from the dashboard is sent to both the behavioral and the deepfake detection endpoints, so each file is billed at the sum of the two rates.

🌐 Submit an audio - using the API

Using your cid, you can submit an audio file to the Behavioral Signals API via a POST request. The request should include your cid and the audio file as a form-data upload.

Upon successful submission, the response will be in application/json format and will include, among other fields, a unique process ID (pid).

For more details, see the Submit Audio File section.

Below is an example request:

curl --location 'https://api.behavioralsignals.com/v5/clients/<your-client-id>/processes/audio' \
--header 'X-Auth-Token: your-api-token' \
--form 'file=@"/path/to/your/file.wav"' \ 
--form 'name="my-awesome-audio"'

Upon successful submission, the server will return a JSON response similar to the following:

{
  "pid": 1,
  "cid": "<your-client-id>",
  "name": "my-awesome-audio",
  "status": 0,
  "statusmsg": "Pending",
  "duration": 0,
  "datetime": "2024-07-19T11:54:37.900Z",
  "meta": ""
}

The pid is a unique identifier for the processing task. You'll use it to retrieve the analysis results, as described in the next section.

🐍 Submit an audio - using the Python SDK

Submitting an audio using the SDK is straightforward:

from behavioralsignals import Client

client = Client()

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

process is an object of type ProcessItem (defined here) with the same schema as the JSON response above.