FalaAI API (1.21.49)

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

import { Configuration, SpeechApi } from "falaai-api";
import { readFileSync } from "node:fs";

const config = new Configuration({
  basePath: process.env.FALAAI_BASE_URL ?? "https://api01-falaai.action.tec.br",
  accessToken: process.env.FALAAI_API_KEY ?? "",
});
const speechApi = new SpeechApi(config);

const model = "falaai-transcribe-1";
const language = "pt";
const clientReferenceId = "call_202609271408";

const file = new Blob([readFileSync("demo_callcenter.mp3")], { type: "audio/mpeg" });

// REQUIRED: file (audio) + Authorization (fai_ key)
// OPTIONAL (server defaults): model -> falaai-transcribe-1 | language -> pt | client_reference_id -> (empty)
const transcription = await speechApi.createTranscriptionV1AudioTranscriptionsPost({
  file,
  model,
  language,
  clientReferenceId,
});
console.log(JSON.stringify(transcription, null, 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

import { Configuration, AnalysisApi } from "falaai-api";

const config = new Configuration({
  basePath: process.env.FALAAI_BASE_URL ?? "https://api01-falaai.action.tec.br",
  accessToken: process.env.FALAAI_API_KEY ?? "",
});
const analysisApi = new AnalysisApi(config);

// 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
const diagnostic = await analysisApi.createDiagnosticV1AnalyzeDiagnosticPost({
  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",
    audioEvents: [
      {
        "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",
    responseLanguage: "pt-BR",
    durationSeconds: 81.46,
    callDirection: "inbound",
    participants: [
      {
        "interlocutor": "Speaker 1",
        "name": "Carla",
        "role": "agent"
      },
      {
        "interlocutor": "Speaker 2",
        "name": "",
        "role": "client"
      }
    ],
    clientReferenceId: "call-202609271311",
  },
});
console.log(JSON.stringify(diagnostic, null, 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) ^v[0-9]+$
Default: "v2"

Response format version. v1=legacy flat PT-BR, v2=structured EN-US blocks.

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

import { Configuration, AnalysisApi } from "falaai-api";

const config = new Configuration({
  basePath: process.env.FALAAI_BASE_URL ?? "https://api01-falaai.action.tec.br",
  accessToken: process.env.FALAAI_API_KEY ?? "",
});
const analysisApi = new AnalysisApi(config);

// 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
const audit = await analysisApi.createRiskAuditV1AnalyzeRiskAuditPost({
  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",
    audioEvents: [
      {
        "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"
      }
    ],
    durationSeconds: 81.46,
    language: "pt-BR",
    responseLanguage: "pt-BR",
    callDirection: "inbound",
    participants: [
      {
        "interlocutor": "Speaker 1",
        "name": "Carla",
        "role": "agent"
      },
      {
        "interlocutor": "Speaker 2",
        "name": "",
        "role": "client"
      }
    ],
    responseFormat: "v2",
    clientReferenceId: "call-202609271311",
  },
});
console.log(JSON.stringify(audit, null, 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"
}

version

Get Version

Responses

Response samples

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

health

Health Check

Responses

Request samples

import { Configuration, HealthApi } from "falaai-api";

const config = new Configuration({
  basePath: process.env.FALAAI_BASE_URL ?? "https://api01-falaai.action.tec.br",
});
const healthApi = new HealthApi(config);

const health = await healthApi.healthCheck();

const head = await healthApi.healthCheckHeadRaw();
console.log(JSON.stringify(health, null, 2));

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

import { Configuration, HealthApi } from "falaai-api";

const config = new Configuration({
  basePath: process.env.FALAAI_BASE_URL ?? "https://api01-falaai.action.tec.br",
});
const healthApi = new HealthApi(config);

const health = await healthApi.healthCheck();

const head = await healthApi.healthCheckHeadRaw();
console.log(JSON.stringify(health, null, 2));

Response samples

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