API développeur

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é :

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.

Quotas

Même compteur que l'export depuis le carnet dans l'application : 10 conversions par semaine glissante pour un compte gratuit, 500 par mois pour un compte Premium. Les appels anonymes (sans clé, sans session) sont limités à 3 par 24 heures. Le solde exact est dans GET /me/usage et dans les en-têtes X-Quota-* de chaque réponse qui consomme du quota.

Comment ça marche

La conversion est asynchrone : tu déposes un job, il passe en file, s'exécute, et tu récupères le résultat une fois terminé. Suis-le soit par sondage sur GET /jobs/{id} (respecte Retry-After), soit en ouvrant un flux Server-Sent Events sur GET /jobs/{id}/events.

Exemples

Lister les formats servis par ce serveur

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

Convertir un fichier en PDF

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 songbook

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/wonderwall", "output": "songbook"}'

Suivre la progression (SSE ou sondage)

# 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ésultat

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

Python (requests)

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/wonderwall", "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"))

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.

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.

Serveur MCP

Un serveur MCP (Model Context Protocol) officiel, généré depuis ce même schéma OpenAPI, expose l'API en cinq outils : list_formats, convert_file, convert_text, get_job et get_usage. 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 sans que tu écrives le moindre code HTTP.

Installation

npx @jam-jam/convert-mcp

Configuration (Claude Desktop, Claude Code, Cursor)

{
  "mcpServers": {
    "jam-convert": {
      "command": "npx",
      "args": ["-y", "@jam-jam/convert-mcp"],
      "env": { "JAM_JAM_API_KEY": "jj_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

Outils

• list_formats : formats d'entrée et de sortie servis, avec leurs limites
• convert_file : chemin de fichier local ou contenu en base64 en entrée, résultat téléchargé en sortie
• convert_text : texte ou ChordPro collé en entrée, sans fichier
• get_job : état d'un job par son identifiant (phase, avancement, artefacts)
• get_usage : solde du quota de l'identité appelante

Crédits open source

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

• MuseScore 4 (GPL-3.0) : Notation import/render, sheet music PDF
• Audiveris (AGPL-3.0) : Optical Music Recognition (scanned sheet music)
• Tesseract OCR (Apache-2.0) : Text recognition in scanned pages and photos
• faster-whisper (MIT) : Speech-to-text for lyrics from audio
• Basic Pitch (Apache-2.0) : Note and melody detection from audio
• FluidSynth (LGPL-2.1) : Backing-track rendering from MIDI (SoundFont synthesis)
• FFmpeg (LGPL-2.1 / GPL-2.0) : Audio and video encoding, format conversion
• Chromium (BSD-3-Clause) : Headless rendering of sheet music and chord sheets to PDF