Audio-to-JSON
Audio data extraction to JSON
Endpoint
https://claix.dev/api/audio-jsonThis endpoint accepts an audio file and returns a single JSON object with the data extracted from what was said, following exactly the structure you define via a schema. Analysis is performed by a multimodal AI model with native audio understanding — ideal for calls, meetings, voice notes, interviews, dictations, or spoken messages.
It is intended for server-to-server integrations (backends, scripts, n8n/Zapier/Make). It must not be called from an end-user browser because it requires a secret API key.
Same as Img-to-JSON, the whole audio is treated as a single data source and the response always contains exactly one record in data. If the schema has the context window enabled, the transcription is persisted as Markdown in markdown_content. If source verification is enabled, each field cites the second or second range where the value is spoken.
1. Authentication
Every request must include your API key. It is a personal server credential and must be treated with the same care as a database password.
Option A — Dedicated header (recommended):
x-api-key: <YOUR_API_KEY>
Option B — Standard Authorization header:
Authorization: Bearer <YOUR_API_KEY>
Either one is enough. If you send both, x-api-key takes priority.
Before processing the audio, the system checks that:
- The API key exists and is active.
- The associated account is active (not suspended).
If that fails, the request is rejected with 401 without processing the file.
2. Request format
Method: POST · Content-Type: multipart/form-data (required)
| Field | Type | Required | Description |
|---|---|---|---|
| file | Binary file | Yes | The audio to analyze. Must be the file itself, not a path or URL. |
| schema_id | Text (UUID) | Yes | Schema previously created in your account, of type Audio → JSON. |
| space_id | Text (UUID) | No | Optional. Knowledge space the persisted document is attached to. Must belong to the same account as the API key. Only takes effect if the schema has the context window enabled, which is when the document is saved. You can then query the whole space with POST /space-context/{space_id}. |
The audio field can be sent as file (recommended) or, if needed, as audio, voice, or upload. schema_id is required.
The schema_id must belong to an Audio → JSON schema. If you send an Img → JSON schema or another type, you get 400.
File requirements:
- Accepted formats: .mp3, .wav, .m4a, and .ogg (validated by MIME, extension, and binary signature).
- Must not be empty (0 bytes).
- Maximum size: 12 MB (HTTP 413 if exceeded).
- Maximum duration: 10 minutes (HTTP 413 if exceeded), so the model and Edge Function timeout stay within safe bounds.
- The audio must be intelligible: silence, noise, music without speech, or distortion is rejected with 422 before returning data.
3. How to build the call
- Have your API key and the correct schema_id ready.
- Build a POST to the endpoint URL.
- Add the authentication header.
- Send
multipart/form-datawithfile(audio) andschema_id. - Check the HTTP status: only 200 means success.
4. Request examples
See the right-hand panel for examples in cURL, JavaScript, Node.js, Python, PHP, and n8n.
5. Successful response format
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"
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true when HTTP is 200. |
| schema_utilizado | string | Name of the applied schema (not the id). |
| total_registros | number | Always 1: one audio file = one extracted record. |
| data | array | Contains exactly one object with the schema properties. Missing values are null. If source verification is enabled on the schema, each property is { value, source } and source cites the second or second range (e.g. "second 72" or "seconds 220-235"). |
| log_id | string (UUID) | UUID of this call’s usage_logs row. Present on success and on most authenticated errors. |
Every response includes log_id (the UUID of the usage_logs row) when the log could be stored. It also appears on most errors after the request is authenticated. Use it to find the call in the logs panel.
If source verification is enabled on the schema, each extracted property (and each agent_data field in Agent mode) becomes { "value": ..., "source": "..." } instead of a bare value. source is required: it cites the evidence (page, paragraph, cell, quoted snippet, image region, or the second / second range in audio). If there is no evidence, source is exactly requires_human_revision. If source verification is off, the format is unchanged.
Example with source verification enabled:
{
"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. Error codes
{
"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 — Missing file or schema_id, invalid multipart, unsupported format, empty or corrupt file, inconsistent binary signature, or wrong schema type.
401 — Authentication failed.
404 — schema_id does not exist or does not belong to your account.
413 — Audio exceeds 12 MB or 10 minutes duration.
422 — Unintelligible audio (silence, noise, music without speech) or no extractable data for the schema.
502 — AI service failure (transient).
405 — Method other than POST. · 500 — Internal error.
7. Status code summary
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed audio or data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 413 | Audio too large or too long | No — reduce size or duration first |
| 422 | Unintelligible audio or no extractable data | No — review audio/schema first |
| 500 | Internal server error | Yes, with caution |
| 502 | AI service failure | Yes, recommended with backoff |
8. Best practices
- Validate the HTTP status before reading data[0].
- Check audio size and duration on the client before sending.
- Remember: data always has exactly one item (one audio file = one object).
- Auto-retry only on 500 and 502, never on 400, 401, 404, 413, or 422.
- If you get 422 for quality, ask the user for a cleaner clip before retrying.
- Clear property descriptions in the schema improve accuracy on unstructured calls.
- Do not include your API key in frontend code or public repositories.