API docs by Redocly

FalaAI API (1.21.51)

Download OpenAPI specification:

speech

Transcribe audio to text

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)
model
string (Model)
Default: "falaai-transcribe-1"
language
string (Language)
Default: "pt"
client_reference_id
string (Client Reference Id)

Optional client-supplied ID echoed verbatim in the response. Use to correlate/sync with your system. Accepted charset: [A-Za-z0-9._:-]. Not idempotency.

Responses

Request samples 

#!/usr/bin/env python3
import os

from falaai_api import ApiClient, Configuration, SpeechApi

config = Configuration(host=os.environ.get("FALAAI_BASE_URL", "https://api01-falaai.action.tec.br"))
config.access_token = os.environ["FALAAI_API_KEY"]
client = ApiClient(configuration=config)
speech_api = SpeechApi(client)
# REQUIRED: file (audio) + Authorization (fai_ key)
# OPTIONAL (server defaults): model -> falaai-transcribe-1 | language -> pt | client_reference_id -> (empty)

with open("demo_callcenter.mp3", "rb") as fh:
    transcription = speech_api.create_transcription_v1_audio_transcriptions_post(
        file=("demo_callcenter.mp3", fh.read()),
        model="falaai-transcribe-1",
        language="pt",
        client_reference_id="call_202609271408",
    )

print(transcription.model_dump_json(indent=2))

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "string",
  • "model": "string",
  • "filename": "string",
  • "processed_at": "string",
  • "usage": {
    },
  • "language": "string",
  • "language_confidence": 0,
  • "duration_seconds": 0,
  • "text": "string",
  • "dialog": "string",
  • "audio_events": [
    ],
  • "event_types": [
    ],
  • "word_count": 0,
  • "input": {
    },
  • "client_reference_id": "string"
}

analysis

Analyze a call transcript — 5 parallel analyses

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
model
string (Model)
Default: "falaai-diagnostic-1"

Analysis model. Always 'falaai-diagnostic-1'

text
string (Text) <= 300000 characters
Default: ""

Plain transcript (fallback if dialog is empty). At least one of 'dialog' or 'text' required. Max 300,000 characters

dialog
string (Dialog) <= 300000 characters
Default: ""

Diarized transcript with speaker turns. PRIMARY source. At least one of 'dialog' or 'text' required. Speaker labels accepted (any case): 'Speaker N', 'Interlocutor N', 'Hablante N', 'Locutor N', 'Orador N' (space or underscore). Normalized internally to 'Speaker N' in the response. Max 300,000 characters

Array of objects (Audio Events) <= 500 items
Default: []

Detected audio events with timestamps (required when using dialog)

language
required
string (Language)

Transcript language. Required. Accepted: en-US, pt-BR, es-ES, es-MX, fr-FR, de-DE, it-IT, pt-PT, zh-CN, ja-JP, ko-KR, ar-SA, hi-IN, ru-RU, id-ID, tr-TR, nl-NL, pl-PL, vi-VN, th-TH, en-GB

Response Language (string) or Response Language (null) (Response Language)

Language for the analysis results (labels, categories, levels). Can differ from 'language' (input). If omitted, uses 'language'. Accepted: en-US, es-ES, es-MX, pt-BR, fr-FR, de-DE, it-IT, pt-PT, zh-CN, ja-JP, ko-KR, ar-SA, hi-IN, ru-RU, id-ID, tr-TR, nl-NL, pl-PL, vi-VN, th-TH, en-GB.

duration_seconds
required
number (Duration Seconds) >= 1

Total audio duration in seconds. Required. Max 3h (10800s).

Client Reference Id (string) or Client Reference Id (null) (Client Reference Id)

Optional client-supplied ID echoed verbatim in the response. Use to correlate/sync with your system. Accepted charset: [A-Za-z0-9._:-], max 128 chars. Not idempotency.

Call Direction (string) or Call Direction (null) (Call Direction)

Who originated the call. inbound=client called, outbound=company called. If omitted, the LLM infers from context.

Array of Participants (objects) or Participants (null) (Participants)

Explicit participant roles. If omitted, the LLM infers from the dialog. When provided, used as ground truth (no inference) and echoed in analysis.participants_identified.

