Jam Jam

API REST · OpenAPI 3.1 · Servidor MCP

API para desarrolladores

Convierte archivos, enlaces y textos en acordes y letras, y luego lee y completa tu cancionero desde un script o un asistente.

Crear una clave de API Cuenta gratuita · 6 conversiones por semana Contrato OpenAPI
  • Nivel gratuito
  • El mismo motor que la app
  • Servidor MCP oficial
URL base https://jam-jam.org/api/v1 openapi.json llms.txt

Lo que permite la API

Cada capacidad se abre con un alcance que marcas al crear tu clave.

Conversión

Audio, PDF, imágenes, texto o un enlace a songbook, PDF, MIDI, MusicXML y más.

convert:writeconvert:read

Cancionero privado

Listar, leer, crear, modificar y ordenar tus canciones y playlists.

carnet:readcarnet:write

Perfiles públicos

Solo lectura: perfiles, canciones publicadas, seguidores. Ninguna pista de audio.

social:read

Separación de pistas

Una conversión (output=stems) separa la voz del acompañamiento; la herramienta /stem-tool separa en dos o cuatro pistas. Con una clave API, ambas exigen una cuenta Premium.

stems:write Clave API Premium

Cola de audio

Análisis de acordes y letras en la misma cola que la aplicación.

audio:writequeue:read

Detección de música IA

Un indicio de generación para un archivo, un enlace de Spotify, un enlace de audio directo o un ISRC.

Límites, cuotas y privacidad

La música generada por IA es cada vez más frecuente. Jam Jam te ayuda a buscar indicios: pega un enlace o sube un archivo para obtener un resultado orientativo.

Máx. 100 MB · Máx. 10 min · Spotify, enlace directo de audio o ISRC. YouTube no es compatible. Los enlaces de Spotify pueden analizarse solo a partir de un fragmento.

Un archivo en espera o en proceso por cuenta. Las cuentas Premium tienen prioridad en la cola.

Visitante: 2 análisis/día y 5/mes. Cuenta gratuita: 5/día y 50/mes. Premium: 30/día y 300/mes. Cuotas compartidas entre web, app y API; los errores no cuentan. Reinicio a medianoche UTC y el primer día del mes UTC.

El audio se envía a nuestro proveedor SH Labs para analizarlo. Según su política, no conserva el audio ni lo usa para entrenar modelos. Si falla, un archivo puede analizarse localmente cuando esté disponible el servicio de respaldo. Los archivos temporales se eliminan tras el procesamiento, error o cancelación. Tu cuenta conserva el nombre o enlace, fecha, estado y resultado durante 90 días; los visitantes, 24 h. Los límites de visitantes usan un token y un identificador de red seudonimizado, sin guardar la IP en claro.

Este índice no es una probabilidad ni una prueba. Un índice bajo no garantiza un origen humano.

Descubrir la herramienta
audio:writequeue:read

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:

Formatos de entrada

  • Archivos de audio y vídeo
  • PDF: acordes, letras, partitura, tablatura, cancionero escaneado
  • Imágenes: acordes, letras, partitura, tablatura
  • Texto plano, ChordPro, OnSong
  • Enlaces y búsqueda web (page-link, web-search)
  • MusicXML, MIDI
  • JamSong, .zip mixto, songbook (pivote)

Formatos de salida

  • Songbook (pivote JSON, siempre disponible)
  • PDF: acordes, letras, partitura, tablatura, cuadrícula
  • PNG, HTML, texto plano, ChordPro
  • chords-lab, chords-csv, tonalidad y BPM
  • MusicXML, MIDI (Premium)
  • Letras sincronizadas: .lrc, .srt
  • Vídeo karaoke (.mp4), audio de acompañamiento, JamSong

Empieza en cuatro pasos

La conversión es asíncrona: envías, sigues y recuperas.

  1. Crear una clave

    Ajustes › Claves de API. Prefijo jj_live_, se muestra una sola vez, 5 claves por cuenta, revocables.

    Gestionar mis claves de API

  2. Enviar

    Un archivo, una URL o texto, con el formato de salida que quieras.

    POST /jobs

  3. Seguir

    Consulta respetando Retry-After, o abre un flujo Server-Sent Events.

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

  4. Recuperar

    El resultado sigue disponible 24 horas; después, 410 Gone.

    GET /jobs/{id}/result

Ejemplos

Llamadas completas, listas para copiar tal cual.

Listar los formatos que sirve este servidorcurl

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

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

Seguir el progreso (SSE o sondeo)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

Descargar el resultadocurl

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

Analizar una canción con la detección de música 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

Ejemplos de código

Ejemplos listos para ejecutar en curl, JavaScript y Python, de código abierto con licencia MIT:

jam-jam-api-examples

Asistentes y MCP

