Jam Jam

API REST · OpenAPI 3.1 · Serveur MCP

API développeur

Convertis fichiers, liens et textes en accords et paroles, puis lis et remplis ton carnet depuis un script ou un assistant.

Créer une clé API Compte gratuit · 6 conversions par semaine Contrat OpenAPI
  • Palier gratuit
  • Même moteur que l’app
  • Serveur MCP officiel
URL de base https://jam-jam.org/api/v1 openapi.json llms.txt

Ce que l’API permet

Chaque capacité est ouverte par une portée que tu coches en créant ta clé.

Conversion

Audio, PDF, images, texte ou lien vers songbook, PDF, MIDI, MusicXML et plus.

convert:writeconvert:read

Carnet privé

Lister, lire, créer, modifier et ranger tes chansons et playlists.

carnet:readcarnet:write

Profils publics

Lecture seule : profils, chansons publiées, abonnés. Aucune bande-son.

social:read

Séparation des pistes

Une conversion (output=stems) sépare la voix et l’accompagnement ; l’outil /stem-tool sépare en deux ou quatre pistes. Avec une clé API, les deux exigent un compte Premium.

stems:write Clé API Premium

File audio

Analyse d’accords et de paroles dans la même file que l’application.

audio:writequeue:read

Détection de musique IA

Un indice de génération pour un fichier, un lien Spotify, un lien audio direct ou un ISRC.

Limites, quotas et confidentialité

Les musiques générées par IA sont de plus en plus présentes. Jam Jam t’aide à repérer des indices de génération : colle un lien ou dépose un fichier pour obtenir un résultat indicatif.

100 Mo max · 10 min max · Spotify, lien audio direct ou ISRC. YouTube non pris en charge. Les liens Spotify peuvent être analysés sur un extrait seulement.

Un seul fichier en attente ou en cours par compte. Les comptes Premium sont prioritaires dans la file.

Visiteur : 2 scans/jour et 5/mois. Compte gratuit : 5/jour et 50/mois. Premium : 30/jour et 300/mois. Quotas partagés entre site, application et API ; les échecs ne sont pas décomptés. Réinitialisation à minuit UTC et le premier du mois UTC.

L’audio est transmis à notre prestataire de détection SH Labs pour analyse. Il indique ne pas conserver l’audio ni l’utiliser pour entraîner ses modèles. En cas d’indisponibilité, un fichier peut être analysé localement quand le secours est disponible. Nos fichiers temporaires sont supprimés après traitement, échec ou annulation. Ton compte conserve pendant 90 jours le nom du fichier ou le lien, la date, l’état et le résultat. Sans compte, le résultat reste disponible 24 h. Les limites visiteur utilisent un jeton et une empreinte réseau pseudonymisée, sans conserver l’adresse IP en clair.

Cet indice n’est pas une probabilité ni une preuve. Un faible indice ne garantit pas une origine humaine.

Découvrir l’outil
audio:writequeue:read

Formats pris en charge

La liste complète et à jour, avec les limites exactes et ce que ce serveur sert réellement, est toujours sur GET /formats. En résumé :

Formats en entrée

  • Fichiers audio et vidéo
  • PDF : accords, paroles, partition, tablature, songbook scanné
  • Images : accords, paroles, partition, tablature
  • Texte brut, ChordPro, OnSong
  • Liens et recherche web (page-link, web-search)
  • MusicXML, MIDI
  • JamSong, .zip mixte, songbook (pivot)

Formats en sortie

  • Songbook (pivot JSON, toujours disponible)
  • PDF : accords, paroles, partition, tablature, grille
  • PNG, HTML, texte brut, ChordPro
  • chords-lab, chords-csv, tonalité et BPM
  • MusicXML, MIDI (Premium)
  • Paroles synchronisées : .lrc, .srt
  • Vidéo karaoké (.mp4), audio d’accompagnement, JamSong

Démarrer en quatre étapes