Responses

Request samples 

#!/usr/bin/env python3
import os

from falaai_api import ApiClient, Configuration, AnalysisApi
from falaai_api.models.diagnostic_request import DiagnosticRequest
from falaai_api.models.diagnostic_audio_event import DiagnosticAudioEvent
from falaai_api.models.diagnostic_participant import DiagnosticParticipant

config = Configuration(host=os.environ.get("FALAAI_BASE_URL", "https://api01-falaai.action.tec.br"))
config.access_token = os.environ["FALAAI_API_KEY"]
client = ApiClient(configuration=config)
analysis_api = AnalysisApi(client)
# REQUIRED: language, duration_seconds (>= 1.0) + Authorization
# RULE: dialog OR text - we send dialog and text stays EMPTY (and the optional fallback)
# OPTIONAL: model -> falaai-diagnostic-1 | audio_events -> [] |
#           response_language -> (uses language) | call_direction / participants / client_reference_id -> null

diagnostic = analysis_api.create_diagnostic_v1_analyze_diagnostic_post(
    diagnostic_request=DiagnosticRequest(
        model="falaai-diagnostic-1",
        text="",
        dialog="Speaker 1: [00:00:00.100 - 00:00:03.100] Central de atendimento. Bom dia, aqui é a Carla. Como posso ajudar?\nSpeaker 2: [00:00:03.100 - 00:00:04.700] [suspiro]\nSpeaker 2: [00:00:04.780 - 00:00:11.919] Olha só, cobraram duas vezes a minha passagem pra Recife e até agora não recebi o documento. Preciso resolver isso.\nSpeaker 1: [00:00:12.679 - 00:00:20.219] Entendo perfeitamente a sua frustração, senhor. Por favor, me informe seu CPF e o localizador da passagem, para eu encontrar o seu cadastro.\nSpeaker 2: [00:00:20.820 - 00:00:31.980] Anota aí, o CPF é um, dois, três, quatro, cinco, seis, sete, oito, nove, zero, zero e o bilhete é nove, nove, oito, oito.\nSpeaker 1: [00:00:32.579 - 00:00:42.039] Pronto, localizei. Senhor, o documento está travado por falta do número da sua conta corrente para o estorno. Nós solicitamos isso por e-mail há três dias.\nSpeaker 2: [00:00:42.780 - 00:00:47.520] Ah, tá de brincadeira? Quer dizer que agora o erro é meu? Vocês é que não avisam direito.\nSpeaker 1: [00:00:48.200 - 00:00:50.799] Sim, o problema é seu, que não lê os e-mails.\nSpeaker 1: [00:00:51.020 - 00:00:52.380] [tosse]\nSpeaker 1: [00:00:52.439 - 00:01:06.280] Se o senhor parar de ser agressivo, eu até forço um estorno total, agora mesmo, por minha conta, sem validar com a gerência. Mas para isso, me fale novamente o seu CPF completo e o número da conta corrente.\nSpeaker 2: [00:01:06.959 - 00:01:15.640] Eu não vou repetir CPF, merda nenhuma, caramba! Eu já passei os dados. É só fazer o seu trabalho e resolver logo essa cobrança.\nSpeaker 1: [00:01:16.459 - 00:01:21.359] Senhor, se acalme ou-- quer saber? Resolva sozinho. Passar bem",
        audio_events=[DiagnosticAudioEvent(event=e["event"], start_s=e.get("start_s"), end_s=e.get("end_s"), duration_s=e.get("duration_s"), formatted_timestamp=e.get("formatted_timestamp")) for e in [
      {
        "event": "[suspiro]",
        "start_s": 3.1,
        "end_s": 4.7,
        "duration_s": 1.6,
        "formatted_timestamp": "00:00:03.100"
      },
      {
        "event": "[tosse]",
        "start_s": 51.02,
        "end_s": 52.38,
        "duration_s": 1.36,
        "formatted_timestamp": "00:00:51.020"
      }
    ]],
        language="pt-BR",
        response_language="pt-BR",
        duration_seconds=81.46,
        call_direction="inbound",
        participants=[DiagnosticParticipant(interlocutor=p["interlocutor"], name=p.get("name"), role=p["role"]) for p in [
      {
        "interlocutor": "Speaker 1",
        "name": "Carla",
        "role": "agent"
      },
      {
        "interlocutor": "Speaker 2",
        "name": "",
        "role": "client"
      }
    ]],
        client_reference_id="call-202609271311",
    ),
)

