Download OpenAPI specification:
| 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. |
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));
{- "id": "string",
- "object": "string",
- "model": "string",
- "filename": "string",
- "processed_at": "string",
- "usage": {
- "audio_seconds": 0,
- "credits_consumed": 0,
- "processing_ms": 0
}, - "language": "string",
- "language_confidence": 0,
- "duration_seconds": 0,
- "text": "string",
- "dialog": "string",
- "audio_events": [
- {
- "event": "string",
- "start_s": 0,
- "end_s": 0,
- "duration_s": 0,
- "formatted_timestamp": "string"
}
], - "event_types": [
- "string"
], - "word_count": 0,
- "input": {
- "duration_s": 0,
- "original_format": "string",
- "codec": "string",
- "sample_rate": 0,
- "channels": 0
}, - "client_reference_id": "string"
}| 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. |
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));
{- "id": "string",
- "response_language": "string",
- "object": "string",
- "analysis": {
- "dialogue_summary": {
- "explanation": "string"
}, - "contact_reason": {
- "explanation": "string"
}, - "identified_action": {
- "list_choice": "string",
- "justification": "string",
- "evidence_phrases": [ ]
}, - "identified_label": {
- "list_choice": "string",
- "justification": "string",
- "evidence_phrases": [ ]
}, - "sentiment": {
- "list_choice": "string",
- "justification": "string",
- "evidence_phrases": [ ]
}, - "participants_identified": [ ]
}, - "usage": {
- "characters": 0,
- "credits_consumed": 0,
- "processing_ms": 0
}, - "client_reference_id": "string"
}| 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. |
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": {
- "meta": {
- "id": "string",
- "object": "risk_audit",
- "call_duration_s": 0,
- "analyzed_at": "string",
- "usage": {
- "characters": 0,
- "credits_consumed": 0,
- "processing_ms": 0
}, - "client_reference_id": "string"
}, - "participants": {
- "identified": [ ],
- "call_direction": "string",
- "role_inference_reliable": true,
- "identification_status": "none",
- "unidentified_items_count": 0
}, - "verdict": {
- "label": "string",
- "level_code": "string",
- "color": "string",
- "icon": "string",
- "risk_matrix": { },
- "applied_actions": [ ],
- "decision_details": { }
}, - "scores": {
- "conversation": {
- "consolidated_score": 0,
- "violation_density_per_min": 0,
- "sentiment_trend": { },
- "pct_turns_with_violation": 0,
- "most_critical_turn": { },
- "positive_negative_ratio": { },
- "global_risk_severity": "string",
- "global_risk_severity_label": "string",
- "global_risk_severity_color": "string",
- "risk_likelihood_avg": 0,
- "risk_impact_avg": 0
}, - "per_participant": { }
}, - "detections": {
- "violations": [ ],
- "positives": [ ],
- "client_risk_alerts": [ ],
- "client_behavior_alerts": [ ],
- "client_negatives": [ ]
}, - "analysis": {
- "global_metrics": { },
- "final_analysis": { },
- "frameworks": { }
}, - "timeline": {
- "turns_sentiment": [ ],
- "audio_events": [ ],
- "audio_groups_found": [ ]
}, - "audio_event_model": {
- "model": "",
- "description": "",
- "windows_s": { }
}, - "categories_summary": { },
- "indexer": {
- "suggested_terms_for_bank": [ ]
}, - "summary": {
- "total_turns": 0,
- "total_calibrated": 0,
- "active": 0,
- "tolerated": 0,
- "blocked": 0,
- "audio_events_used": 0,
- "audio_events_aggravated": 0,
- "mac_audio_applied": { },
- "mvad_applied": { },
- "total_participants": 0,
- "total_agents": 0,
- "total_clients": 0,
- "total_bots": 0,
- "total_unknown": 0,
- "client_risk_alerts_count": 0,
- "client_behavior_alerts_count": 0
}, - "actions_i18n": { },
- "audit_decisions": {
- "risk_origin": "string",
- "has_zero_tolerance_violation": true,
- "deterministic_validator_changes": [ ]
}, - "scoring_explanation": {
- "summary": "string",
- "steps": [ ]
}, - "html_report": "string"
}
}| 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) |
{- "data": [
- {
- "id": "string",
- "endpoint": "string",
- "credits_cost": 0,
- "status": "string",
- "errors_count": 0,
- "created_at": "string"
}
], - "page": 0,
- "limit": 0
}Lists the authenticated user's webhooks (10 alerts). Paginated. Includes the URL signature secret (always visible to the owner).
| page | integer (Page) >= 1 Default: 1 Pagina (1-indexed) |
| limit | integer (Limit) [ 1 .. 100 ] Default: 20 Itens por pagina (max 100) |
{- "data": [
- {
- "id": "string",
- "user_id": "string",
- "name": "string",
- "url": "string",
- "secret": "string",
- "events": [
- "string"
], - "active": true,
- "retry_enabled": true,
- "last_delivery_at": "string",
- "last_status": 0,
- "failure_count": 0,
- "created_at": "string",
- "updated_at": "string"
}
], - "page": 0,
- "limit": 0
}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.
| 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) |
{- "id": "string",
- "user_id": "string",
- "name": "string",
- "url": "string",
- "secret": "string",
- "events": [
- "string"
], - "active": true,
- "retry_enabled": true,
- "last_delivery_at": "string",
- "last_status": 0,
- "failure_count": 0,
- "created_at": "string",
- "updated_at": "string"
}Updates the webhook's name/url/events/retry_enabled/active. Valid events: 10 alerts.
| webhook_id required | string (Webhook Id) |
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 |
{- "message": "string"
}| page | integer (Page) >= 1 Default: 1 |
| limit | integer (Limit) [ 1 .. 100 ] Default: 20 |
{- "data": [
- {
- "id": "string",
- "user_id": "string",
- "name": "string",
- "email": "string",
- "events": [
- "string"
], - "active": true,
- "created_at": "string",
- "updated_at": "string"
}
], - "page": 0,
- "limit": 0
}| 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 |
{- "id": "string",
- "user_id": "string",
- "name": "string",
- "email": "string",
- "events": [
- "string"
], - "active": true,
- "created_at": "string",
- "updated_at": "string"
}| alert_id required | string (Alert Id) |
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) |
{- "message": "string"
}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));
{- "status": "string",
- "version": "string",
- "uptime_seconds": 0,
- "database": true,
- "phase": "string",
- "launch_date": "string"
}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));
{- "status": "string",
- "version": "string",
- "uptime_seconds": 0,
- "database": true,
- "phase": "string",
- "launch_date": "string"
}