Produção

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 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-dataVerificação de conectividade e autenticação.
POST/api/uploadEnviar e analisar arquivo de áudio.
GET/api/analyze/<file_id>Analisar novamente pelo ID do arquivo (se o arquivo original ainda existir).
POST/api/masteringEnvie 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>.wavBaixe um master como WAV de 24 bits.
GET/api/content/analysis-feedFeed de pesquisa com dados sensíveis ocultados para agentes de conteúdo, exclusivo de administradores.
POST/api/content/draftsEndpoint para salvar ou atualizar rascunhos para agentes de conteúdo, exclusivo de administradores.
GET/api/ai-stats?days=30Estatísticas de uso da análise de IA.

Solicitação de envio

POST/api/upload

Campo Tipo Obrigatório Notas
filemultipart fileSimPermitidos: mp3, wav, flac, m4a, aac, ogg. Máx. 95MB.
modulesstring/listNãoSe omitido, todos os módulos são usados por padrão.
detail_levelstringNãofull (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_balancePontuação de frequência e equilíbrio em 7 bandas.
dynamic_rangeFaixa dinâmica, fator de crista, PLR.
stereo_fieldMétricas de largura, fase e correlação.
clarityMétricas de clareza e definição espectral.
harmonic_contentTonalidade e complexidade harmônica.
transientsDados de ataque, densidade de transientes e impacto dos graves.
3d_spatialConsistência de altura, profundidade e largura.
surround_compatibilityCompatibilidade mono e pontuação de fase.
headphone_optimizationPontuação de otimização da reprodução com fones de ouvido.
speaker_optimizationPontuação de otimização da reprodução com alto-falantes.
genreClassificação de gênero e confiança.
voicePresença vocal e características da voz.
instrumentsDetecção de instrumentos e informações do arranjo.
moodPerfil de humor com energia e valência.
keywordsPalavras-chave e tags semânticas.
loudnessMeç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.
noiseMeç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_qualityConfira codificação com perdas, corte espectral e profundidade de bits antes de masterizar MP3, AAC ou fontes degradadas.
referenceReferência
visualizationsURLs dos recursos visuais gerados para a análise.
ai_insightsResumo 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

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

2) Envio e módulos selecionados

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) Envio, módulos selecionados e resposta 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 teste

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

5) JavaScript do lado do 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);

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
filemultipart fileSimPermitidos: mp3, wav, flac, aiff, m4a, aac, ogg. Máx. 95 MB e 12 minutos. O conteúdo do arquivo deve corresponder à extensão.
tonenumberNãoInclinaçã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.
widthnumberNãoNí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.
punchnumberNãoCompressã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.
loudnessnumberNãoMove 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.
monostringNãoDeixa 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.
deharshstringNãoAbaixa 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.
sourcestringNãoDefine 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.
stylestringNãoDefine 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_idintegerNãoO 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-KeyheaderNão1–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:

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

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
400invalid_fileArquivo ausente, formato não suportado ou conteúdo que não corresponde à extensão.
400invalid_settingsUm ajuste não é um número ou não é uma das opções permitidas.
400invalid_idempotency_keyO cabeçalho Idempotency-Key não tem de 1 a 64 letras, dígitos, _ ou -.
402insufficient_creditsTokens insuficientes. O corpo da resposta inclui cost e balance.
403ForbiddenChave 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.
403supporter_onlyPor enquanto, a masterização está disponível só para contas Supporter. Nada é cobrado.
413File too largeO 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.
429busyJá 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.
429Rate Limit ExceededO limite por minuto, por hora ou por dia da sua chave foi atingido. A mensagem diz qual.
503failedNã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

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 até concluir

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

3) Baixar um master

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

Códigos de erro

Status Significado Causa típica
400Solicitação inválidaMódulo/detail_level inválido, campo de arquivo ausente ou arquivo vazio.
401Não autorizadoChave de API ausente, inválida ou expirada.
403ProibidoO nível da conta não permite acesso à API.
404Não encontrado/api/analyze/<file_id> arquivo não está mais disponível (exclusão por privacidade).
413Conteúdo grande demaisArquivo maior que 95MB.
429Limite de solicitações excedidoSolicitações demais por minuto, hora ou dia.
500Erro do servidorFalha 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.