FalaAI API — Manual de uso, campos y flujos

Vision general

La FalaAI API es un conjunto de APIs independientes. No necesitas transcribir con FalaAI para diagnosticar o auditar: si ya tienes el texto, envialo directo al analisis (BYOT).

• Clave: todas las rutas exigen Authorization: Bearer fai_<tu_clave>, excepto GET/HEAD /v1/health y GET /api/version.
• Zero-storage (LGPD): audio/texto/resultado se procesan en memoria y se descartan.
• Idiomas: transcripcion en 31 idiomas; diagnostico en 21 locales; auditoria y reporte HTML en 3 (pt/en/es).

Autenticacion

Para que sirve: como probar quien eres en cada llamada.

• Clave: toda ruta exige el header Authorization: Bearer fai_<tu_clave> — excepto GET/HEAD /v1/health y GET /api/version (publicas, sin clave).
• Como obtenerla: crea la cuenta y genera la API Key en el Dashboard. La clave aparece una unica vez (show-once) — guardala con seguridad.
• Scopes: cada clave tiene scopes — transcribe, diagnostic, auditoria, whatsapp, alerts, billing, invoices (o * para todos). Ruta sin el scope exigido → 403 insufficient_scope.
• JWT: ademas de la clave fai_, la API acepta JWT de sesion en las mismas rutas.

Errores de autenticacion

Campos obligatorios — resumen rapido

Si solo quieres hacerlo funcionar, estos son los campos que la API exige en cada endpoint:

GET /v1/health publico

Para que sirve: solo decir si el servidor esta activo y la version/uptime/estado de la base. No analiza nada.

flowchart LR
  A[Monitor / uptime / curl] -->|GET /v1/health| B{{FalaAI API}}
  B -->|200| C[status, version, uptime, database]
  A2[Comprobacion ligera] -->|HEAD /v1/health| B
  B -->|200 sin cuerpo| D[solo el codigo HTTP]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,A2,C,D pub
  class B api

Campos

Ninguno.

Solicitud (ejemplo cURL)

cargando...

Respuesta — campos

HEAD /v1/health = mismo 200 sin cuerpo.

Ejemplo de respuesta (JSON)

cargando...

Flujos posibles

• Uptime/monitor (cada 1 min) con alerta si != 200.
• Health check de deploy (mas barato): HEAD.
• Leer la version de la API para log.

GET /api/version publico

Para que sirve: identificar la version del contrato en uso (fijar la compatibilidad de tu cliente).

flowchart LR
  A[Tu cliente / CI] -->|GET /api/version| B{{FalaAI API}}
  B --> C[version del contrato]
  C --> D[Fijar/validar compatibilidad]
  classDef pub fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  class A,C,D pub
  class B api

Campos

Ninguno.

Respuesta

POST /v1/audio/transcriptions multipart/form-data

Para que sirve: convertir audio en texto con separacion de quien hablo (diarizacion), timestamps y eventos de audio.

Campos

Solicitud (ejemplo cURL)

cargando...

Respuesta — campos

Ejemplo de respuesta (JSON)

cargando...

Flujo

flowchart TD
  S([Tienes el audio?]) -->|si| U[Elegir el archivo: mp3, mp4, m4a, wav, flac, ogg, opus, webm, aac... hasta 1GB / 3h]
  U --> T[POST /v1/audio/transcriptions + file]
  T --> R[Respuesta: text, dialog, audio_events, duration_seconds, usage]
  R --> D1[Usar en Diagnostic]
  R --> A1[Usar en Risk Audit]
  R --> DB[(Tu base / CRM / BI)]
  S -->|no, ya tengo texto| B[Saltar: ir directo a Diagnostic o Risk Audit]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class S,U,B in
  class T api
  class R,D1,A1,DB out

Flujos posibles

• Audio → transcripcion → diagnostico (resumen, motivo, accion, topico, sentimiento).
• Audio → transcripcion → auditoria de riesgo (score + violaciones + reporte).
• Audio → transcripcion → (diagnostico + auditoria) en la misma conversacion.
• Lote: repetir por archivo en cola y consolidar por cuenta/equipo.

POST /v1/analyze/diagnostic application/json

Para que sirve: diagnosticar la conversacion — 5 analisis en una llamada.

Campos

Solicitud (ejemplo cURL)

cargando...

Respuesta — campos

Ejemplo de respuesta (JSON)

cargando...

Flujo

flowchart TD
  I{Como tienes la conversacion?} -->|transcripcion simple| X[text = transcripcion corrida + language]
  I -->|con quien hablo| Y[dialog = turnos con hablante y tiempos + language + duration_seconds]
  X --> P[POST /v1/analyze/diagnostic]
  Y --> P
  P --> R[summary, contact_reason, action_taken, topic, sentiment]
  R --> O1[Dashboard de calidad / CX]
  R --> O2[CRM / ticket / ERP]
  R --> O3[BI / warehouse]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class I,X,Y in
  class P api
  class R,O1,O2,O3 out

Flujos posibles

• Ya tengo transcripcion (Whisper/Deepgram/propia) → solo diagnosticar (BYOT).
• Audio → transcripcion → diagnostico (pipeline completo).
• Diagnostico + auditoria en la misma conversacion.
• Lote por conversacion y agregacion por periodo/equipo (client_reference_id para rastrear).

POST /v1/analyze/riskAudit application/json

Para que sirve: auditar riesgo/compliance (COPC CX, ISO 18295-1, LGPD): score, detecciones/violaciones, evidencias y reporte HTML auditable.

Campos

Solicitud (ejemplo cURL)

cargando...

Respuesta — campos (dentro de response)

