Magic Chords Public API

Eine versionierte REST-API fuer Akkorderkennung, Liedtext-Transkription und Noten-Exporte. Alle Endpunkte liegen unter /api/v1/, akzeptieren und liefern JSON (ausser Uploads und generierten Dateien) und stehen anonymen Entwicklern im Rahmen fairer Limits offen.

Jeder Endpunkt ist interaktiv in der eingebetteten Referenz unten dokumentiert – direkt aus der Implementierung generiert und immer aktuell.

So funktioniert es

Analyse und Transkription laufen asynchron: Sie reichen einen Job ein, erhalten eine job_id, fragen den Status ab und rufen das vollstaendige Ergebnis ab, sobald die Verarbeitung abgeschlossen ist.

Schnellstart

Akkordanalyse fuer eine Song-URL einreichen:

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"}'

Die Antwort enthaelt Ihren Job-Handle:

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

Status abfragen, bis er complete ist:

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

Akkorde, Tempo, Tonart und Struktur abrufen:

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

Oder ein Export-Artefakt direkt herunterladen (pdf, midi, musicxml, txt, csv, json):

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

Um statt einer URL eine lokale Audiodatei zu analysieren:

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

Endpunkte

Methode & Pfad	Zweck
`POST /api/v1/analyze`	Hochgeladene Audio zur Akkordanalyse einreichen (Multipart-Formular)
`POST /api/v1/analyze/url`	Medien-URL fuer die Akkordanalyse einreichen
`POST /api/v1/transcribe`	Hochgeladene Audio fuer Liedtext-Transkription einreichen
`POST /api/v1/transcribe/url`	Medien-URL fuer Liedtext-Transkription einreichen
`GET /api/v1/jobs/{job_id}`	Kompakter Status zum Polling
`GET /api/v1/jobs/{job_id}/result`	Vollstaendige Ergebnisdaten (Akkorde, Woerter, Tempo, Tonart…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Fertige Analyse als pdf/midi/musicxml/txt/csv/json exportieren
`GET /api/v1/limits`	Aktuelle Limit-Politik (nicht gezahlt)

Ratenlimits

Anonyme Clients sind pro IP-Adresse begrenzt. Aktuelle Standards (auch live unter /api/v1/limits abrufbar):

Bucket	Limit
Job-Einreichungen (heavy)	20 pro Stunde pro Client
Status-/Ergebnis-/Export-Lesezugriffe (light)	60 pro Minute pro Client
Gleichzeitig laufende Jobs	2 pro Client

Jede gezaehlte Antwort enthaelt die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Bei Erreichen eines Limits erhalten Sie 429 mit einem Retry-After-Header — bitte respektieren Sie ihn.

Fehler

Status	Bedeutung
`400`	Ungueltige Anfrage (fehlerhafte URL, unbekanntes Format)
`404`	Unbekannte job_id
`409`	Job existiert, ist aber nicht fertig oder nicht exportierbar
`413`	Upload ueberschreitet die maximale Groesse
`415`	Datei wurde nicht als Audio erkannt
`429`	Ratenlimit oder Gleichzeitigkeitslimit erreicht
`503`	Voruebergehend nicht verfuegbar (Quota-Backend ausgefallen)

Hinweise & faires Verhalten

Behandeln Sie Ihre job_id wie ein Capability-Token: Wer sie haelt, kann das Job-Ergebnis lesen.
URL-Einreichungen muessen auf oeffentlich erreichbare Hosts zeigen; interne Adressen werden abgelehnt.
Exporte benoetigen eine abgeschlossene Akkordanalyse; reine Transkriptions-Jobs koennen noch nicht exportiert werden.
YouTube-Cookie-Authentifizierung ist ueber die oeffentliche API nicht verfuegbar.
Client-IP-Adressen koennen zum Missbrauchsschutz aufgezeichnet werden.
Cross-Origin-Browserzugriff ist standardmaessig deaktiviert; Betreiber koennen Urspruenge via PUBLIC_API_CORS_ORIGINS erlauben.

Interaktive API-Referenz

Die vollständige Referenz wird unten geladen — durchsuchen Sie alle Endpunkte und testen Sie Anfragen direkt auf dieser Seite.

Die interaktive Referenz wird geladen…