La conversion est asynchrone : tu déposes, tu suis, tu récupères.

  1. Créer une clé

    Paramètres › Clés API. Préfixe jj_live_, affichée une seule fois, 5 clés par compte, révocables.

    Gérer mes clés API

  2. Déposer

    Un fichier, une URL ou du texte, avec le format de sortie voulu.

    POST /jobs

  3. Suivre

    Sonde en respectant Retry-After, ou ouvre un flux Server-Sent Events.

    GET /jobs/{id}GET /jobs/{id}/events

  4. Récupérer

    Le résultat reste disponible 24 heures, puis 410 Gone.

    GET /jobs/{id}/result

Exemples

Des appels complets, à copier tels quels.

Lister les formats servis par ce serveurcurl

curl https://jam-jam.org/api/v1/formats

Convertir un fichier en PDFcurl

curl -X POST https://jam-jam.org/api/v1/jobs \
  -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  -F [email protected] \
  -F inputFormat=pdf-songbook \
  -F output=pdf-songbook

Convertir une URL en songbookcurl

curl -X POST https://jam-jam.org/api/v1/jobs \
  -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/tabs/amazing-grace", "output": "songbook"}'

Suivre la progression (SSE ou sondage)curl

# Server-Sent Events
curl -N -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/jobs/jb_123/events

# Polling
curl -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/jobs/jb_123

Télécharger le résultatcurl

curl -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  -OJ https://jam-jam.org/api/v1/jobs/jb_123/result

Python (requests)python

import time
import requests

API = "https://jam-jam.org/api/v1"
HEADERS = {"Authorization": "Bearer jj_live_xxxxxxxxxxxxxxxx"}

# 1. Discover formats
formats = requests.get(f"{API}/formats").json()

# 2. Submit a conversion
resp = requests.post(
    f"{API}/jobs",
    headers=HEADERS,
    json={"url": "https://example.com/tabs/amazing-grace", "output": "songbook"},
)
resp.raise_for_status()
job = resp.json()

# 3. Poll until done (or use GET /jobs/{id}/events for SSE)
while job["phase"] not in ("done", "failed", "cancelled"):
    time.sleep(job.get("etaS", 2))
    job = requests.get(f"{API}/jobs/{job['id']}", headers=HEADERS).json()

# 4. Fetch the result
if job["phase"] == "done":
    songbook = requests.get(f"{API}/jobs/{job['id']}/result/songbook", headers=HEADERS).json()
    print(songbook["songs"][0]["title"])
else:
    print("failed:", job.get("problem"))

Analyser un morceau avec la Détection de musique IAcurl

# Availability and remaining quota (no key needed)
curl https://jam-jam.org/api/v1/ai-music/availability

# Analyze a file
curl -X POST https://jam-jam.org/api/v1/ai-music/jobs \
  -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  -F "[email protected]"

# Analyze a Spotify link
curl -X POST https://jam-jam.org/api/v1/ai-music/jobs \
  -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://open.spotify.com/track/2JUDGXTQYGQZrVVUgq40Ke"}'

# History, current analysis, one analysis
curl -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/ai-music/history
curl -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/ai-music/jobs
curl -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/ai-music/jobs/JOB_ID

# Cancel
curl -X DELETE -H "Authorization: Bearer jj_live_xxxxxxxxxxxxxxxx" \
  https://jam-jam.org/api/v1/ai-music/jobs/JOB_ID

Exemples de code

Exemples prêts à lancer en curl, JavaScript et Python, open source sous licence MIT :

jam-jam-api-examples

Assistants et MCP

Un assistant lit le contrat et construit ses appels. Le serveur MCP officiel lui donne 42 outils prêts.

Pour les agents IA

Lis d'abord GET /openapi.json : il documente la séquence d'appels recommandée (découvrir les formats, déposer, suivre, récupérer), l'authentification et les quotas dans un bloc x-agent-guide pensé pour être lu par un modèle. Le llms.txt de ce site liste chaque capacité de conversion comme une entrée à part.

