API pública de Magic Chords

Una API REST versionada para reconocimiento de acordes, transcripción de letras y exportación de partituras. Todos los endpoints están bajo /api/v1/, aceptan y devuelven JSON (excepto subidas y archivos generados) y están abiertos a desarrolladores anónimos dentro de cuotas de uso razonable.

Cada endpoint está documentado de forma interactiva en la referencia integrada de abajo, generada directamente a partir de la implementación y siempre actualizada.

Cómo funciona

El análisis y la transcripción se ejecutan de forma asíncrona: envías un trabajo, recibes un job_id, consultas el estado y obtienes el resultado completo cuando el procesamiento termina.

Inicio rápido

Envía el análisis de acordes de una 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"}'

La respuesta contiene el identificador de tu trabajo:

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

Consulta el estado hasta que sea complete:

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

Obtén acordes, tempo, tonalidad y estructura:

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

O descarga un artefacto exportado directamente (pdf, midi, musicxml, txt, csv, json):

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

Para analizar un archivo de audio local en lugar de una URL:

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

Endpoints

Método y ruta	Propósito
`POST /api/v1/analyze`	Enviar audio subido para análisis de acordes (formulario multipart)
`POST /api/v1/analyze/url`	Enviar una URL de medios para análisis de acordes
`POST /api/v1/transcribe`	Enviar audio subido para transcripción de letras
`POST /api/v1/transcribe/url`	Enviar una URL de medios para transcripción de letras
`GET /api/v1/jobs/{job_id}`	Estado compacto para sondear
`GET /api/v1/jobs/{job_id}/result`	Resultado completo (acordes, palabras, tempo, tonalidad…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Exportar un análisis completado como pdf/midi/musicxml/txt/csv/json
`GET /api/v1/limits`	Política de cuotas actual (sin límite de peticiones)

Límites de uso

Los clientes anónimos tienen límites por dirección IP. Valores actuales (también disponibles en vivo en /api/v1/limits):

Categoría	Límite
Envíos de trabajos (heavy)	20 por hora por cliente
Lecturas de estado/resultado/export (light)	60 por minuto por cliente
Trabajos simultáneos	2 por cliente

Cada respuesta medida incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al alcanzar un límite recibirás un 429 con la cabecera Retry-After: respétala.

Errores

Estado	Significado
`400`	Solicitud no válida (URL errónea, formato desconocido)
`404`	job_id desconocido
`409`	El trabajo existe pero no ha terminado o no se puede exportar
`413`	La subida supera el tamaño máximo
`415`	El archivo no se reconoce como audio
`429`	Límite de peticiones o de concurrencia alcanzado
`503`	No disponible temporalmente (backend de cuotas caído)

Notas y buen uso

Trata tu job_id como un token de acceso: quien lo tenga puede leer el resultado del trabajo.
Las URLs deben apuntar a hosts públicamente accesibles; las direcciones internas se rechazan.
Las exportaciones requieren un análisis de acordes completado; los trabajos solo de transcripción aún no se pueden exportar.
La autenticación con cookies de YouTube no está disponible en la API pública.
Las direcciones IP pueden registrarse para prevenir abusos.
El acceso entre orígenes está desactivado por defecto; los operadores pueden permitir orígenes vía PUBLIC_API_CORS_ORIGINS.

Referencia interactiva de la API

La referencia completa se carga abajo — explore cada endpoint y pruebe las peticiones directamente desde esta página.

Cargando la referencia interactiva…