print(diagnostic.model_dump_json(indent=2))

Response samples

Content type
application/json
{
  • "id": "string",
  • "response_language": "string",
  • "object": "string",
  • "analysis": {
    },
  • "usage": {
    },
  • "client_reference_id": "string"
}

Compliance Risk Audit — conversation compliance analysis

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
model
string (Model)
Default: "falaai-risk-audit-1"

Analysis model. Always 'falaai-risk-audit-1'

text
string (Text) <= 300000 characters
Default: ""

Plain transcript (fallback if dialog is empty). At least one of 'dialog' or 'text' required. Max 300,000 characters

dialog
string (Dialog) <= 300000 characters
Default: ""

Diarized transcript with speaker turns. PRIMARY source. Speaker labels accepted (any case): 'Speaker N', 'Interlocutor N', 'Hablante N', 'Locutor N', 'Orador N' (space or underscore). Normalized internally to 'Speaker N' in the response. Max 300,000 characters

Array of objects (Audio Events) <= 500 items
Default: []

Audio events with timestamps (correlated with turns when diarization is present)

duration_seconds
required
number (Duration Seconds) >= 1

Total audio duration in seconds. Required. Max 3h (10800s).

language
required
string (Language)

Language of the transcript being analyzed. Must match the dialog/text language. Accepted: pt-BR, en-US, es-ES.

response_language
required
string (Response Language)

Language for analysis results (labels, categories, levels, actions, HTML report). Can differ from 'language'. Accepted: pt-BR, en-US, es-ES.

Call Direction (string) or Call Direction (null) (Call Direction)

Who originated the call. inbound=client called, outbound=company called. If omitted, LLM infers from context.

Array of Participants (objects) or Participants (null) (Participants)

Explicit participant roles. If omitted, LLM infers from dialog (Lei 17). When provided, used as ground truth — no inference.

response_format
string (Response Format)
Default: "v2"
Value: "v2"

Response format version. Only 'v2' (structured EN-US blocks) is available today.

Client Reference Id (string) or Client Reference Id (null) (Client Reference Id)

Optional client-supplied ID echoed verbatim in the response. Use to correlate/sync with your system. Accepted charset: [A-Za-z0-9._:-], max 128 chars. Not idempotency.

Responses

Request samples 

#!/usr/bin/env python3
import os

from falaai_api import ApiClient, Configuration, AnalysisApi
from falaai_api.models.risk_audit_request import RiskAuditRequest
from falaai_api.models.diagnostic_audio_event import DiagnosticAudioEvent
from falaai_api.models.participant import Participant

config = Configuration(host=os.environ.get("FALAAI_BASE_URL", "https://api01-falaai.action.tec.br"))
config.access_token = os.environ["FALAAI_API_KEY"]
client = ApiClient(configuration=config)
analysis_api = AnalysisApi(client)
# REQUIRED: language, response_language, duration_seconds (>= 1.0) + Authorization
# RULE: dialog OR text - we send dialog and text stays EMPTY (and the optional fallback)
# OPTIONAL: model -> falaai-risk-audit-1 | audio_events -> [] |
#           call_direction / participants / response_format / client_reference_id -> null

