Documentación de la API de Mixanalytic
Referencia oficial de la API de https://mixanalytic.com. Usa esta API para subir audio y recibir análisis de mezcla con IA, con módulos seleccionables y respuestas compactas o completas.
URL base: https://mixanalytic.com/api
Autenticación
Envía tu clave de API en la cabecera X-API-Key en cada solicitud.
- 401 clave ausente o no válida
- 403 clave de plan gratuito sin acceso a la API
- 429 límite de solicitudes superado
Ámbitos: write permite subir y analizar en Mixanalytic. content lee datos de investigación de contenido con datos sensibles ocultos. content_write guarda borradores de contenido no públicos. Los ámbitos de contenido son exclusivos de administradores.
Endpoints
| Método | Ruta | Propósito |
|---|---|---|
| GET | /api/test-data | Comprobación de conectividad y autenticación. |
| POST | /api/upload | Subir y analizar un archivo de audio. |
| GET | /api/analyze/<file_id> | Volver a analizar mediante el ID de archivo (si el archivo original aún existe). |
| POST | /api/mastering | Sube una mezcla e inicia una masterización (cuatro masters). |
| GET | /api/mastering/<token> | Estado y resultados de una masterización. |
| GET | /api/mastering/<token>/<variant>.wav | Descarga un master como WAV de 24 bits. |
| GET | /api/content/analysis-feed | Feed de investigación con datos sensibles ocultos para agentes de contenido, exclusivo de administradores. |
| POST | /api/content/drafts | Endpoint para guardar o actualizar borradores para agentes de contenido, exclusivo de administradores. |
| GET | /api/ai-stats?days=30 | Estadísticas de uso del análisis de IA. |
Solicitud de subida
POST/api/upload
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
| file | multipart file | Sí | Permitidos: mp3, wav, flac, m4a, aac, ogg. Máx. 95MB. |
| modules | string/list | No | Si se omite, se usan todos los módulos por defecto. |
| detail_level | string | No | full (por defecto) o summary. |
Un valor de detail_level no válido devuelve 400. Los archivos demasiado grandes devuelven 413.
Selección de módulos
Controla qué módulos de análisis se devuelven (y se calculan) con modules.
Formatos admitidos:
- Cadena separada por comas: modules=frequency_balance,clarity,mood
- Cadena de array JSON: modules=["frequency_balance","clarity","mood"]
- Clave repetida (consulta/formulario): modules=frequency_balance&modules=clarity
- Todos los módulos: modules=all o modules=*
| Módulo | Descripción |
|---|---|
| frequency_balance | Puntuación de frecuencias y equilibrio en 7 bandas. |
| dynamic_range | Rango dinámico, factor de cresta, PLR. |
| stereo_field | Métricas de anchura, fase y correlación. |
| clarity | Métricas de claridad y definición espectral. |
| harmonic_content | Tonalidad y complejidad armónica. |
| transients | Datos de ataque, densidad de transitorios y pegada en graves. |
| 3d_spatial | Consistencia de altura, profundidad y anchura. |
| surround_compatibility | Compatibilidad mono y puntuación de fase. |
| headphone_optimization | Puntuación de optimización de reproducción con auriculares. |
| speaker_optimization | Puntuación de optimización de reproducción con altavoces. |
| genre | Clasificación de género y nivel de confianza. |
| voice | Presencia vocal y características de la voz. |
| instruments | Detección de instrumentos e información del arreglo. |
| mood | Perfil de estado de ánimo con energía y valencia. |
| keywords | Palabras clave y etiquetas semánticas. |
| loudness | Mide LUFS, pico real, clipping y objetivos de streaming para que el máster tenga suficiente nivel sin distorsión, picos del códec ni sorpresas en plataformas. |
| noise | Mide ruido de fondo, zumbido de red, siseo y artefactos para limpiar audio antes de que el mastering los haga más fuertes, brillantes y difíciles de ocultar. |
| format_quality | Revisa codificación con pérdida, corte espectral y profundidad de bits para no masterizar audio MP3, AAC o ampliado y degradado por error antes de publicar. |
| reference | Referencia |
| visualizations | URL de los recursos visuales generados para el análisis. |
| ai_insights | Resumen y recomendaciones generados por LLM. |
Control del tamaño de respuesta
Usa detail_level:
- full (por defecto): respuesta completa
- summary: respuesta compacta para clientes web y móviles
Ejemplos
1) Subida y análisis completo
2) Subida y módulos seleccionados
3) Subida, módulos seleccionados y respuesta resumida
4) Endpoint de prueba
5) JavaScript del lado del cliente
Metadatos estándar de respuesta
Las respuestas de análisis correctas incluyen:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Sube una mezcla terminada y recibe cuatro masters WAV de 24 bits en una sola masterización: dynamic, balanced, loud, chart. La API usa el mismo motor, el mismo precio y la misma cuota mensual que el Estudio de mastering.
- El mastering es solo para Supporter: se incluyen 20 masterizaciones por mes UTC y después cada masterización usa tokens.
- Una masterización crea los cuatro masters. Después de las masterizaciones incluidas, cada una cuesta 85 tokens. Si una masterización falla, recuperas sus tokens o la masterización incluida.
- Cada cuenta puede tener una sola masterización en curso a la vez, contando también el Estudio de mastering.
- Los masters se eliminan 24 horas después de que termine la masterización, o a los 30 días en una cuenta Supporter, salvo que la masterización se conserve en Mis masters. Descárgalos antes de la hora indicada en expires_at de la respuesta de estado.
- Iniciar una masterización requiere el ámbito write. El estado y las descargas requieren read.
Solicitud de mastering
POST/api/mastering
Envía la mezcla como multipart/form-data. Solo file es obligatorio.
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
| file | multipart file | Sí | Permitidos: mp3, wav, flac, aiff, m4a, aac, ogg. Máximo 95 MB y 12 minutos. El contenido del archivo debe coincidir con la extensión. |
| tone | number | No | Inclinación tonal alrededor de 1 kHz, en dB. Los valores negativos dan un sonido más cálido; los positivos, más brillante. De -2 a 2 en pasos de 0.5. Por defecto 0. |
| width | number | No | Nivel de los laterales por encima de 120 Hz, en dB. Los valores negativos estrechan la imagen; los positivos la ensanchan. Los graves se quedan en el centro. De -3 a 2 en pasos de 0.5. Por defecto 0. |
| punch | number | No | Compresión de pegamento como múltiplo de la cantidad medida en la mezcla. 0 desactiva el pegamento. De 0 a 1.5 en pasos de 0.25. Por defecto 1. |
| loudness | number | No | Mueve los cuatro objetivos de sonoridad a la vez, en LU. Si subir más aplastara la batería, el master se detiene antes y lo indica en sus cambios. De -3 a 1.5 en pasos de 0.5. Por defecto 0. |
| mono | string | No | Pone los graves en mono por debajo de 120 Hz. auto solo lo aplica cuando la medición de la mezcla lo pide. Uno de auto, on, off. Por defecto auto. |
| deharsh | string | No | Baja los 4–9 kHz solo en los momentos en que sobresalen. auto solo lo aplica cuando la medición de la mezcla lo pide. Uno de auto, on, off. Por defecto auto. |
| source | string | No | Define el objetivo de agudos. ai nunca toca la banda de aire por encima de 10 kHz y apunta a unos agudos más contenidos. recorded busca una zona alta más brillante. auto usa la detección de música con IA del informe de song_id o comprueba el propio archivo subido. Uno de auto, ai, recorded. Por defecto auto. |
| style | string | No | Define el peso de los graves y qué master se recomienda. auto usa el género del informe de song_id. Sin song_id no se aplica ningún género: los graves quedan neutros y la recomendación depende del rango de sonoridad, así que envía un estilo para elegir uno. Uno de auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Por defecto auto. |
| song_id | integer | No | El id de una canción que hayas analizado. Se reutiliza su informe guardado en lugar de medir el archivo subido. Sube la misma mezcla. |
| Idempotency-Key | header | No | De 1 a 64 caracteres: letras, dígitos, _ y -. |
Los números fuera de rango se ajustan al límite y se redondean a su paso. Un valor que no es un número, o una opción desconocida, devuelve 400 con invalid_settings.
Envía una cabecera Idempotency-Key para reintentar de forma segura, con una clave nueva para cada mezcla. Si tu cuenta repite una clave mientras su masterización aún existe, no se vuelve a cobrar ni a iniciar nada: recibes 200 con el cuerpo original más "replayed": true. Si la repetición llega mientras la primera solicitud aún se está iniciando, recibes 429 busy. Tras 503 failed, reintenta con una clave nueva.
Respuesta de inicio
Una masterización nueva devuelve 202:
Una masterización de la cuota de Supporter lleva "billed": "included" y "charged": 0. Las cuentas Supporter también reciben un objeto included con used, cap, reset_date.
Estado y descargas de mastering
GET/api/mastering/<token>
Consulta el estado cada 3–5 segundos, dentro del límite de solicitudes de tu clave, hasta que sea done o error.
- pending: los masters se están creando.
- settling: la masterización falló y se están devolviendo sus tokens o la masterización incluida. Sigue consultando.
- done: los cuatro masters están listos.
- error: la masterización falló y se ha devuelto lo que se cobró. El campo error indica el motivo: too_long, too_short, too_quiet, failed.
Una respuesta de una masterización terminada contiene recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Cada elemento de masters tiene key, url, target_lufs, ceiling, metrics, changes, peaks.
Las respuestas terminadas y con error también incluyen access: tu saldo y tus masterizaciones incluidas tras esta masterización.
Los tokens de masterización desconocidos o caducados, y los de otras cuentas, devuelven 404 con {"status": "expired"}.
Descarga
GET/api/mastering/<token>/<variant>.wav
Devuelve el master como adjunto WAV de 24 bits con el nombre de tu archivo subido, por ejemplo My Mix - balanced.wav. variant es uno de dynamic, balanced, loud, chart.
Una variante desconocida, el token de otra cuenta o una masterización caducada o sin terminar devuelve 404.
Todas las respuestas de mastering incluyen Cache-Control: private, no-store.
Errores de mastering
Los errores devuelven {"error": "invalid_file", "message": "…"}.
| Estado | Error | Significado |
|---|---|---|
| 400 | invalid_file | Falta el archivo, el formato no es compatible o el contenido no coincide con la extensión. |
| 400 | invalid_settings | Un ajuste no es un número o no es una de sus opciones. |
| 400 | invalid_idempotency_key | La cabecera Idempotency-Key no está formada por 1–64 letras, dígitos, _ o -. |
| 402 | insufficient_credits | No hay suficientes tokens. El cuerpo incluye cost y balance. |
| 403 | Forbidden | La clave de una cuenta gratuita, o una clave sin el ámbito que requiere este endpoint. Un Supporter cuyo pago de renovación ha fallado queda en el plan gratuito hasta que el pago se complete, así que mientras tanto el mastering solo funciona en el Estudio de mastering. No se cobra nada. |
| 403 | supporter_only | Por ahora, el mastering solo está disponible para cuentas Supporter. No se cobra nada. |
| 413 | File too large | El archivo supera los 95 MB, así que la solicitud se rechaza antes de llegar al endpoint, a veces sin cuerpo JSON. Un archivo apenas por encima del límite recibe invalid_file en su lugar. |
| 429 | busy | Ya hay una masterización en curso o iniciándose para esta cuenta, desde la API o el Estudio de mastering. El cuerpo incluye su token, que es null mientras esa masterización aún se está iniciando. |
| 429 | Rate Limit Exceeded | Se alcanzó el límite por minuto, por hora o por día de tu clave. El mensaje indica cuál. |
| 503 | failed | No se pudo iniciar la masterización. Se devuelve todo lo que se haya cobrado por ella. |
Ejemplo de mastering
1) Iniciar una masterización
2) Consultar hasta que termine
3) Descargar un master
Códigos de error
| Estado | Significado | Causa habitual |
|---|---|---|
| 400 | Solicitud incorrecta | Módulo/detail_level no válido, campo de archivo ausente o archivo vacío. |
| 401 | No autorizado | Clave de API ausente, no válida o caducada. |
| 403 | Prohibido | El nivel de cuenta no permite el acceso a la API. |
| 404 | No encontrado | /api/analyze/<file_id> archivo ya no disponible (eliminación por privacidad). |
| 413 | Contenido demasiado grande | Archivo de más de 95MB. |
| 429 | Límite de solicitudes superado | Demasiadas solicitudes por minuto, hora o día. |
| 500 | Error del servidor | Fallo de análisis o de ejecución. |
Notas para el frontend
- Para clientes web y móviles, usa preferentemente detail_level=summary.
- Solicita solo los módulos necesarios para el primer renderizado para reducir la latencia y el tamaño de la respuesta.
- Gestiona 429 y 500 con reintentos e intervalos de espera crecientes.
- No expongas claves de producción de larga duración en paquetes públicos.