Producción

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 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-dataComprobación de conectividad y autenticación.
POST/api/uploadSubir 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/masteringSube 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>.wavDescarga un master como WAV de 24 bits.
GET/api/content/analysis-feedFeed de investigación con datos sensibles ocultos para agentes de contenido, exclusivo de administradores.
POST/api/content/draftsEndpoint para guardar o actualizar borradores para agentes de contenido, exclusivo de administradores.
GET/api/ai-stats?days=30Estadísticas de uso del análisis de IA.

Solicitud de subida

POST/api/upload

Campo Tipo Obligatorio Notas
filemultipart fileSíPermitidos: mp3, wav, flac, m4a, aac, ogg. Máx. 95MB.
modulesstring/listNoSi se omite, se usan todos los módulos por defecto.
detail_levelstringNofull (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_balancePuntuación de frecuencias y equilibrio en 7 bandas.
dynamic_rangeRango dinámico, factor de cresta, PLR.
stereo_fieldMétricas de anchura, fase y correlación.
clarityMétricas de claridad y definición espectral.
harmonic_contentTonalidad y complejidad armónica.
transientsDatos de ataque, densidad de transitorios y pegada en graves.
3d_spatialConsistencia de altura, profundidad y anchura.
surround_compatibilityCompatibilidad mono y puntuación de fase.
headphone_optimizationPuntuación de optimización de reproducción con auriculares.
speaker_optimizationPuntuación de optimización de reproducción con altavoces.
genreClasificación de género y nivel de confianza.
voicePresencia vocal y características de la voz.
instrumentsDetección de instrumentos e información del arreglo.
moodPerfil de estado de ánimo con energía y valencia.
keywordsPalabras clave y etiquetas semánticas.
loudnessMide 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.
noiseMide 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_qualityRevisa 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.
referenceReferencia
visualizationsURL de los recursos visuales generados para el análisis.
ai_insightsResumen 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

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3"

2) Subida y módulos seleccionados

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,dynamic_range,genre,mood,keywords"

3) Subida, módulos seleccionados y respuesta resumida

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,stereo_field,clarity,ai_insights" \ -F "detail_level=summary"

4) Endpoint de prueba

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"

5) JavaScript del lado del cliente

const formData = new FormData(); formData.append('file', fileInput.files[0]); formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights'); formData.append('detail_level', 'summary'); const res = await fetch('https://mixanalytic.com/api/upload', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: formData }); const data = await res.json(); console.log(data.analysis, data.returned_modules);

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
filemultipart fileSí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.
tonenumberNoInclinació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.
widthnumberNoNivel 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.
punchnumberNoCompresió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.
loudnessnumberNoMueve 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.
monostringNoPone 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.
deharshstringNoBaja 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.
sourcestringNoDefine 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.
stylestringNoDefine 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_idintegerNoEl 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-KeyheaderNoDe 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:

{ "token": "3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "status": "pending", "status_url": "/api/mastering/3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "billed": "tokens", "charged": 85, "balance": 415, "expires_in_hours": 720 }

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
400invalid_fileFalta el archivo, el formato no es compatible o el contenido no coincide con la extensión.
400invalid_settingsUn ajuste no es un número o no es una de sus opciones.
400invalid_idempotency_keyLa cabecera Idempotency-Key no está formada por 1–64 letras, dígitos, _ o -.
402insufficient_creditsNo hay suficientes tokens. El cuerpo incluye cost y balance.
403ForbiddenLa 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.
403supporter_onlyPor ahora, el mastering solo está disponible para cuentas Supporter. No se cobra nada.
413File too largeEl 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.
429busyYa 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.
429Rate Limit ExceededSe alcanzó el límite por minuto, por hora o por día de tu clave. El mensaje indica cuál.
503failedNo se pudo iniciar la masterización. Se devuelve todo lo que se haya cobrado por ella.

Ejemplo de mastering

1) Iniciar una masterización

curl -X POST "https://mixanalytic.com/api/mastering" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_MIX" \ -F "file=@/path/to/mix.wav" \ -F "style=electronic" \ -F "loudness=0.5"

2) Consultar hasta que termine

curl "https://mixanalytic.com/api/mastering/TOKEN" \ -H "X-API-Key: YOUR_API_KEY"

3) Descargar un master

curl -o "mix - balanced.wav" "https://mixanalytic.com/api/mastering/TOKEN/balanced.wav" \ -H "X-API-Key: YOUR_API_KEY"

Códigos de error

Estado Significado Causa habitual
400Solicitud incorrectaMódulo/detail_level no válido, campo de archivo ausente o archivo vacío.
401No autorizadoClave de API ausente, no válida o caducada.
403ProhibidoEl nivel de cuenta no permite el acceso a la API.
404No encontrado/api/analyze/<file_id> archivo ya no disponible (eliminación por privacidad).
413Contenido demasiado grandeArchivo de más de 95MB.
429Límite de solicitudes superadoDemasiadas solicitudes por minuto, hora o día.
500Error del servidorFallo 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.