Un asistente lee el contrato y construye sus llamadas. El servidor MCP oficial le da 42 herramientas listas.

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.

openapi.json llms.txt

Servidor MCP

Clave leída en JAM_JAM_API_KEY: solo aparecen las herramientas que permiten sus alcances. No sigue a nadie, no da me gusta y no publica nada por su cuenta.

Claude DesktopClaude CodeCursor
En detalle

Un servidor oficial de Model Context Protocol expone la API a un asistente como 42 herramientas con el prefijo jj_: conversión de archivos y de texto, lectura y organización de tu cancionero privado, lectura de perfiles públicos, separación de stems, análisis de audio y cola, detección de música con IA y Mastering. Lee tu clave de API de la variable de entorno JAM_JAM_API_KEY y solo muestra las herramientas que permiten los alcances de esa clave. Se encarga del sondeo, los errores de cuota y la obtención de los archivos por ti, para que un asistente como Claude Desktop, Claude Code o Cursor pueda convertir un archivo u organizar tu cancionero sin que escribas ni una línea de código HTTP. Nunca sigue a nadie, ni da me gusta, ni publica una canción por su cuenta.

Instalaciónshell 
npx -y @jam-jam/convert-mcp

Página del paquete en npm: npmjs.com/package/@jam-jam/convert-mcp

Configuración (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"
      }
    }
  }
}

Herramientas y alcances necesarios 42

Conversión

formatos, archivos, texto y estado de los trabajos.

  • jj_list_formatssin alcance
  • jj_convert_fileconvert:write
  • jj_convert_textconvert:write
  • jj_get_jobconvert:read
Cuota sin alcance

lo que puede hacer la clave y lo que le queda.

  • jj_check_usage
Cancionero privado, lectura carnet:read

canciones y playlists.

  • jj_list_songs
  • jj_get_song
  • jj_list_playlists
  • jj_get_playlist
Cancionero privado, escritura carnet:write

crear, modificar y borrar canciones y playlists.

  • jj_create_song
  • jj_update_song
  • jj_delete_song
  • jj_create_playlist
  • jj_update_playlist
  • jj_delete_playlist
Perfiles públicos, lectura social:read

fichas de perfil, canciones y playlists publicadas, seguidores y seguidos.

  • jj_get_profile
  • jj_list_profile_songs
  • jj_list_profile_playlists
  • jj_list_followers
  • jj_list_following
Separación de stems

capacidades, trabajos y archivos.

  • 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
Análisis de audio y cola

analizar un archivo, y listar, leer y cancelar trabajos.

  • jj_audio_analyzeaudio:write
  • jj_queue_listqueue:read
  • jj_queue_get_jobqueue:read
  • jj_queue_cancel_jobaudio:write
Detección de música con IA

disponibilidad, análisis, historial y trabajos.

  • 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

capacidades, preajustes, renderizado, estado y cancelación de los trabajos.

  • jj_mastering_capabilitiessin alcance
  • jj_list_mastering_presetsmastering:read
  • jj_create_mastering_presetmastering:write
  • jj_master_audiomastering:write
  • jj_mastering_get_jobmastering:read
  • jj_mastering_cancel_jobmastering:write

Referencia de endpoints

Todas las rutas servidas, por familia, con su alcance y su cuota. El contrato completo es el que vale.

Conversión (jobs) 6
Método Ruta Alcance Cuota
POST /jobsEnvía una conversión: un archivo (multipart/form-data), una URL o texto plano/ChordPro (application/json). Con output=stems también se requieren el alcance stems:write y una clave API Premium, con una cuota aparte (200/día UTC). convert:write cuota: conversión
GET /jobs/{id}Estado de un trabajo (fase, porcentaje, pasos). Sondéalo respetando la cabecera Retry-After. convert:read cuota: ninguna
DELETE /jobs/{id}Cancela un trabajo y borra sus archivos; solo devuelve la cuota si todavía estaba en cola. convert:write cuota: ninguna
GET /jobs/{id}/eventsAlternativa al sondeo mediante Server-Sent Events: eventos state, done, error y ping de mantenimiento. convert:read cuota: ninguna
GET /jobs/{id}/resultDescarga el artefacto principal (o uno concreto mediante ?artifact=). Disponible 24 horas tras crear el trabajo. convert:read cuota: ninguna
GET /jobs/{id}/result/songbookEl pivote JSON canónico del songbook (acordes, letra, estructura), siempre disponible cuando el trabajo termina. convert:read cuota: ninguna

Formatos 1
Método Ruta Alcance Cuota
GET /formatsRegistro de los pares entrada/salida que este servidor realmente ofrece, con sus límites (maxBytes, maxPages, maxDurationS). público (sin clave) cuota: ninguna

