API publique Magic Chords

Une API REST versionnée pour la reconnaissance d'accords, la transcription de paroles et l'export de partitions. Tous les endpoints vivent sous /api/v1/, acceptent et renvoient du JSON (hors téléversements et fichiers générés) et sont ouverts aux développeurs anonymes dans des quotas raisonnables.

Chaque endpoint est documenté de manière interactive dans la référence intégrée ci-dessous, générée directement à partir de l'implémentation et toujours à jour.

Comment ça marche

L'analyse et la transcription s'exécutent de façon asynchrone : vous soumettez un job, recevez un job_id, interrogez le statut, puis récupérez le résultat complet une fois le traitement terminé.

Démarrage rapide

Soumettre l'analyse d'accords d'une 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 réponse contient l'identifiant de votre job :

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

Interrogez le statut jusqu'à ce qu'il soit complete :

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

Récupérer accords, tempo, tonalité et structure :

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

Ou télécharger directement un fichier exporté (pdf, midi, musicxml, txt, csv, json) :

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

Pour analyser un fichier audio local plutôt qu'une URL :

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

Endpoints

Méthode & chemin	Rôle
`POST /api/v1/analyze`	Soumettre un audio téléversé pour analyse d'accords (formulaire multipart)
`POST /api/v1/analyze/url`	Soumettre une URL média pour analyse d'accords
`POST /api/v1/transcribe`	Soumettre un audio téléversé pour transcription de paroles
`POST /api/v1/transcribe/url`	Soumettre une URL média pour transcription de paroles
`GET /api/v1/jobs/{job_id}`	Statut compact pour le polling
`GET /api/v1/jobs/{job_id}/result`	Résultat complet (accords, mots, tempo, tonalité…)
`GET /api/v1/jobs/{job_id}/export?format=…`	Exporter une analyse terminée en pdf/midi/musicxml/txt/csv/json
`GET /api/v1/limits`	Politique de quotas actuelle (non comptée)

Limites d'utilisation

Les clients anonymes sont limités par adresse IP. Valeurs actuelles (aussi disponibles en direct sur /api/v1/limits) :

Catégorie	Limite
Soumissions de jobs (heavy)	20 par heure par client
Lectures statut/résultat/export (light)	60 par minute par client
Jobs simultanés	2 par client

Chaque réponse comptée embarque les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement vous recevez un 429 avec l'en-tête Retry-After — merci de le respecter.

Erreurs

Statut	Signification
`400`	Requête invalide (URL erronée, format inconnu)
`404`	job_id inconnu
`409`	Le job existe mais n'est pas terminé ou non exportable
`413`	Le téléversement dépasse la taille maximale
`415`	Fichier non reconnu comme audio
`429`	Limite de débit ou de concurrence atteinte
`503`	Temporairement indisponible (backend de quotas hors service)

Notes & bon usage

Traitez votre job_id comme un jeton d'accès : quiconque le détient peut lire le résultat du job.
Les URL soumises doivent pointer vers des hôtes publiquement accessibles ; les adresses internes sont rejetées.
Les exports exigent une analyse d'accords terminée ; les jobs de transcription seule ne sont pas encore exportables.
L'authentification par cookies YouTube n'est pas disponible via l'API publique.
Les adresses IP des clients peuvent être enregistrées pour prévenir les abus.
L'accès navigateur multi-origine est désactivé par défaut ; les opérateurs peuvent autoriser des origines via PUBLIC_API_CORS_ORIGINS.

Référence API interactive

La référence complète se charge ci-dessous — parcourez chaque endpoint et testez les requêtes directement depuis cette page.

Chargement de la référence interactive…