openapi.json llms.txt

Serveur MCP

Clé lue dans JAM_JAM_API_KEY : seuls les outils permis par ses portées apparaissent. Il ne suit personne, n’aime rien, ne publie rien de lui-même.

Claude DesktopClaude CodeCursor
En détail

Un serveur Model Context Protocol officiel expose l'API à un assistant en 42 outils préfixés jj_ : conversion de fichiers et de texte, lecture et organisation de ton carnet privé, lecture des profils publics, séparation des stems, analyse audio et file d'attente, détection de musique IA et Mastering. Il lit ta clé d'API dans la variable d'environnement JAM_JAM_API_KEY et n'affiche que les outils que les portées de cette clé autorisent. Il gère le sondage, les erreurs de quota et la récupération des fichiers à ta place : un assistant comme Claude Desktop, Claude Code ou Cursor peut convertir un fichier ou organiser ton carnet sans que tu écrives le moindre code HTTP. Il ne suit personne, n'aime rien et ne publie aucune chanson de lui-même.

Installationshell 
npx -y @jam-jam/convert-mcp

Page du paquet sur npm : npmjs.com/package/@jam-jam/convert-mcp

Configuration (Claude Desktop, Claude Code, Cursor)json 
{
  "mcpServers": {
    "jam-jam": {
      "command": "npx",
      "args": ["-y", "@jam-jam/convert-mcp"],
      "env": {
        "JAM_JAM_API_KEY": "jj_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Outils et portées requises 42

Conversion

formats, fichiers, texte et état des jobs.

  • jj_list_formatsaucune portée
  • jj_convert_fileconvert:write
  • jj_convert_textconvert:write
  • jj_get_jobconvert:read
Quota aucune portée

ce que la clé peut faire et ce qu'il lui reste.

  • jj_check_usage
Carnet privé, lecture carnet:read

chansons et playlists.

  • jj_list_songs
  • jj_get_song
  • jj_list_playlists
  • jj_get_playlist
Carnet privé, écriture carnet:write

créer, modifier et supprimer des chansons et des playlists.

  • jj_create_song
  • jj_update_song
  • jj_delete_song
  • jj_create_playlist
  • jj_update_playlist
  • jj_delete_playlist
Profils publics, lecture social:read

fiches de profil, chansons et playlists publiées, abonnés et abonnements.

  • jj_get_profile
  • jj_list_profile_songs
  • jj_list_profile_playlists
  • jj_list_followers
  • jj_list_following
Séparation des stems

capacités, jobs et fichiers.

  • jj_stems_capabilitiesconvert:read
  • jj_stems_separatestems:write
  • jj_stems_get_jobconvert:read
  • jj_stems_list_jobsconvert:read
  • jj_stems_get_fileconvert:read
  • jj_stems_cancel_jobstems:write
Analyse audio et file d'attente

analyser un fichier, puis lister, lire et annuler des jobs.

  • jj_audio_analyzeaudio:write
  • jj_queue_listqueue:read
  • jj_queue_get_jobqueue:read
  • jj_queue_cancel_jobaudio:write
Détection de musique IA

disponibilité, analyse, historique et jobs.

  • jj_ai_music_availabilityqueue:read
  • jj_ai_music_analyzeaudio:write
  • jj_ai_music_currentqueue:read
  • jj_ai_music_get_jobqueue:read
  • jj_ai_music_historyqueue:read
  • jj_ai_music_cancel_jobaudio:write
Mastering

capacités, préréglages, rendu, état et annulation des jobs.

  • jj_mastering_capabilitiesaucune portée
  • jj_list_mastering_presetsmastering:read
  • jj_create_mastering_presetmastering:write
  • jj_master_audiomastering:write
  • jj_mastering_get_jobmastering:read
  • jj_mastering_cancel_jobmastering:write

Référence des adresses

Toutes les routes servies, par famille, avec leur portée et leur quota. Le contrat complet fait foi.

Conversion (jobs) 6
Méthode Chemin Portée Quota
POST /jobsDépose une conversion : un fichier (multipart/form-data), une URL ou du texte brut/ChordPro (application/json). Avec output=stems, la portée stems:write et une clé API Premium sont aussi requises, avec un quota séparé (200/jour UTC). convert:write quota : conversion
GET /jobs/{id}État d'un job (phase, pourcentage, étapes). À sonder en respectant l'en-tête Retry-After. convert:read quota : aucun
DELETE /jobs/{id}Annule un job et efface ses fichiers ; ne rembourse le quota que s'il était encore en file. convert:write quota : aucun
GET /jobs/{id}/eventsAlternative au sondage via Server-Sent Events : événements state, done, error et ping de maintien. convert:read quota : aucun
GET /jobs/{id}/resultTélécharge l'artefact principal (ou un artefact précis via ?artifact=). Disponible 24 heures après la création du job. convert:read quota : aucun
GET /jobs/{id}/result/songbookLe pivot JSON canonique du songbook (accords, paroles, structure), toujours disponible une fois le job terminé. convert:read quota : aucun

Formats 1
Méthode Chemin Portée Quota
GET /formatsRegistre des paires entrée/sortie réellement servies par ce serveur, avec leurs limites (maxBytes, maxPages, maxDurationS). public (sans clé) quota : aucun

Usage et quotas 1
Méthode Chemin Portée Quota
GET /me/usageLe solde de tes quotas (conversion, lecture, écriture, stems) et les portées que ton identité peut réellement exercer, en un seul appel. convert:read quota : aucun

Carnet, lecture 4
Méthode Chemin Portée Quota
GET /me/songsListe les chansons de ton carnet privé, paginée par curseur opaque ; utilise updatedSince pour un export incrémental. carnet:read quota : lecture
GET /me/songs/{songId}Une chanson complète de ton carnet, accords, paroles et structure inclus. carnet:read quota : lecture
GET /me/playlistsListe les playlists de ton carnet, plates et multi-appartenance, même pagination que les chansons. carnet:read quota : lecture
GET /me/playlists/{playlistId}Une playlist et ses chansons, dans l'ordre, en résumé. carnet:read quota : lecture

Carnet, écriture 8
Méthode Chemin Portée Quota
POST /me/songsAjoute une chanson à ton carnet, le même payload pivot que rend une conversion. Pose Idempotency-Key pour éviter les doublons. carnet:write quota : écriture
PUT /me/songs/{songId}Remplace entièrement une chanson (déclaratif) ; la crée sous cet identifiant si elle n'existe pas encore. carnet:write quota : écriture
PATCH /me/songs/{songId}Modifie seulement les champs envoyés (tonalité, capo, bpm, playlistIds...) ; publie ou dépublie aussi la chanson sur ton profil. carnet:write quota : écriture
DELETE /me/songs/{songId}Retire une chanson de ton carnet ; suppression douce, idempotente, elle quitte aussi toutes ses playlists. carnet:write quota : écriture
POST /me/playlistsCrée une playlist ; songIds est la liste ordonnée des chansons qu'elle contient, conservée telle quelle. carnet:write quota : écriture
PUT /me/playlists/{playlistId}Remplace entièrement une playlist (déclaratif) ; songIds est obligatoire. carnet:write quota : écriture
PATCH /me/playlists/{playlistId}Renomme, change l'emoji de pochette ou réordonne entièrement les chansons d'une playlist. carnet:write quota : écriture
DELETE /me/playlists/{playlistId}Supprime la playlist elle-même ; ses chansons restent dans ton carnet et dans leurs autres playlists. carnet:write quota : écriture

Social, lecture seule 5
Méthode Chemin Portée Quota
GET /users/{handle}En-tête du profil public d'un compte par pseudo ; un compte privé que tu ne suis pas rend une carte fermée (sans bio ni compteurs). social:read quota : lecture
GET /users/{handle}/songsChansons qu'un compte a publiées sur son profil ; audioPlayable n'est vrai que si vous vous suivez mutuellement. social:read quota : lecture
GET /users/{handle}/playlistsPlaylists qu'un compte a publiées ; songCount ne compte que ce que tu peux réellement voir. social:read quota : lecture
GET /me/followersComptes qui te suivent ; status=accepted (défaut) ou requested. social:read quota : lecture
GET /me/followingComptes que tu suis ; status=requested liste les demandes en attente vers des comptes privés. social:read quota : lecture

File audio et stems 4
Méthode Chemin Portée Quota
POST /audioMet en file l'analyse automatique (accords, paroles) puis le calage, pour une chanson déjà dans ton carnet. Même file que l'application ; songId doit t'appartenir. audio:write quota : aucun
GET /queueLa file de traitement audio de ton compte : active, en attente (avec rank) et terminée des 7 derniers jours. queue:read quota : aucun
GET /queue/{id}Un travail de la file audio, le tien uniquement ; même 404 indifférencié pour un travail inconnu ou d'un autre compte. queue:read quota : aucun
DELETE /queue/{id}Annule un travail de ta file audio ; ne rembourse que si l'analyse n'avait pas encore abouti. audio:write quota : aucun

Séparation des pistes 6
Méthode Chemin Portée Quota
GET /stem-tool/capabilitiesVérifier la disponibilité, les limites, les modèles et le quota de séparation des pistes pour l’appelant. convert:read quota : aucun
GET /stem-tool/jobsLister les séparations privées de l’appelant, avec un curseur de pagination facultatif. convert:read quota : aucun
POST /stem-tool/jobsDéposer un fichier audio pour le séparer en deux ou quatre pistes. Les clés API nécessitent Premium. stems:write quota : stems
GET /stem-tool/jobs/{id}Lire l’état, la progression et les fichiers disponibles d’une séparation appartenant à l’appelant. convert:read quota : aucun
DELETE /stem-tool/jobs/{id}Annuler une séparation appartenant à l’appelant. stems:write quota : aucun
GET /stem-tool/jobs/{id}/files/{name}Obtenir une URL signée temporaire pour télécharger une piste MP3 ou une archive ZIP. convert:read quota : aucun

Avec une clé API, toutes ces routes exigent un compte Premium ; sinon la réponse est un 403 (api-premium-required). Les plafonds de l’appelant sont dans GET /stem-tool/capabilities.

Mastering 8
Méthode Chemin Portée Quota
GET /mastering/capabilitiesLimites, plages des réglages, cibles de loudness, préréglages intégrés et droit de rendu. public (sans clé) quota : aucun
GET /mastering/presetsLister tes préréglages de mastering. mastering:read quota : aucun
POST /mastering/presetsCréer un préréglage de mastering (Idempotency-Key obligatoire). mastering:write quota : aucun
DELETE /mastering/presets/{id}Supprimer un de tes préréglages de mastering. mastering:write quota : aucun
POST /mastering/jobsDéposer un audio et lancer un rendu de mastering avec un préréglage ou des réglages. mastering:write quota : mastering (3 par semaine gratuit, illimité Premium)
GET /mastering/jobs/{id}Lire l’état d’un rendu de mastering. mastering:read quota : aucun
DELETE /mastering/jobs/{id}Annuler un rendu de mastering. mastering:write quota : aucun
GET /mastering/jobs/{id}/resultTélécharger le WAV masterisé. mastering:read quota : aucun

Détection de musique IA 7 + 1 interne
Méthode Chemin Portée Quota
GET /ai-music/availabilityDisponibilité de l’outil, formats acceptés et quotas restants du compte ou du visiteur. public (sans clé) quota : aucun
POST /ai-music/jobsDépose un fichier audio, un lien Spotify, un lien audio direct ou un ISRC. Un seul travail non terminé par compte ; YouTube n’est pas pris en charge. audio:write quota : détection IA
GET /ai-music/jobsRetrouve ton analyse en cours ou la plus récente. queue:read quota : aucun
GET /ai-music/jobs/{id}Suit une analyse et lit son bilan. queue:read quota : aucun
DELETE /ai-music/jobs/{id}Annule une analyse et supprime ses fichiers temporaires. audio:write quota : aucun
GET /ai-music/historyHistorique privé des 90 derniers jours, par pages de 30 ; compte requis, aucun audio conservé. queue:read quota : aucun
DELETE /ai-music/history/{id}Supprime un scan de ton historique ; le quota d’une analyse réussie n’est pas rendu. audio:write quota : aucun
GET /ai-music/source/{token}/{filename}Adresse temporaire réservée au prestataire de détection, valable 180 secondes au plus : aucun client ne l’appelle. interne quota : aucun

Santé et spécification 2
Méthode Chemin Portée Quota
GET /healthÉtat du service et disponibilité par moteur (OMR, audio, vidéo...) ; aucune authentification requise. public (sans clé) quota : aucun
GET /openapi.jsonCe contrat, en JSON lisible par une machine. public (sans clé) quota : aucun

Contrat complet, lisible par une machine, toujours synchronisé avec ce tableau :

https://jam-jam.org/api/v1/openapi.json Contrat OpenAPI

Quotas et limites

Le solde exact est dans GET /me/usage et dans les en-têtes X-Quota-* de chaque réponse.

Conversion

Compte gratuit
6 / semaine
Premium
500 / mois
Sans clé ni session
3 / 24 h

Même compteur que l’export du carnet dans l’application.

Lectures et écritures

par jour UTCCompte gratuitPremium
Lectures (carnet, profils)2 00020 000
Écritures (carnet)2005 000

X-Read-Quota-* · X-Write-Quota-*

Pistes séparées par conversion

POST /jobs · output=stems

Clé API Premium exigée : sans Premium, la réponse est un 403 (premium-required).

Premium
200 par jour UTC

En appelant ces routes, tu garantis détenir les droits sur l’audio envoyé.

En détail
  • POST /jobs avec output=stems renvoie un .zip : vocals, accompaniment et manifest.json.
  • Portées requises : stems:write et convert:write.
  • Un compteur à part, distinct de celui des conversions, décompté par jour UTC (et non sur 24 heures glissantes).
  • À ne pas confondre avec l’outil Séparation des pistes (/stem-tool/*) : une clé API y exige un compte Premium, avec ses propres plafonds (GET /stem-tool/capabilities).

Obtenir une clé API

Crée un compte Jam Jam gratuit, puis ouvre Paramètres, Clés API dans l'application (mobile ou web) et crée une clé. Elle commence par jj_live_ et n'est affichée qu'une fois : copie-la tout de suite. 5 clés maximum par compte, révocables à tout moment.

Gérer mes clés API

Erreurs

Chaque erreur, sur chaque route, est un objet application/problem+json (RFC 9457) avec un champ code stable sur lequel un client peut brancher sa logique : quota-exhausted, rate-limited, unsupported-pair, not-found... Le catalogue complet est dans le schéma OpenAPI (components.schemas.Problem).

Rétention

Les fichiers déposés et les résultats générés sont supprimés 24 heures après la création du job. Rien n'est conservé plus longtemps, y compris les jobs en échec. Récupérer un résultat après ce délai renvoie 410 Gone.

Crédits open source

Cette API s'appuie sur de vrais moteurs open source. Utilisés honnêtement, crédités par leur nom :

Modèles et données

Détection des intervenants (Studio) : modèle d’empreinte de voix WeSpeaker ResNet34-LM, projet WeNet (github.com/wenet-e2e/wespeaker), entraîné sur VoxCeleb (VGG, Université d’Oxford), licence CC BY 4.0 (creativecommons.org/licenses/by/4.0/). Modifié par Jam Jam : poids convertis en demi-précision.