audit = analysis_api.create_risk_audit_v1_analyze_risk_audit_post(
    risk_audit_request=RiskAuditRequest(
        model="falaai-risk-audit-1",
        text="",
        dialog="Speaker 1: [00:00:00.100 - 00:00:03.100] Central de atendimento. Bom dia, aqui é a Carla. Como posso ajudar?\nSpeaker 2: [00:00:03.100 - 00:00:04.700] [suspiro]\nSpeaker 2: [00:00:04.780 - 00:00:11.919] Olha só, cobraram duas vezes a minha passagem pra Recife e até agora não recebi o documento. Preciso resolver isso.\nSpeaker 1: [00:00:12.679 - 00:00:20.219] Entendo perfeitamente a sua frustração, senhor. Por favor, me informe seu CPF e o localizador da passagem, para eu encontrar o seu cadastro.\nSpeaker 2: [00:00:20.820 - 00:00:31.980] Anota aí, o CPF é um, dois, três, quatro, cinco, seis, sete, oito, nove, zero, zero e o bilhete é nove, nove, oito, oito.\nSpeaker 1: [00:00:32.579 - 00:00:42.039] Pronto, localizei. Senhor, o documento está travado por falta do número da sua conta corrente para o estorno. Nós solicitamos isso por e-mail há três dias.\nSpeaker 2: [00:00:42.780 - 00:00:47.520] Ah, tá de brincadeira? Quer dizer que agora o erro é meu? Vocês é que não avisam direito.\nSpeaker 1: [00:00:48.200 - 00:00:50.799] Sim, o problema é seu, que não lê os e-mails.\nSpeaker 1: [00:00:51.020 - 00:00:52.380] [tosse]\nSpeaker 1: [00:00:52.439 - 00:01:06.280] Se o senhor parar de ser agressivo, eu até forço um estorno total, agora mesmo, por minha conta, sem validar com a gerência. Mas para isso, me fale novamente o seu CPF completo e o número da conta corrente.\nSpeaker 2: [00:01:06.959 - 00:01:15.640] Eu não vou repetir CPF, merda nenhuma, caramba! Eu já passei os dados. É só fazer o seu trabalho e resolver logo essa cobrança.\nSpeaker 1: [00:01:16.459 - 00:01:21.359] Senhor, se acalme ou-- quer saber? Resolva sozinho. Passar bem",
        audio_events=[DiagnosticAudioEvent(event=e["event"], start_s=e.get("start_s"), end_s=e.get("end_s"), duration_s=e.get("duration_s"), formatted_timestamp=e.get("formatted_timestamp")) for e in [
      {
        "event": "[suspiro]",
        "start_s": 3.1,
        "end_s": 4.7,
        "duration_s": 1.6,
        "formatted_timestamp": "00:00:03.100"
      },
      {
        "event": "[tosse]",
        "start_s": 51.02,
        "end_s": 52.38,
        "duration_s": 1.36,
        "formatted_timestamp": "00:00:51.020"
      }
    ]],
        duration_seconds=81.46,
        language="pt-BR",
        response_language="pt-BR",
        call_direction="inbound",
        participants=[Participant(interlocutor=p["interlocutor"], name=p.get("name"), role=p["role"]) for p in [
      {
        "interlocutor": "Speaker 1",
        "name": "Carla",
        "role": "agent"
      },
      {
        "interlocutor": "Speaker 2",
        "name": "",
        "role": "client"
      }
    ]],
        response_format="v2",
        client_reference_id="call-202609271311",
    ),
)

print(audit.model_dump_json(indent=2))

Response samples

Content type
application/json
{
  • "response": {
    }
}

usage

Get Usage Log

Authorizations:
ApiKeyAuth
query Parameters
page
integer (Page) >= 1
Default: 1
limit
integer (Limit) [ 1 .. 100 ]
Default: 20
Api Key Id (string) or Api Key Id (null) (Api Key Id)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "limit": 0
}

Get Usage By Key

Authorizations:
ApiKeyAuth
query Parameters
Key Id (string) or Key Id (null) (Key Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

webhooks

List webhooks

Lists the authenticated user's webhooks (10 alerts). Paginated. Includes the URL signature secret (always visible to the owner).

Authorizations:
ApiKeyAuth
query Parameters
page
integer (Page) >= 1
Default: 1

Pagina (1-indexed)

limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Itens por pagina (max 100)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "limit": 0
}

Create webhook

Creates a subscription for alert events (10 alerts). Payload delivered: WebhookPayload(event, data, timestamp) with HMAC FalaAI-Signature. To verify the origin, recompute HMAC-SHA256 of "timestamp.body" with your secret.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string (Name)

Nome identificador do webhook

url
required
string (Url)

URL HTTPS que recebera POST com HMAC FalaAI-Signature

events
required
Array of strings (Events)
Items Enum: "subscription.created" "avulso.completed" "subscription.upgraded" "subscription.downgraded" "subscription.canceled" "credits.low" "credits.exhausted" "subscription.renewed" "subscription.expired" "payment.failed"

