Documentação da API do Mixanalytic
Referência oficial da API de https://mixanalytic.com. Use esta API para enviar áudio e receber análises de mixagem com IA, com módulos selecionáveis e respostas compactas ou completas.
URL base: https://mixanalytic.com/api
Autenticação
Envie sua chave de API no cabeçalho X-API-Key em todas as solicitações.
- 401 chave ausente ou inválida
- 403 chave de plano gratuito sem acesso à API
- 429 limite de solicitações excedido
Escopos: write serve para envio e análise no Mixanalytic. content lê dados de pesquisa de conteúdo com dados sensíveis ocultados. content_write salva rascunhos de conteúdo não públicos. Os escopos de conteúdo são exclusivos de administradores.
Endpoints
| Método | Caminho | Finalidade |
|---|---|---|
| GET | /api/test-data | Verificação de conectividade e autenticação. |
| POST | /api/upload | Enviar e analisar arquivo de áudio. |
| GET | /api/analyze/<file_id> | Analisar novamente pelo ID do arquivo (se o arquivo original ainda existir). |
| POST | /api/mastering | Envie uma mixagem e inicie uma masterização (quatro masters). |
| GET | /api/mastering/<token> | Status e resultados de uma masterização. |
| GET | /api/mastering/<token>/<variant>.wav | Baixe um master como WAV de 24 bits. |
| GET | /api/content/analysis-feed | Feed de pesquisa com dados sensíveis ocultados para agentes de conteúdo, exclusivo de administradores. |
| POST | /api/content/drafts | Endpoint para salvar ou atualizar rascunhos para agentes de conteúdo, exclusivo de administradores. |
| GET | /api/ai-stats?days=30 | Estatísticas de uso da análise de IA. |
Solicitação de envio
POST/api/upload
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
| file | multipart file | Sim | Permitidos: mp3, wav, flac, m4a, aac, ogg. Máx. 95MB. |
| modules | string/list | Não | Se omitido, todos os módulos são usados por padrão. |
| detail_level | string | Não | full (padrão) ou summary. |
Um valor inválido de detail_level retorna 400. Arquivos grandes demais retornam 413.
Seleção de módulos
Controle quais módulos de análise são retornados (e calculados) com modules.
Formatos aceitos:
- String separada por vírgulas: modules=frequency_balance,clarity,mood
- String de array JSON: modules=["frequency_balance","clarity","mood"]
- Chave repetida (consulta/formulário): modules=frequency_balance&modules=clarity
- Todos os módulos: modules=all ou modules=*
| Módulo | Descrição |
|---|---|
| frequency_balance | Pontuação de frequência e equilíbrio em 7 bandas. |
| dynamic_range | Faixa dinâmica, fator de crista, PLR. |
| stereo_field | Métricas de largura, fase e correlação. |
| clarity | Métricas de clareza e definição espectral. |
| harmonic_content | Tonalidade e complexidade harmônica. |
| transients | Dados de ataque, densidade de transientes e impacto dos graves. |
| 3d_spatial | Consistência de altura, profundidade e largura. |
| surround_compatibility | Compatibilidade mono e pontuação de fase. |
| headphone_optimization | Pontuação de otimização da reprodução com fones de ouvido. |
| speaker_optimization | Pontuação de otimização da reprodução com alto-falantes. |
| genre | Classificação de gênero e confiança. |
| voice | Presença vocal e características da voz. |
| instruments | Detecção de instrumentos e informações do arranjo. |
| mood | Perfil de humor com energia e valência. |
| keywords | Palavras-chave e tags semânticas. |
| loudness | Meça LUFS, true peak, clipping e metas de streaming para manter o master alto o bastante sem distorção, picos do codec ou surpresas nas plataformas. |
| noise | Meça ruído de fundo, zumbido de rede, chiado e artefatos para limpar gravações antes de ficarem mais altos, brilhantes e difíceis de esconder na masterização. |
| format_quality | Confira codificação com perdas, corte espectral e profundidade de bits antes de masterizar MP3, AAC ou fontes degradadas. |
| reference | Referência |
| visualizations | URLs dos recursos visuais gerados para a análise. |
| ai_insights | Resumo e recomendações gerados por LLM. |
Controle do tamanho da resposta
Use detail_level:
- full (padrão): resposta completa
- summary: resposta compacta para clientes web e móveis
Exemplos
1) Envio e análise completa
2) Envio e módulos selecionados
3) Envio, módulos selecionados e resposta resumida
4) Endpoint de teste
5) JavaScript do lado do cliente
Metadados padrão da resposta
As respostas de análise bem-sucedidas incluem:
- requested_modules
- returned_modules
- detail_level
- available_modules
Masterização
Envie uma mixagem finalizada e receba quatro masters WAV de 24 bits em uma única masterização: dynamic, balanced, loud, chart. A API usa o mesmo motor, o mesmo preço e a mesma cota mensal do Mastering Studio.
- A masterização é exclusiva do Supporter: 20 masterizações por mês (UTC) estão incluídas; depois, cada masterização usa tokens.
- Uma masterização gera os quatro masters. Depois das masterizações incluídas, uma masterização custa 85 tokens. Se uma masterização falhar, os tokens ou a masterização incluída são devolvidos.
- Cada conta faz uma masterização por vez, e esse limite é compartilhado com o Mastering Studio.
- Os masters são excluídos 24 horas depois que a masterização termina, ou após 30 dias em uma conta Supporter, a menos que a masterização seja guardada em Meus masters. Baixe-os antes do horário em expires_at na resposta de status.
- Iniciar uma masterização exige o escopo write. Status e downloads exigem read.
Solicitação de masterização
POST/api/mastering
Envie a mixagem como multipart/form-data. Só file é obrigatório.
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
| file | multipart file | Sim | Permitidos: mp3, wav, flac, aiff, m4a, aac, ogg. Máx. 95 MB e 12 minutos. O conteúdo do arquivo deve corresponder à extensão. |
| tone | number | Não | Inclinação tonal em torno de 1 kHz, em dB. Negativo deixa mais quente; positivo, mais brilhante. De -2 a 2, em passos de 0.5. Padrão: 0. |
| width | number | Não | Nível das laterais acima de 120 Hz, em dB. Negativo deixa mais estreito; positivo, mais aberto. O grave fica no centro. De -3 a 2, em passos de 0.5. Padrão: 0. |
| punch | number | Não | Compressão de cola como múltiplo do valor medido na mixagem. 0 desliga a cola. De 0 a 1.5, em passos de 0.25. Padrão: 1. |
| loudness | number | Não | Move os quatro alvos de loudness juntos, em LU. Se mais volume for esmagar a bateria, o master para antes e avisa isso na lista de mudanças. De -3 a 1.5, em passos de 0.5. Padrão: 0. |
| mono | string | Não | Deixa os graves em mono abaixo de 120 Hz. auto aplica o ajuste só quando a medição da mixagem mostra necessidade. Um destes: auto, on, off. Padrão: auto. |
| deharsh | string | Não | Abaixa 4–9 kHz só nos momentos em que eles se destacam. auto aplica o ajuste só quando a medição da mixagem mostra necessidade. Um destes: auto, on, off. Padrão: auto. |
| source | string | Não | Define o alvo de agudos. ai nunca mexe na banda de ar acima de 10 kHz e mira agudos mais contidos. recorded mira agudos mais brilhantes. auto usa o veredito de música por IA do relatório de song_id ou verifica o próprio envio. Um destes: auto, ai, recorded. Padrão: auto. |
| style | string | Não | Define o peso dos graves e qual master é recomendado. auto usa o gênero do relatório de song_id. Sem song_id, nenhum gênero é aplicado: os graves ficam neutros e a recomendação segue a faixa de loudness, então envie um estilo para escolher um. Um destes: auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Padrão: auto. |
| song_id | integer | Não | O id de uma música que você analisou. O relatório salvo dela é reutilizado em vez de medir o envio. Envie a mesma mixagem. |
| Idempotency-Key | header | Não | 1–64 caracteres: letras, dígitos, _ e -. |
Números fora do intervalo são limitados a ele e arredondados para o passo. Um valor que não é número, ou uma opção desconhecida, retorna 400 com invalid_settings.
Envie um cabeçalho Idempotency-Key para repetir a solicitação com segurança, com uma chave nova para cada mix. Se sua conta repetir uma chave enquanto a masterização dela ainda existir, nada é cobrado nem iniciado de novo: você recebe 200 com o corpo original mais "replayed": true. Se a repetição chegar enquanto a primeira solicitação ainda está iniciando, você recebe 429 busy. Depois de 503 failed, tente de novo com uma chave nova.
Resposta ao iniciar
Uma nova masterização retorna 202:
Uma masterização da cota do Supporter tem "billed": "included" e "charged": 0. Contas Supporter também recebem um objeto included com used, cap, reset_date.
Status e downloads da masterização
GET/api/mastering/<token>
Consulte a cada 3–5 segundos, dentro do limite de solicitações da sua chave, até o status ser done ou error.
- pending: os masters estão sendo criados.
- settling: a masterização falhou e os tokens ou a masterização incluída estão sendo devolvidos. Continue consultando.
- done: os quatro masters estão prontos.
- error: a masterização falhou e o que foi cobrado já foi devolvido. O campo error informa o motivo: too_long, too_short, too_quiet, failed.
Uma resposta concluída contém recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Cada item de masters tem key, url, target_lufs, ceiling, metrics, changes, peaks.
As respostas concluídas e com erro também incluem access: seu saldo e suas masterizações incluídas depois desta masterização.
Tokens de masterização desconhecidos, expirados ou de outras contas retornam 404 com {"status": "expired"}.
Download
GET/api/mastering/<token>/<variant>.wav
Retorna o master como anexo WAV de 24 bits com o nome do arquivo enviado, por exemplo My Mix - balanced.wav. variant é um destes: dynamic, balanced, loud, chart.
Uma variante desconhecida, o token de masterização de outra conta ou uma masterização expirada ou ainda não concluída retorna 404.
Toda resposta de masterização inclui Cache-Control: private, no-store.
Erros de masterização
Os erros retornam {"error": "invalid_file", "message": "…"}.
| Status | Erro | Significado |
|---|---|---|
| 400 | invalid_file | Arquivo ausente, formato não suportado ou conteúdo que não corresponde à extensão. |
| 400 | invalid_settings | Um ajuste não é um número ou não é uma das opções permitidas. |
| 400 | invalid_idempotency_key | O cabeçalho Idempotency-Key não tem de 1 a 64 letras, dígitos, _ ou -. |
| 402 | insufficient_credits | Tokens insuficientes. O corpo da resposta inclui cost e balance. |
| 403 | Forbidden | Chave de uma conta gratuita, ou uma chave sem o escopo que este endpoint exige. Um Supporter cujo pagamento de renovação falhou fica no plano gratuito até o pagamento ser aprovado, então, enquanto isso, a masterização só funciona no Mastering Studio. Nada é cobrado. |
| 403 | supporter_only | Por enquanto, a masterização está disponível só para contas Supporter. Nada é cobrado. |
| 413 | File too large | O arquivo tem mais de 95 MB, então a solicitação é recusada antes de chegar ao endpoint, às vezes sem corpo JSON. Um arquivo só um pouco acima do limite recebe invalid_file no lugar. |
| 429 | busy | Já há uma masterização em andamento ou iniciando nesta conta, pela API ou pelo estúdio. O corpo da resposta inclui o token dela, que é null enquanto essa masterização ainda está iniciando. |
| 429 | Rate Limit Exceeded | O limite por minuto, por hora ou por dia da sua chave foi atingido. A mensagem diz qual. |
| 503 | failed | Não foi possível iniciar a masterização. Tudo o que foi cobrado por ela é devolvido. |
Exemplo de masterização
1) Iniciar uma masterização
2) Consultar até concluir
3) Baixar um master
Códigos de erro
| Status | Significado | Causa típica |
|---|---|---|
| 400 | Solicitação inválida | Módulo/detail_level inválido, campo de arquivo ausente ou arquivo vazio. |
| 401 | Não autorizado | Chave de API ausente, inválida ou expirada. |
| 403 | Proibido | O nível da conta não permite acesso à API. |
| 404 | Não encontrado | /api/analyze/<file_id> arquivo não está mais disponível (exclusão por privacidade). |
| 413 | Conteúdo grande demais | Arquivo maior que 95MB. |
| 429 | Limite de solicitações excedido | Solicitações demais por minuto, hora ou dia. |
| 500 | Erro do servidor | Falha de análise ou de execução. |
Notas para o frontend
- Para clientes web e móveis, prefira detail_level=summary.
- Solicite apenas os módulos necessários para a primeira renderização para reduzir a latência e o tamanho da resposta.
- Trate 429 e 500 com novas tentativas e intervalos de espera crescentes.
- Não exponha chaves de produção de longa duração em pacotes públicos.