Audio-to-JSON
Extracción de datos de audio a JSON
Endpoint
https://claix.dev/api/audio-jsonEste endpoint recibe un archivo de audio y devuelve un único objeto JSON con los datos extraídos de lo hablado, siguiendo exactamente la estructura que definas mediante un schema. El análisis lo realiza un modelo multimodal de IA con comprensión nativa de audio — ideal para llamadas, reuniones, notas de voz, entrevistas, dictados o mensajes.
Está pensado para integraciones server-to-server (backends, scripts, n8n/Zapier/Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.
Igual que en Img-to-JSON, el audio completo se trata como una única fuente de datos y la respuesta contiene exactamente un registro en data. Si el schema tiene la ventana de contexto activada, la transcripción se guarda en Markdown en markdown_content. Si la verificación de fuente está activa, cada campo incluye el segundo o el rango de segundos en el que se menciona el dato.
1. Autenticación
Toda petición debe incluir tu API key. Es una credencial de servidor personal y debe tratarse con el mismo cuidado que una contraseña de base de datos.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.
Antes de procesar el audio, el sistema valida que:
- La API key exista y esté activa.
- La cuenta asociada esté activa (no suspendida).
Si falla, se rechaza con 401 sin procesar el archivo.
2. Formato de la petición
Método: POST · Content-Type: multipart/form-data (obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | El audio a analizar. Debe ser el archivo en sí, no una ruta ni URL. |
| schema_id | Texto (UUID) | Sí | Schema previamente creado en tu cuenta, del tipo Audio → JSON. |
| space_id | Texto (UUID) | No | Opcional. Espacio de conocimiento al que se asocia el documento guardado. Debe pertenecer a la misma cuenta que la API key. Solo tiene efecto si el schema tiene la ventana de contexto activada, que es cuando el documento se guarda. Después puedes preguntar a todo el espacio con POST /space-context/{space_id}. |
El campo del archivo puede enviarse como file (recomendado) o, si hace falta, como audio, voice o upload. El schema_id es obligatorio.
El schema_id debe corresponder a un schema de tipo Audio → JSON. Si envías uno de Img → JSON u otro tipo, recibirás 400.
Requisitos del archivo:
- Formatos admitidos: .mp3, .wav, .m4a y .ogg (validados por MIME, extensión y firma binaria).
- No puede estar vacío (0 bytes).
- Tamaño máximo: 12 MB (error 413 si se supera).
- Duración máxima: 10 minutos (error 413 si se supera), para no saturar el modelo ni el timeout de la Edge Function.
- El audio debe ser inteligible: silencio, ruido, música sin habla o distorsión se rechazan con 422 antes de devolver datos.
3. Cómo construir la llamada
- Ten a mano tu API key y el schema_id del tipo correcto.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfile(audio) yschema_id. - Comprueba el código HTTP: solo 200 indica éxito.
4. Ejemplos de llamada
Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
{
"success": true,
"schema_utilizado": "Notas de llamada",
"total_registros": 1,
"data": [
{
"cliente": "Suministros Industriales del Ebro S.L.",
"numero_factura": "F-2026-00456",
"fecha_emision": "2026-03-14",
"importe_total": 1284.50
}
],
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado (no el id). |
| total_registros | number | Siempre 1: un audio = un registro extraído. |
| data | array | Contiene exactamente un objeto con las propiedades del schema. Valores no encontrados son null. Si la verificación de fuente está activa en el schema, cada propiedad es { value, source } y source cita el segundo o rango de segundos (p. ej. «segundo 72» o «segundos 220-235»). |
| log_id | string (UUID) | Identificador del registro en usage_logs de esta llamada. Presente en éxito y en la mayoría de errores autenticados. |
Toda respuesta incluye log_id (UUID de usage_logs) cuando el registro se ha podido guardar. También aparece en la mayoría de errores una vez autenticada la petición. Úsalo para localizar la llamada en el panel de logs.
Si la verificación de fuente está activada en el schema, cada propiedad extraída (y cada campo de agent_data en modo agente) deja de ser un valor plano y pasa a { "value": ..., "source": "..." }. source es obligatorio: cita la evidencia (página, párrafo, celda, fragmento, zona de la imagen, o el segundo / rango de segundos en audio). Si no hay evidencia, source vale exactamente requires_human_revision. Si la verificación de fuente está desactivada, el formato no cambia.
Ejemplo con verificación de fuente activada:
{
"success": true,
"schema_utilizado": "Notas de voz de facturas",
"total_registros": 1,
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34",
"data": [
{
"numero_factura": {
"value": "F-2026-00456",
"source": "segundo 72, «factura F-2026-00456»"
},
"importe_total": {
"value": 1284.50,
"source": "segundos 220-235, importe total"
},
"moneda": {
"value": null,
"source": "requires_human_revision"
}
}
]
}6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos).",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}400 — Falta file o schema_id, multipart inválido, formato no soportado, archivo vacío, corrupto, firma binaria incoherente o schema de tipo incorrecto.
401 — Autenticación fallida.
404 — schema_id inexistente o no pertenece a tu cuenta.
413 — Audio supera 12 MB o 10 minutos de duración.
422 — Audio ininteligible (silencio, ruido, música sin habla) o sin datos extraíbles según el schema.
502 — Fallo del servicio de IA (transitorio).
405 — Método distinto de POST. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (audio o datos mal formados) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 404 | Recurso no encontrado | No, corrige el schema_id primero |
| 405 | Método HTTP incorrecto | No, corrige el método primero |
| 413 | Audio demasiado grande o demasiado largo | No, reduce el tamaño o la duración primero |
| 422 | Audio ininteligible o sin datos extraíbles | No, revisa el audio/schema primero |
| 500 | Error interno del servidor | Sí, con precaución |
| 502 | Fallo del servicio de IA | Sí, recomendado con backoff |
8. Buenas prácticas
- Valida el código HTTP antes de leer data[0].
- Comprueba el tamaño y la duración del audio en tu cliente antes de enviarlo.
- Recuerda: data siempre tiene exactamente un elemento (un audio = un objeto).
- Reintenta automáticamente solo en 500 y 502, nunca en 400, 401, 404, 413 o 422.
- Si recibes 422 por calidad, pide al usuario un recorte más nítido o sin ruido de fondo antes de reenviar.
- Descripciones claras en las propiedades del schema mejoran la precisión en llamadas poco estructuradas.
- No incluyas tu API key en frontend ni repositorios públicos.