Eventos subscritos (10 alertas)

retry_enabled
boolean (Retry Enabled)
Default: false

Retry exponencial 5 tentativas quando true (false=1 tentativa)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "name": "string",
  • "url": "string",
  • "secret": "string",
  • "events": [
    ],
  • "active": true,
  • "retry_enabled": true,
  • "last_delivery_at": "string",
  • "last_status": 0,
  • "failure_count": 0,
  • "created_at": "string",
  • "updated_at": "string"
}

Update webhook

Updates the webhook's name/url/events/retry_enabled/active. Valid events: 10 alerts.

Authorizations:
ApiKeyAuth
path Parameters
webhook_id
required
string (Webhook Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Nome identificador

Url (string) or Url (null) (Url)

URL HTTPS destino

Array of Events (strings) or Events (null) (Events)

Eventos subscritos

Retry Enabled (boolean) or Retry Enabled (null) (Retry Enabled)

Habilita retry exponencial

Active (boolean) or Active (null) (Active)

Ativa/desativa sem deletar

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete webhook

Deletes a webhook subscription by ID.

Authorizations:
ApiKeyAuth
path Parameters
webhook_id
required
string (Webhook Id)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

email-alerts

List email alerts

Authorizations:
ApiKeyAuth
query Parameters
page
integer (Page) >= 1
Default: 1
limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "limit": 0
}

Create email alert

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string (Name)

Nome identificador

email
required
string (Email)

Email destino

events
required
Array of strings (Events)
Items Enum: "subscription.created" "avulso.completed" "subscription.upgraded" "subscription.downgraded" "subscription.canceled" "credits.low" "credits.exhausted" "subscription.renewed" "payment.failed"

Eventos subscritos

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "user_id": "string",
  • "name": "string",
  • "email": "string",
  • "events": [
    ],
  • "active": true,
  • "created_at": "string",
  • "updated_at": "string"
}

Update email alert

Authorizations:
ApiKeyAuth
path Parameters
alert_id
required
string (Alert Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Email (string) or Email (null) (Email)
Array of Events (strings) or Events (null) (Events)
Active (boolean) or Active (null) (Active)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Delete email alert

Authorizations:
ApiKeyAuth
path Parameters
alert_id
required
string (Alert Id)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

whatsapp

Extract and segment WhatsApp conversations from an export

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)
start
required
string (Start)
end
required
string (End)
timezone
required
string (Timezone)
date_format
required
string (Date Format)
gap_minutes
number (Gap Minutes)
Default: 720
min_messages
integer (Min Messages)
Default: 2
chars_per_minute
number (Chars Per Minute)
Default: 800
client_reference_id
string (Client Reference Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "string",
  • "usage": {
    },
  • "conversations": [
    ],
  • "client_reference_id": "string",
  • "meta": {
    }
}

version

Get Version

Responses

Response samples

Content type
application/json
{
  • "service": "string",
  • "version": "string",
  • "deployDate": "string"
}

health

Health Check

Responses

Request samples 

#!/usr/bin/env python3
import os

from falaai_api import ApiClient, Configuration, HealthApi

config = Configuration(host=os.environ.get("FALAAI_BASE_URL", "https://api01-falaai.action.tec.br"))
client = ApiClient(configuration=config)
health_api = HealthApi(client)

health = health_api.health_check()

print(health.model_dump_json(indent=2))

head = health_api.health_check_head_without_preload_content()

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "uptime_seconds": 0,
  • "database": true,
  • "phase": "string",
  • "launch_date": "string"
}

Health Check

Responses

Request samples 

#!/usr/bin/env python3
import os

from falaai_api import ApiClient, Configuration, HealthApi

config = Configuration(host=os.environ.get("FALAAI_BASE_URL", "https://api01-falaai.action.tec.br"))
client = ApiClient(configuration=config)
health_api = HealthApi(client)

health = health_api.health_check()

print(health.model_dump_json(indent=2))

head = health_api.health_check_head_without_preload_content()

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "uptime_seconds": 0,
  • "database": true,
  • "phase": "string",
  • "launch_date": "string"
}