Behavioral Signals Python SDK

Python SDK for the Behavioral Signals API. Behavioral Signals builds AI solutions that understand human behavior through voice and detect deepfake content in audio. Our API enables developers to integrate behavioral analysis into their applications, both in batch and streaming modes.

Table of Contents

• Behavioral Signals Python SDK
  • Features
  • Requirements
  • API Key Setup
  • SDK Installation
  • SDK Example Usage
    • Behavioral API Batch Mode
    • Behavioral API Streaming Mode
    • Deepfakes API Batch Mode
    • Deepfakes API Streaming Mode

Features

• Behavioral Analysis API : Analyze human behavior in both batch (offline) and streaming (online) modes.

• Deepfake Detection API: Detect synthetic or manipulated speech using advanced deepfake detection models.

  • Supports batch (offline) and streaming (online) modes
  • Compatible with a wide range of spoken languages

• Core Speech Attributes (Batch Only): Extract foundational conversational metadata from both APIs:

  • Automatic Speech Recognition (ASR)
  • Speaker Diarization
  • Language Identification

Requirements

• Python3.10+,
• ffmpeg,
• Python dependencies as specified in pyproject.toml

API Key Setup

To use the Behavioral Signals API, you need to create an account and obtain an API key from the Behavioral Signals portal.

SDK Installation

pip install behavioralsignals

SDK Example Usage

After obtaining your API key, you can use the SDK to interact with the Behavioral Signals APIs. We currently provide two main APIs:

• the Behavioral API for analyzing human behavior through voice, and
• the Deepfakes API for detecting deepfake audio content in human speech.

Both APIs support batch and streaming modes, allowing you to send audio files or streams for analysis and receive results after processing and in real-time, respectively. You can also find more detailed examples for both batch and streaming in the examples/ directory.

Behavioral API Batch Mode

In batch mode, you can send audio files to the Behavioral Signals API for analysis. The API will return a unique process ID (PID) that you can use to retrieve the results later.

from behavioralsignals import Client

client = Client(YOUR_CID, YOUR_API_KEY)

response = client.behavioral.upload_audio(file_path="audio.wav")
output = client.behavioral.get_result(pid=response.pid)

Setting embeddings=True during audio upload will include speaker and behavioral embeddings in the output (see documentation):

response = client.behavioral.upload_audio(file_path="audio.wav", embeddings=True)
output = client.behavioral.get_result(pid=response.pid)

Behavioral API Streaming Mode

In streaming mode, you can send audio data in real-time to the Behavioral Signals API. The API will return results as they are processed.

from behavioralsignals import Client, StreamingOptions
from behavioralsignals.utils import make_audio_stream

client = Client(YOUR_CID, YOUR_API_KEY)
audio_stream, sample_rate = make_audio_stream("audio.wav", chunk_size=250)
options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM")

for result in client.behavioral.stream_audio(audio_stream=audio_stream, options=options):
    print(result)

Deepfakes API Batch Mode

A similar example for the Deepfakes API in batch mode allows you to send audio files for deepfake detection:

from behavioralsignals import Client

client = Client(YOUR_CID, YOUR_API_KEY)

response = client.deepfakes.upload_audio(file_path="audio.wav")
output = client.deepfakes.get_result(pid=response.pid)

Setting embeddings=True during audio upload will include speaker and deepfake embeddings in the output (see documentation):

response = client.deepfakes.upload_audio(file_path="audio.wav", embeddings=True)
output = client.deepfakes.get_result(pid=response.pid)

🔬 Experimental: Deepfake Generator Prediction (Batch Only)

An experimental option is now available that attempts to predict the generator model used to produce a deepfake. When enabled, the returned results will contain an additional field - only for audios with detected deepfake content - indicating the predicted generator model along with a confidence score.

You can activate this feature by passing enable_generator_detection=True during audio upload:

from behavioralsignals import Client

client = Client(YOUR_CID, YOUR_API_KEY)

response = client.deepfakes.upload_audio(file_path="audio.wav", enable_generator_detection=True)
output = client.deepfakes.get_result(pid=response.pid)

See more in our API documentation.

🎬 Video Deepfake Detection (Batch Only)

In addition to audio, the Deepfakes API can detect deepfakes in video files. You upload a video the same way you upload audio, and the API analyzes both the audio track and the video frames.

from behavioralsignals import Client

client = Client(YOUR_CID, YOUR_API_KEY)

response = client.deepfakes.upload_video(file_path="video.mp4")
output = client.deepfakes.get_video_result(pid=response.pid)

Unlike get_result, the video result response returns two separate lists — audio_results (deepfake detection on the audio track) and video_results (deepfake detection on the video frames):

for item in output.video_results:
    print(item.task, item.finalLabel)

You can also submit a video via an S3 presigned URL with client.deepfakes.upload_s3_presigned_video_url(url=...), and list/inspect video processes with client.deepfakes.list_video_processes() and client.deepfakes.get_video_process(pid=...). The embeddings and enable_generator_detection options are supported and apply to the audio-track results. Video deepfake detection is currently available in batch mode only.

Deepfakes API Streaming Mode

A similar streaming example for the Deepfakes API allows you to send audio data in real-time for speech deepfake detection:

from behavioralsignals import Client, StreamingOptions
from behavioralsignals.utils import make_audio_stream

client = Client(YOUR_CID, YOUR_API_KEY)
audio_stream, sample_rate = make_audio_stream("audio.wav", chunk_size=250)
options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM")

for result in client.deepfakes.stream_audio(audio_stream=audio_stream, options=options):
    print(result)