API para desarrolladores

Formatos admitidos

La lista completa y actualizada, con los límites exactos y lo que este servidor realmente ofrece, está siempre en GET /formats. En resumen:

Obtener una clave API

Crea una cuenta gratuita de Jam Jam, luego abre Ajustes, Claves de API en la aplicación (móvil o web) y crea una clave. Empieza por jj_live_ y solo se muestra una vez: cópiala enseguida. Máximo 5 claves por cuenta, revocables en cualquier momento.

Cuotas

Mismo contador que exportar desde el cancionero en la aplicación: 10 conversiones por semana móvil en una cuenta gratuita, 500 al mes en Premium. Las llamadas anónimas (sin clave, sin sesión) están limitadas a 3 cada 24 horas. El saldo exacto está en GET /me/usage y en las cabeceras X-Quota-* de cada respuesta que consume cuota.

Cómo funciona

La conversión es asíncrona: envías un trabajo, entra en cola, se ejecuta, y recuperas el resultado cuando termina. Síguelo sondeando GET /jobs/{id} (respeta Retry-After) o abriendo un flujo Server-Sent Events en GET /jobs/{id}/events.

Ejemplos

Listar los formatos que sirve este servidor

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

Convertir un archivo a 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 una URL a un 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"}'

Seguir el progreso (SSE o sondeo)

# 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

Descargar el resultado

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

Errores

Cada error, en cada ruta, es un objeto application/problem+json (RFC 9457) con un campo code estable sobre el que un cliente puede ramificar su lógica: quota-exhausted, rate-limited, unsupported-pair, not-found... El catálogo completo está en el esquema OpenAPI (components.schemas.Problem).

Retención

Los archivos subidos y los resultados generados se eliminan 24 horas después de crear el trabajo. Nada se conserva más tiempo, incluidos los trabajos fallidos. Recuperar un resultado pasado ese plazo devuelve 410 Gone.

Para agentes de IA

Lee primero GET /openapi.json: documenta la secuencia de llamadas recomendada (descubrir formatos, enviar, seguir, recuperar), la autenticación y las cuotas en un bloque x-agent-guide pensado para ser leído por un modelo. El llms.txt de este sitio enumera cada capacidad de conversión como una entrada propia.

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

Créditos de código abierto

Esta API se apoya en motores de código abierto reales. Usados honestamente, acreditados por su nombre:

• 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