Uso y cuotas 1
Método Ruta Alcance Cuota
GET /me/usageEl saldo de tus cuotas (conversión, lectura, escritura, stems) y los alcances que tu identidad puede ejercer realmente, en una sola llamada. convert:read cuota: ninguna

Cancionero, lectura 4
Método Ruta Alcance Cuota
GET /me/songsLista las canciones de tu cancionero privado, paginada por cursor opaco; usa updatedSince para una exportación incremental. carnet:read cuota: lectura
GET /me/songs/{songId}Una canción completa de tu cancionero, con acordes, letra y estructura. carnet:read cuota: lectura
GET /me/playlistsLista las listas de reproducción de tu cancionero, planas y de pertenencia múltiple, misma paginación que las canciones. carnet:read cuota: lectura
GET /me/playlists/{playlistId}Una lista de reproducción y sus canciones, en orden, en formato resumido. carnet:read cuota: lectura

Cancionero, escritura 8
Método Ruta Alcance Cuota
POST /me/songsAñade una canción a tu cancionero, el mismo payload pivote que devuelve una conversión. Pon Idempotency-Key para evitar duplicados. carnet:write cuota: escritura
PUT /me/songs/{songId}Reemplaza una canción por completo (declarativo); la crea con ese identificador si aún no existe. carnet:write cuota: escritura
PATCH /me/songs/{songId}Modifica solo los campos enviados (tonalidad, cejilla, bpm, playlistIds...); también publica o despublica la canción en tu perfil. carnet:write cuota: escritura
DELETE /me/songs/{songId}Elimina una canción de tu cancionero; supresión suave, idempotente, sale también de todas sus listas. carnet:write cuota: escritura
POST /me/playlistsCrea una lista de reproducción; songIds es la lista ordenada de canciones que contiene, se conserva tal cual. carnet:write cuota: escritura
PUT /me/playlists/{playlistId}Reemplaza una lista de reproducción por completo (declarativo); songIds es obligatorio. carnet:write cuota: escritura
PATCH /me/playlists/{playlistId}Renombra, cambia el emoji de portada o reordena por completo las canciones de una lista. carnet:write cuota: escritura
DELETE /me/playlists/{playlistId}Elimina la lista de reproducción en sí; sus canciones permanecen en tu cancionero y en sus otras listas. carnet:write cuota: escritura

Social, solo lectura 5
Método Ruta Alcance Cuota
GET /users/{handle}Cabecera del perfil público de una cuenta por su alias; una cuenta privada que no sigues devuelve una tarjeta cerrada (sin bio ni contadores). social:read cuota: lectura
GET /users/{handle}/songsCanciones que una cuenta ha publicado en su perfil; audioPlayable solo es cierto si os seguís mutuamente. social:read cuota: lectura
GET /users/{handle}/playlistsListas de reproducción que una cuenta ha publicado; songCount solo cuenta lo que realmente puedes ver. social:read cuota: lectura
GET /me/followersCuentas que te siguen; status=accepted (por defecto) o requested. social:read cuota: lectura
GET /me/followingCuentas que sigues; status=requested lista las solicitudes pendientes hacia cuentas privadas. social:read cuota: lectura

Cola de audio y stems 4
Método Ruta Alcance Cuota
POST /audioEncola el análisis automático (acordes, letra) y luego el ajuste, para una canción ya presente en tu cancionero. Misma cola que la aplicación; songId debe ser tuyo. audio:write cuota: ninguna
GET /queueLa cola de procesamiento de audio de tu cuenta: activa, en espera (con rank) y la terminada de los últimos 7 días. queue:read cuota: ninguna
GET /queue/{id}Un trabajo de la cola de audio, solo el tuyo; mismo 404 indiferenciado para un trabajo desconocido o de otra cuenta. queue:read cuota: ninguna
DELETE /queue/{id}Cancela un trabajo de tu cola de audio; solo devuelve la cuota si el análisis aún no había terminado. audio:write cuota: ninguna

Separación de pistas 6
Método Ruta Alcance Cuota
GET /stem-tool/capabilitiesConsultar la disponibilidad, los límites, los modelos y la cuota de separación de pistas de quien llama. convert:read cuota: ninguna
GET /stem-tool/jobsEnumerar las separaciones privadas de quien llama, con un cursor de paginación opcional. convert:read cuota: ninguna
POST /stem-tool/jobsSubir un archivo de audio para separarlo en dos o cuatro pistas. Las claves API requieren Premium. stems:write cuota: stems
GET /stem-tool/jobs/{id}Consultar el estado, el progreso y los archivos disponibles de una separación propia. convert:read cuota: ninguna
DELETE /stem-tool/jobs/{id}Cancelar una separación propia. stems:write cuota: ninguna
GET /stem-tool/jobs/{id}/files/{name}Obtener una URL firmada temporal para descargar una pista MP3 o un archivo ZIP. convert:read cuota: ninguna

