Entwickler-API

Unterstützte Formate

Die vollständige, aktuelle Liste, mit genauen Grenzwerten und dem, was dieser Server tatsächlich bedient, steht immer unter GET /formats. Kurz gefasst:

Einen API-Schlüssel erhalten

Erstelle ein kostenloses Jam-Jam-Konto, öffne dann in der App (mobil oder web) Einstellungen, API-Schlüssel und erstelle einen Schlüssel. Er beginnt mit jj_live_ und wird nur einmal angezeigt: kopiere ihn sofort. Bis zu 5 Schlüssel pro Konto, jederzeit widerrufbar.

Kontingente

Derselbe Zähler wie der Export aus dem Liederbuch in der App: 10 Konvertierungen pro gleitender Woche bei einem kostenlosen Konto, 500 pro Monat bei Premium. Anonyme Aufrufe (ohne Schlüssel, ohne Sitzung) sind auf 3 pro 24 Stunden begrenzt. Der genaue Kontostand steht in GET /me/usage und in den X-Quota-*-Headern jeder Antwort, die Kontingent verbraucht.

So funktioniert es

Die Konvertierung ist asynchron: du reichst einen Job ein, er wird eingereiht, läuft, und du holst das Ergebnis ab, sobald er fertig ist. Verfolge ihn entweder per Abfrage von GET /jobs/{id} (Retry-After beachten) oder über einen Server-Sent-Events-Stream unter GET /jobs/{id}/events.

Beispiele

Die von diesem Server bedienten Formate auflisten

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

Eine Datei in PDF umwandeln

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

Eine URL in ein Songbook umwandeln

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

Fortschritt verfolgen (SSE oder Abfrage)

# 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

Das Ergebnis herunterladen

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"))

Fehler

Jeder Fehler, auf jeder Route, ist ein application/problem+json-Objekt (RFC 9457) mit einem stabilen code-Feld, an dem ein Client seine Logik ausrichten kann: quota-exhausted, rate-limited, unsupported-pair, not-found... Der vollständige Katalog steht im OpenAPI-Schema (components.schemas.Problem).

Aufbewahrung

Hochgeladene Dateien und erzeugte Ergebnisse werden 24 Stunden nach Erstellung des Jobs gelöscht. Nichts wird länger aufbewahrt, auch fehlgeschlagene Jobs nicht. Der Abruf eines Ergebnisses nach dieser Frist liefert 410 Gone.

Für KI-Agenten

Lies zuerst GET /openapi.json: es dokumentiert die empfohlene Aufrufreihenfolge (Formate entdecken, einreichen, verfolgen, abrufen), Authentifizierung und Kontingente in einem x-agent-guide-Block, der für ein Modell gedacht ist. Die llms.txt dieser Website listet jede Konvertierungsfähigkeit als eigenen Eintrag.

MCP server

An official Model Context Protocol server, generated from this same OpenAPI spec, exposes the API as five tools: list_formats, convert_file, convert_text, get_job and get_usage. It handles polling, quota errors and file results for you, so an assistant like Claude Desktop, Claude Code or Cursor can convert a file without you writing any HTTP code.

Install

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

Tools

• list_formats: input and output formats served, with limits
• convert_file: local file path or base64 content in, downloaded result out
• convert_text: pasted text or ChordPro in, no file needed
• get_job: job status by id (phase, progress, artifacts)
• get_usage: the calling identity's quota balance

Open-Source-Credits

Diese API stützt sich auf echte Open-Source-Engines. Ehrlich genutzt, namentlich genannt:

• 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