Ejemplo de respuesta (JSON)

cargando...

Flujo

flowchart TD
  A{Ya tengo el dialog?} -->|si| P[POST /v1/analyze/riskAudit + dialog + duration_seconds + language + response_language]
  A -->|solo audio| T[POST /v1/audio/transcriptions] --> P
  P --> R[risk score, detections, verdict, summary, usage]
  R --> V1[Reporte HTML auditable]
  R --> V2[Auditoria 100% de las conversaciones]
  R --> V3[Evidencia para juridico / disputa]
  R --> V4[Plan de accion por equipo]
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class A,T in
  class P api
  class R,V1,V2,V3,V4 out

Flujos posibles

• Auditoria puntual: una conversacion → score + violaciones + reporte.
• Auditoria en lote (100%): todas las conversaciones del dia/semana → ranking por riesgo.
• Auditoria + diagnostico para contexto (motivo/accion) junto al riesgo.
• Reverificacion despues de entrenamiento (compara score antes/despues).

POST /v1/whatsapp/extractConversations multipart/form-data

Para que sirve: extraer y segmentar conversaciones de un export de WhatsApp (.zip/.txt) para luego diagnosticar o auditar.

Campos

Solicitud (ejemplo cURL, por variante)

Preview (gratis)

cargando...

Ventana unica (extraccion)

cargando...

Varias ventanas (extraccion)

cargando...

Respuesta — campos

Ejemplo de respuesta (JSON, por variante)

Preview (gratis)

cargando...

Ventana unica (extraccion)

cargando...

Varias ventanas (extraccion)

cargando...

Flujo (con las 3 variantes)

flowchart TD
  U[Export de WhatsApp: .zip o .txt] --> V{Elegir la variante}
  V -->|preview gratis| P1[dry_run=true: devuelve ROTULOS y previas - no extrae la conversacion]
  V -->|ventana unica| P2[start + end definen 1 ventana]
  V -->|varias ventanas| P3[windows = JSON con varias ventanas]
  P2 --> C[conversations: dialog, participantes, mensajes, duracion]
  P3 --> C
  C --> J[Usar como transcripcion JSON en el Playground]
  C --> D[POST /v1/analyze/diagnostic]
  C --> A[POST /v1/analyze/riskAudit]
  P1 --> L[Conferir volumen/rotulos antes de gastar creditos]
  L --> V
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef prev fill:#fef9c3,stroke:#ca8a04,color:#713f12
  classDef out fill:#f3e8ff,stroke:#7c3aed,color:#4c1d95
  class U,V in
  class P1,P2,P3 api
  class L prev
  class C,J,D,A out

Flujos posibles

• Conferir antes (gratis): ejecutar dry_run=true para ver cuantas conversaciones/rotulos existen y la estimacion de creditos.
• Extraer la conversacion completa (start+end) → diagnosticar/auditar.
• Extraer varias ventanas (windows) → diagnosticar/auditar en lote.
• Atencion por WhatsApp → conversa extraida → auditoria de risco (compliance).

Flujos combinados (arbol de decision)

flowchart TD
  S([Que tienes en mano?]) --> A{Audio?}
  A -->|si| T[Transcripcion] --> Q{Que quieres saber?}
  A -->|no, tengo texto| Q
  A -->|no, tengo el export de WhatsApp| W[Extract WhatsApp] --> Q
  Q -->|resumen/motivo/accion/sentimiento| D[Diagnostic]
  Q -->|riesgo/compliance/reporte| R[Risk Audit]
  Q -->|los dos| D2[Diagnostic + Risk Audit]
  D --> FIM([JSON tipado para tu sistema])
  R --> FIM
  D2 --> FIM
  classDef in fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
  classDef api fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
  classDef out fill:#dcfce7,stroke:#16a34a,color:#14532d
  class S,W in
  class T,D,R,D2 api
  class Q,FIM out

Recetas listas

Webhooks de alertas

Para que sirve: recibir avisos de suscripcion/cobro/creditos en un endpoint HTTPS tuyo, sin consultar la API.

Endpoints

Eventos (10)

• subscription.created · avulso.completed · subscription.upgraded · subscription.downgraded · subscription.canceled
• credits.low · credits.exhausted · subscription.renewed · subscription.expired · payment.failed

Payload (ejemplo)

{
  "event": "credits.low",
  "data": { "balance_monthly": 12, "balance_avulso": 0, "total": 12, "plan": "starter_api", "plan_name": "Starter API - 90K" },
  "timestamp": 1725470000.123
}

Entrega y seguridad

• Firma: todo disparo trae el header FalaAI-Signature: t=<unix>,v0=<hmac_sha256(secret, "<t>.<cuerpo crudo>")>. Valida recalculando el HMAC con tu secret y comparalo con v0; rechaza si t esta fuera de la ventana de tolerancia (anti-replay).
• Retry: retry_enabled=false = 1 intento; true = hasta 5 (backoff 2^attempt: 1s, 2s, 4s, 8s). Timeout HTTP de 10s por disparo; respuesta < 500 cuenta como entregada; tras 5 fallos consecutivos la suscripcion se auto-desactiva (active=false).

Errores

Limites y errores comunes

• 401: clave ausente/invalida (Authorization: Bearer fai_...).
• 402 / creditos: saldo insuficiente para la operacion.
• 413 / limite: archivo por encima de 1 GB (o audio por encima de 3 h).
• 422: campo obligatorio ausente o formato invalido (ej.: auditoria sin dialog; WhatsApp sin timezone/date_format).
• Publico sin clave: solo GET/HEAD /v1/health y GET /api/version.

Contrato completo: Swagger · openapi.json · Quickstart · Playground