API pubblica Magic Chords

Un'API REST versionata per riconoscimento di accordi, trascrizione di testi ed export di spartiti. Tutti gli endpoint sono sotto /api/v1/, accettano e restituiscono JSON (eccetto upload e file generati) e sono aperti agli sviluppatori anonimi entro quote di fair use.

Ogni endpoint è documentato in modo interattivo nella referenza integrata qui sotto, generata direttamente dall'implementazione e sempre aggiornata.

Come funziona

Analisi e trascrizione girano in modo asincrono: invii un job, ricevi un job_id, interroghi lo stato e scarichi il risultato completo a elaborazione finita.

Avvio rapido

Invia l'analisi degli accordi per l'URL di un brano:

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 risposta contiene l'identificativo del job:

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

Interroga lo stato finché non diventa complete:

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

Scarica accordi, tempo, tonalità e struttura:

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

Oppure scarica subito un artefatto esportato (pdf, midi, musicxml, txt, csv, json):

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

Per analizzare un file audio locale invece di un URL:

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

Endpoint

Metodo e percorso	Scopo
`POST /api/v1/analyze`	Invia audio caricato per analisi degli accordi (form multipart)
`POST /api/v1/analyze/url`	Invia un URL multimediale per analisi degli accordi
`POST /api/v1/transcribe`	Invia audio caricato per trascrizione del testo
`POST /api/v1/transcribe/url`	Invia un URL multimediale per trascrizione del testo
`GET /api/v1/jobs/{job_id}`	Stato compatto per il polling
`GET /api/v1/jobs/{job_id}/result`	Payload completo (accordi, parole, tempo, tonalità…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Esporta un'analisi completata come pdf/midi/musicxml/txt/csv/json
`GET /api/v1/limits`	Politica delle quote attuale (non conteggiata)

Limiti di utilizzo

I client anonimi hanno limiti per indirizzo IP. Valori attuali (disponibili anche live su /api/v1/limits):

Bucket	Limite
Invii di job (heavy)	20 all'ora per client
Letture stato/risultato/export (light)	60 al minuto per client
Job simultanei	2 per client

Ogni risposta conteggiata include le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Al superamento di un limite ricevi 429 con l'intestazione Retry-After: ti chiediamo di rispettarla.

Errori

Stato	Significato
`400`	Richiesta non valida (URL errato, formato sconosciuto)
`404`	job_id sconosciuto
`409`	Il job esiste ma non è finito o non è esportabile
`413`	L'upload supera la dimensione massima
`415`	File non riconosciuto come audio
`429`	Limite di richieste o di concorrenza raggiunto
`503`	Temporaneamente non disponibile (backend quote fuori servizio)

Note e buon uso

Tratta il tuo job_id come un token di accesso: chi lo possiede può leggere il risultato del job.
Gli URL inviati devono puntare a host pubblicamente raggiungibili; gli indirizzi interni vengono rifiutati.
Gli export richiedono un'analisi degli accordi completata; i job di sola trascrizione non sono ancora esportabili.
L'autenticazione con cookie YouTube non è disponibile tramite l'API pubblica.
Gli indirizzi IP dei client possono essere registrati per prevenire abusi.
L'accesso cross-origin da browser è disattivo per impostazione predefinita; gli operatori possono consentire origini via PUBLIC_API_CORS_ORIGINS.

Riferimento API interattivo

Il riferimento completo viene caricato qui sotto — sfoglia ogni endpoint e prova le richieste direttamente da questa pagina.

Caricamento del riferimento interattivo…