Con una clave API, todas estas rutas exigen una cuenta Premium; si no, la respuesta es un 403 (api-premium-required). Los límites de quien llama están en GET /stem-tool/capabilities.

Mastering 8
Método Ruta Alcance Cuota
GET /mastering/capabilitiesLímites, rangos de ajustes, objetivos de sonoridad, preajustes integrados y derecho de renderizado. público (sin clave) cuota: ninguna
GET /mastering/presetsListar tus preajustes de mastering. mastering:read cuota: ninguna
POST /mastering/presetsCrear un preajuste de mastering (Idempotency-Key obligatorio). mastering:write cuota: ninguna
DELETE /mastering/presets/{id}Eliminar uno de tus preajustes de mastering. mastering:write cuota: ninguna
POST /mastering/jobsSubir un audio e iniciar un renderizado de mastering con un preajuste o ajustes. mastering:write cuota: mastering (3/semana gratis, ilimitado Premium)
GET /mastering/jobs/{id}Consultar el estado de un trabajo de mastering. mastering:read cuota: ninguna
DELETE /mastering/jobs/{id}Cancelar un trabajo de mastering. mastering:write cuota: ninguna
GET /mastering/jobs/{id}/resultDescargar el WAV masterizado. mastering:read cuota: ninguna

Detección de música IA 7 + 1 interna
Método Ruta Alcance Cuota
GET /ai-music/availabilityDisponibilidad de la herramienta, formatos aceptados y cuotas restantes de la cuenta o del visitante. público (sin clave) cuota: ninguna
POST /ai-music/jobsEnvía un archivo de audio, un enlace de Spotify, un enlace de audio directo o un ISRC. Un solo trabajo sin terminar por cuenta; YouTube no es compatible. audio:write cuota: detección IA
GET /ai-music/jobsRecupera tu análisis en curso o el más reciente. queue:read cuota: ninguna
GET /ai-music/jobs/{id}Sigue un análisis y lee su informe. queue:read cuota: ninguna
DELETE /ai-music/jobs/{id}Cancela un análisis y borra sus archivos temporales. audio:write cuota: ninguna
GET /ai-music/historyHistorial privado de los últimos 90 días, en páginas de 30; requiere cuenta, no se conserva ningún audio. queue:read cuota: ninguna
DELETE /ai-music/history/{id}Borra un escaneo de tu historial; la cuota de un análisis correcto no se devuelve. audio:write cuota: ninguna
GET /ai-music/source/{token}/{filename}Dirección temporal reservada al proveedor de detección, válida 180 segundos como máximo: ningún cliente la llama. interna cuota: ninguna

Estado y especificación 2
Método Ruta Alcance Cuota
GET /healthEstado del servicio y disponibilidad por motor (OMR, audio, vídeo...); no requiere autenticación. público (sin clave) cuota: ninguna
GET /openapi.jsonEste contrato, en JSON legible por una máquina. público (sin clave) cuota: ninguna

Contrato completo, legible por una máquina, siempre sincronizado con esta tabla:

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

Cuotas y límites

El saldo exacto está en GET /me/usage y en los encabezados X-Quota-* de cada respuesta.

Conversión

Cuenta gratuita
6 / semana
Premium
500 / mes
Sin clave ni sesión
3 / 24 h

El mismo contador que la exportación del cancionero en la aplicación.

Lecturas y escrituras

por día UTCCuenta gratuitaPremium
Lecturas (cancionero, perfiles)200020.000
Escrituras (cancionero)2005000

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

Pistas separadas por conversión

POST /jobs · output=stems

Se exige una clave API Premium: sin Premium, la respuesta es un 403 (premium-required).

Premium
200 por día UTC

Al llamar a estas rutas, garantizas que tienes los derechos sobre el audio enviado.

En detalle
  • POST /jobs con output=stems devuelve un .zip: vocals, accompaniment y manifest.json.
  • Alcances necesarios: stems:write y convert:write.
  • Un contador propio, distinto del de las conversiones, contado por día UTC (no en 24 horas móviles).
  • No hay que confundirlo con la herramienta Separación de pistas (/stem-tool/*): allí una clave API exige una cuenta Premium, con sus propios límites (GET /stem-tool/capabilities).

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.

Gestionar mis claves de API

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.

Créditos de código abierto

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

Modelos y datos

Detección de intervinientes (Studio): modelo de huella de voz WeSpeaker ResNet34-LM, proyecto WeNet (github.com/wenet-e2e/wespeaker), entrenado con VoxCeleb (VGG, Universidad de Oxford), licencia CC BY 4.0 (creativecommons.org/licenses/by/4.0/). Modificado por Jam Jam: pesos convertidos a media precisión.