API pública do Magic Chords

Uma API REST versionada para reconhecimento de acordes, transcrição de letras e exportação de partituras. Todos os endpoints ficam sob /api/v1/, aceitam e retornam JSON (exceto uploads e arquivos gerados) e estão abertos a desenvolvedores anônimos dentro de cotas de uso justo.

Cada endpoint é documentado interativamente na referência incorporada abaixo, gerada diretamente da implementação e sempre atualizada.

Como funciona

A análise e a transcrição rodam de forma assíncrona: você envia um job, recebe um job_id, consulta o status e busca o resultado completo quando o processamento termina.

Início rápido

Envie a análise de acordes de uma URL:

curl -X POST https://magic-chords.dev/api/v1/analyze/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

A resposta contém o identificador do seu job:

{"job_id": "bBm3Zx8kQ7...", "status": "processing"}

Consulte o status até que seja complete:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7...

Obtenha acordes, tempo, tom e estrutura:

curl https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../result

Ou baixe diretamente um artefato exportado (pdf, midi, musicxml, txt, csv, json):

curl -o chords.pdf \
  "https://magic-chords.dev/api/v1/jobs/bBm3Zx8kQ7.../export?format=pdf"

Para analisar um arquivo de áudio local em vez de uma URL:

curl -X POST https://magic-chords.dev/api/v1/analyze \
  -F "file=@song.mp3"

Endpoints

Método e caminho	Finalidade
`POST /api/v1/analyze`	Enviar áudio carregado para análise de acordes (form multipart)
`POST /api/v1/analyze/url`	Enviar uma URL de mídia para análise de acordes
`POST /api/v1/transcribe`	Enviar áudio carregado para transcrição de letras
`POST /api/v1/transcribe/url`	Enviar uma URL de mídia para transcrição de letras
`GET /api/v1/jobs/{job_id}`	Status compacto para polling
`GET /api/v1/jobs/{job_id}/result`	Resultado completo (acordes, palavras, tempo, tom…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Exportar análise concluída como pdf/midi/musicxml/txt/csv/json
`GET /api/v1/limits`	Política de cotas atual (sem contagem)

Limites de uso

Clientes anônimos têm limites por endereço IP. Valores atuais (também disponíveis em /api/v1/limits):

Categoria	Limite
Envios de jobs (heavy)	20 por hora por cliente
Leituras de status/resultado/export (light)	60 por minuto por cliente
Jobs simultâneos	2 por cliente

Cada resposta contabilizada inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Ao atingir um limite você recebe 429 com o cabeçalho Retry-After — respeite-o, por favor.

Erros

Status	Significado
`400`	Requisição inválida (URL inválida, formato desconhecido)
`404`	job_id desconhecido
`409`	O job existe mas não terminou ou não pode ser exportado
`413`	O upload excede o tamanho máximo
`415`	Arquivo não reconhecido como áudio
`429`	Limite de requisições ou de concorrência atingido
`503`	Indisponível temporariamente (backend de cotas fora do ar)

Notas e bom uso

Trate seu job_id como um token de acesso: quem o tiver pode ler o resultado do job.
URLs enviadas devem apontar para hosts publicamente acessíveis; endereços internos são rejeitados.
As exportações exigem uma análise de acordes concluída; jobs apenas de transcrição ainda não podem ser exportados.
A autenticação por cookies do YouTube não está disponível na API pública.
Endereços IP de clientes podem ser registrados para prevenção de abusos.
O acesso cross-origin pelo navegador fica desativado por padrão; operadores podem permitir origens via PUBLIC_API_CORS_ORIGINS.

Referência interativa da API

A referência completa é carregada abaixo — explore cada endpoint e teste as requisições diretamente nesta página.

Carregando a referência interativa…