Crear Análisis

Envía una grabación de llamada para transcripción y análisis con IA.

Endpoint

POST /api/v1/analysis/

Autenticación

Requiere clave de API (recomendado) o token JWT.

Método	Header	Ejemplo
Clave de API	X-API-Key: {api_key}	X-API-Key: sk_live_abc123...
Token JWT	Authorization: Bearer {token}	Authorization: Bearer eyJhbGc...

Request

Content-Type

Requerido: multipart/form-data

Este endpoint acepta solo subida de archivos (no JSON). Usa form-data para enviar el archivo de audio.

Parámetros de Form Data

Parámetro	Tipo	Requerido	Descripción
agent_id	string	Sí	Identificador interno del agente en la llamada
contact_id	string	Sí	Identificador interno del cliente/contacto
audio_file	file	Sí	Archivo de audio a analizar (subida multipart)
webhook_url	string	No	URL para recibir notificación cuando el análisis se complete

Formatos de Audio Soportados

Formatos soportados:

• flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm

Límites:

• Tamaño máximo de archivo: 500 MB
• Los archivos se almacenan y procesan de forma segura en la nube

Response

Devuelve un objeto AnalysisResponse con status: "processing".

El análisis se ejecuta de forma asincrónica en segundo plano. Usa webhooks (recomendado) o polling para obtener los resultados cuando se complete.

Response Exitoso (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1705334400,
  "status": "processing",
  "livemode": false,
  "call": {
    "agent_id": "agent_001",
    "contact_id": "customer_12345",
    "duration_ms": 125500,
    "duration_seconds": 125.5
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov-audio/...",
    "size_bytes": 1048576,
    "format": "wav",
    "duration_seconds": 125.5
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "webhook_url": "https://your-app.com/webhooks/analysis",
    "completed_at": null,
    "processing_time_ms": null,
    "error_message": null
  }
}

Campos del Response

Campo	Tipo	Descripción
id	UUID	Identificador único del análisis
object	string	Siempre "analysis"
created	integer	Timestamp Unix de creación
status	string	"processing", "completed", o "failed"
livemode	boolean	Siempre false (modo test no implementado)
call.agent_id	string	Tu identificador del agente
call.contact_id	string	Tu identificador del contacto
call.duration_ms	integer	Duración del audio en milisegundos
audio.url	string	URL S3 donde se almacena el audio
audio.size_bytes	integer	Tamaño del archivo en bytes
audio.format	string	Formato de audio (wav, mp3, etc.)
transcript	object	null hasta que el procesamiento se complete
results	object	null hasta que el procesamiento se complete
metadata.webhook_url	string	Tu URL de webhook (si se proporcionó)

Ejemplos

curl -X POST https://api.callcov.com/api/v1/analysis/ \
-H "X-API-Key: sk_live_abc123..." \
-F "audio_file=@/path/to/call-recording.wav" \
-F "agent_id=agent_001" \
-F "contact_id=customer_12345" \
-F "webhook_url=https://your-app.com/webhooks/analysis"

Errores

400 Bad Request

Formato de audio no soportado:

{
  "detail": "Formato de archivo de audio no soportado. Formatos soportados: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm"
}

401 Unauthorized

Clave de API inválida o faltante:

{
  "detail": "Credenciales de autenticación inválidas"
}

402 Payment Required

Límite de facturación excedido:

{
  "detail": "Límite de uso excedido. Uso actual: 150.5 minutos. Límite del plan: 100 minutos."
}

O límite de sobrecargo alcanzado:

{
  "detail": "Límite de sobrecargo de 50 minutos excedido. Por favor actualiza tu plan o espera al próximo ciclo de facturación."
}

500 Internal Server Error

Fallo en la subida a S3:

{
  "detail": "Fallo al subir archivo de audio"
}

Error inesperado:

{
  "detail": "Ocurrió un error inesperado"
}

Cómo Funciona

1. Subida: El archivo de audio se sube de forma segura al almacenamiento en la nube
2. Cola: La tarea de análisis se pone en cola para procesamiento
3. Transcribir: La IA transcribe el audio con identificación de hablantes
4. Analizar: IA avanzada analiza la transcripción para cumplimiento, calidad e insights de coaching
5. Notificar: Se envía webhook (si se proporcionó) cuando se complete
6. Facturar: Los minutos se rastrean y facturan a tu suscripción

Tiempo de Procesamiento

Tiempos de procesamiento típicos:

• Llamadas cortas (< 5 min): 30-90 segundos
• Llamadas medianas (5-15 min): 1-3 minutos
• Llamadas largas (15-60 min): 3-8 minutos

Usa Webhooks

Usa webhooks en lugar de polling. Serás notificado inmediatamente cuando el análisis se complete.

Facturación

• Cobrado por duración: Duración del audio redondeada hacia arriba al 0.01 minuto más cercano
• Planes: Gratuito (100 min/mes), Starter ($49/mes, 1000 min), Growth ($199/mes, 5000 min)
• Sobrecargo: Cobrado por minuto sobre el límite del plan (si el límite de sobrecargo lo permite)
• Verificación de facturación: La API valida los límites de uso antes de aceptar el análisis

Consulta la Guía de Facturación para detalles completos de precios.

Relacionado

• Obtener Análisis - Obtener análisis por ID
• Listar Análisis - Listar todos los análisis con filtros
• Guía de Webhooks - Notificaciones en tiempo real