Jam Jam

API REST · OpenAPI 3.1 · Server MCP

API per sviluppatori

Converti file, link e testi in accordi e testi delle canzoni, poi leggi e riempi il tuo carnet da uno script o da un assistente.

Crea una chiave API Account gratuito · 6 conversioni a settimana Contratto OpenAPI
  • Piano gratuito
  • Lo stesso motore dell’app
  • Server MCP ufficiale
URL di base https://jam-jam.org/api/v1 openapi.json llms.txt

Cosa permette l’API

Ogni funzione si sblocca con una portata che spunti quando crei la chiave.

Conversione

Audio, PDF, immagini, testo o link verso songbook, PDF, MIDI, MusicXML e altro.

convert:writeconvert:read

Carnet privato

Elencare, leggere, creare, modificare e ordinare le tue canzoni e playlist.

carnet:readcarnet:write

Profili pubblici

Sola lettura: profili, canzoni pubblicate, follower. Nessuna traccia audio.

social:read

Separazione delle tracce

Una conversione (output=stems) separa la voce dall’accompagnamento; lo strumento /stem-tool separa in due o quattro tracce. Con una chiave API, entrambi richiedono un account Premium.

stems:write Chiave API Premium

Coda audio

Analisi di accordi e testi nella stessa coda dell’applicazione.

audio:writequeue:read

Rilevamento di musica IA

Un indizio di generazione per un file, un link Spotify, un link audio diretto o un ISRC.

Limiti, quote e privacy

La musica generata con IA è sempre più diffusa. Jam Jam ti aiuta a cercarne gli indizi: incolla un link o carica un file per un risultato indicativo.

Max 100 MB · Max 10 min · Spotify, link audio diretto o ISRC. YouTube non è supportato. I link Spotify possono essere analizzati solo su un’anteprima.

Un file in attesa o in elaborazione per account. Gli account Premium hanno priorità in coda.

Visitatore: 2 analisi/giorno e 5/mese. Account gratuito: 5/giorno e 50/mese. Premium: 30/giorno e 300/mese. Quote condivise tra sito, app e API; gli errori non contano. Ripristino a mezzanotte UTC e il primo del mese UTC.

L’audio viene inviato al fornitore SH Labs per l’analisi. Dichiara di non conservarlo né usarlo per addestrare modelli. Se il servizio non è disponibile, il file può essere analizzato localmente quando il servizio di riserva è attivo. I file temporanei vengono eliminati dopo elaborazione, errore o annullamento. L’account conserva nome o link, data, stato e risultato per 90 giorni; gli ospiti per 24 ore. Le quote ospite usano un token e un identificatore di rete pseudonimizzato, senza conservare l’IP in chiaro.

Questo indice non è una probabilità né una prova. Un indice basso non garantisce un’origine umana.

Scopri lo strumento
audio:writequeue:read

Formati supportati

L'elenco completo e aggiornato, con i limiti esatti e ciò che questo server serve realmente, è sempre disponibile su GET /formats. In breve:

Formati in ingresso

  • File audio e video
  • PDF: accordi, testi, spartito, tablatura, canzoniere scansionato
  • Immagini: accordi, testi, spartito, tablatura
  • Testo semplice, ChordPro, OnSong
  • Link e ricerca web (page-link, web-search)
  • MusicXML, MIDI
  • JamSong, .zip misto, songbook (pivot)

Formati in uscita

  • Songbook (pivot JSON, sempre disponibile)
  • PDF: accordi, testi, spartito, tablatura, griglia
  • PNG, HTML, testo semplice, ChordPro
  • chords-lab, chords-csv, tonalità e BPM
  • MusicXML, MIDI (Premium)
  • Testi sincronizzati: .lrc, .srt
  • Video karaoke (.mp4), audio di accompagnamento, JamSong

Inizia in quattro passi

La conversione è asincrona: invii, segui, recuperi.

  1. Crea una chiave

    Impostazioni › Chiavi API. Prefisso jj_live_, mostrata una sola volta, 5 chiavi per account, revocabili.

    Gestisci le mie chiavi API

  2. Invia

    Un file, un URL o del testo, con il formato di uscita che vuoi.

    POST /jobs

  3. Segui

    Interroga rispettando Retry-After, oppure apri un flusso Server-Sent Events.

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

  4. Recupera

    Il risultato resta disponibile 24 ore, poi 410 Gone.

    GET /jobs/{id}/result

Esempi

Chiamate complete, da copiare così come sono.

Elenca i formati serviti da questo servercurl

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

Converti un file in 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

Converti un URL in un carnetcurl

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

Segui l'avanzamento (SSE o polling)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

Scarica il risultatocurl

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

Analizzare un brano con il rilevamento di musica 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

Esempi di codice

Esempi pronti all'uso in curl, JavaScript e Python, open source con licenza MIT:

jam-jam-api-examples

Assistenti e MCP

Un assistente legge il contratto e costruisce da solo le sue chiamate. Il server MCP ufficiale gli fornisce 42 strumenti pronti.

Per gli agenti IA

Leggi prima GET /openapi.json: documenta la sequenza di chiamate consigliata (scoprire i formati, inviare, seguire, recuperare), l'autenticazione e le quote in un blocco x-agent-guide pensato per essere letto da un modello. Il file llms.txt di questo sito elenca ogni funzionalità di conversione come voce a sé stante.

openapi.json llms.txt

Server MCP

Chiave letta da JAM_JAM_API_KEY: compaiono solo gli strumenti consentiti dalle sue portate. Non segue nessuno, non mette mi piace e non pubblica nulla di sua iniziativa.

Claude DesktopClaude CodeCursor
Nel dettaglio

Un server ufficiale Model Context Protocol espone l'API a un assistente come 42 strumenti con prefisso jj_: conversione di file e di testo, lettura e organizzazione del tuo carnet privato, lettura dei profili pubblici, separazione degli stem, analisi audio e coda, rilevamento di musica IA e Mastering. Legge la tua chiave API dalla variabile d'ambiente JAM_JAM_API_KEY e mostra solo gli strumenti consentiti dalle portate di quella chiave. Gestisce per te il polling, gli errori di quota e il recupero dei file, così un assistente come Claude Desktop, Claude Code o Cursor può convertire un file o organizzare il tuo carnet senza che tu scriva alcun codice HTTP. Non segue nessuno, non mette like e non pubblica mai una canzone di sua iniziativa.

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

Pagina del pacchetto su npm: npmjs.com/package/@jam-jam/convert-mcp

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

Strumenti e portate richieste 42

Conversione

formati, file, testo e stato dei job.

  • jj_list_formatsnessuna portata
  • jj_convert_fileconvert:write
  • jj_convert_textconvert:write
  • jj_get_jobconvert:read
Quota nessuna portata

cosa può fare la chiave e quanto le resta.

  • jj_check_usage
Carnet privato, lettura carnet:read

canzoni e playlist.

  • jj_list_songs
  • jj_get_song
  • jj_list_playlists
  • jj_get_playlist
Carnet privato, scrittura carnet:write

creare, modificare ed eliminare canzoni e playlist.

  • jj_create_song
  • jj_update_song
  • jj_delete_song
  • jj_create_playlist
  • jj_update_playlist
  • jj_delete_playlist
Profili pubblici, lettura social:read

schede profilo, canzoni e playlist pubblicate, follower e seguiti.

  • jj_get_profile
  • jj_list_profile_songs
  • jj_list_profile_playlists
  • jj_list_followers
  • jj_list_following
Separazione degli stem

capacità, job e file.

  • 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
Analisi audio e coda

analizzare un file, poi elencare, leggere e annullare i job.

  • jj_audio_analyzeaudio:write
  • jj_queue_listqueue:read
  • jj_queue_get_jobqueue:read
  • jj_queue_cancel_jobaudio:write
Rilevamento di musica IA

disponibilità, analisi, cronologia e job.

  • 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à, preset, rendering, stato e annullamento dei job.

  • jj_mastering_capabilitiesnessuna portata
  • jj_list_mastering_presetsmastering:read
  • jj_create_mastering_presetmastering:write
  • jj_master_audiomastering:write
  • jj_mastering_get_jobmastering:read
  • jj_mastering_cancel_jobmastering:write

Riferimento degli endpoint

Tutte le rotte servite, per famiglia, con portata e quota. Fa fede il contratto completo.

Conversione (job) 6
Metodo Percorso Portata Quota
POST /jobsInvia una conversione: un file (multipart/form-data), un URL oppure testo grezzo/ChordPro (application/json). Con output=stems sono richieste anche la portata stems:write e una chiave API Premium, con una quota separata (200/giorno UTC). convert:write quota: conversione
GET /jobs/{id}Stato del job (fase, percentuale, passaggi). Da interrogare rispettando l'header Retry-After. convert:read quota: nessuna
DELETE /jobs/{id}Annulla un job e cancella i suoi file; rimborsa la quota solo se era ancora in coda. convert:write quota: nessuna
GET /jobs/{id}/eventsAlternativa al polling tramite Server-Sent Events: eventi state, done, error e ping di keep-alive. convert:read quota: nessuna
GET /jobs/{id}/resultScarica l'artefatto principale (o uno specifico tramite ?artifact=). Disponibile per 24 ore dalla creazione del job. convert:read quota: nessuna
GET /jobs/{id}/result/songbookIl pivot JSON canonico del carnet (accordi, testi, struttura), sempre disponibile una volta terminato il job. convert:read quota: nessuna

Formati 1
Metodo Percorso Portata Quota
GET /formatsRegistro delle coppie input/output effettivamente servite da questo server, con i relativi limiti (maxBytes, maxPages, maxDurationS). pubblico (nessuna chiave richiesta) quota: nessuna

Utilizzo e quote 1
Metodo Percorso Portata Quota
GET /me/usageIl saldo delle tue quote (conversione, lettura, scrittura, stems) e le portate che la tua identità può effettivamente esercitare, in un'unica chiamata. convert:read quota: nessuna

Carnet, lettura 4
Metodo Percorso Portata Quota
GET /me/songsElenca le canzoni del tuo carnet privato, con paginazione tramite cursore opaco; usa updatedSince per un'esportazione incrementale. carnet:read quota: lettura
GET /me/songs/{songId}Una canzone completa dal tuo carnet, inclusi accordi, testi e struttura. carnet:read quota: lettura
GET /me/playlistsElenca le playlist del tuo carnet, piatte e a più appartenenze, con la stessa paginazione delle canzoni. carnet:read quota: lettura
GET /me/playlists/{playlistId}Una playlist e le sue canzoni, in ordine, in forma sintetica. carnet:read quota: lettura

Carnet, scrittura 8
Metodo Percorso Portata Quota
POST /me/songsAggiunge una canzone al tuo carnet, lo stesso payload pivot restituito da una conversione. Imposta Idempotency-Key per evitare duplicati. carnet:write quota: scrittura
PUT /me/songs/{songId}Sostituisce interamente una canzone (dichiarativo); la crea con quell'id se non esiste ancora. carnet:write quota: scrittura
PATCH /me/songs/{songId}Aggiorna solo i campi inviati (tonalità, capotasto, bpm, playlistIds...); pubblica o rimuove anche la canzone dal tuo profilo. carnet:write quota: scrittura
DELETE /me/songs/{songId}Rimuove una canzone dal tuo carnet; eliminazione soft, idempotente, ed esce anche da tutte le playlist. carnet:write quota: scrittura
POST /me/playlistsCrea una playlist; songIds è l'elenco ordinato delle canzoni che contiene, conservato esattamente come inviato. carnet:write quota: scrittura
PUT /me/playlists/{playlistId}Sostituisce interamente una playlist (dichiarativo); songIds è obbligatorio. carnet:write quota: scrittura
PATCH /me/playlists/{playlistId}Rinomina, cambia l'emoji di copertina oppure riordina interamente le canzoni di una playlist. carnet:write quota: scrittura
DELETE /me/playlists/{playlistId}Elimina la playlist stessa; le sue canzoni restano nel tuo carnet e nelle loro altre playlist. carnet:write quota: scrittura

Social, sola lettura 5
Metodo Percorso Portata Quota
GET /users/{handle}Intestazione del profilo pubblico di un account tramite handle; un account privato che non segui restituisce una scheda chiusa (senza bio né conteggi). social:read quota: lettura
GET /users/{handle}/songsCanzoni che un account ha pubblicato sul proprio profilo; audioPlayable è vero solo se vi seguite reciprocamente. social:read quota: lettura
GET /users/{handle}/playlistsPlaylist pubblicate da un account; songCount conta solo ciò che puoi effettivamente vedere. social:read quota: lettura
GET /me/followersAccount che ti seguono; status=accepted (predefinito) oppure requested. social:read quota: lettura
GET /me/followingAccount che segui; status=requested elenca le richieste in sospeso verso account privati. social:read quota: lettura

Coda audio e stems 4
Metodo Percorso Portata Quota
POST /audioMette in coda l'analisi automatica di accordi e testi, seguita dall'allineamento, per una canzone già presente nel tuo carnet. Stessa coda dell'app; songId deve appartenerti. audio:write quota: nessuna
GET /queueLa coda di elaborazione audio del tuo account: attiva, in attesa (con rank) e i completati degli ultimi 7 giorni. queue:read quota: nessuna
GET /queue/{id}Un job della coda audio, solo il tuo; stesso 404 indistinguibile per un job sconosciuto o di un altro account. queue:read quota: nessuna
DELETE /queue/{id}Annulla uno dei job della tua coda audio; rimborsa solo se l'analisi non era ancora completata. audio:write quota: nessuna

Separazione stems 6
Metodo Percorso Portata Quota
GET /stem-tool/capabilitiesControlla disponibilità, limiti, modelli e quota di separazione stems del chiamante. convert:read quota: nessuna
GET /stem-tool/jobsElenca le separazioni private del chiamante con un cursore di paginazione facoltativo. convert:read quota: nessuna
POST /stem-tool/jobsCarica un file audio e separalo in due o quattro tracce. Le chiavi API richiedono Premium. stems:write quota: stems
GET /stem-tool/jobs/{id}Legge stato, avanzamento e file disponibili di una separazione del chiamante. convert:read quota: nessuna
DELETE /stem-tool/jobs/{id}Annulla una separazione del chiamante. stems:write quota: nessuna
GET /stem-tool/jobs/{id}/files/{name}Ottiene un URL firmato temporaneo per scaricare una traccia MP3 o un archivio ZIP. convert:read quota: nessuna

Con una chiave API, tutte queste rotte richiedono un account Premium; altrimenti la risposta è un 403 (api-premium-required). I limiti del chiamante sono in GET /stem-tool/capabilities.

Mastering 8
Metodo Percorso Portata Quota
GET /mastering/capabilitiesLimiti, intervalli delle impostazioni, obiettivi di loudness, preset integrati e diritto di rendering. pubblico (nessuna chiave richiesta) quota: nessuna
GET /mastering/presetsElenca i tuoi preset di mastering. mastering:read quota: nessuna
POST /mastering/presetsCrea un preset di mastering (Idempotency-Key obbligatoria). mastering:write quota: nessuna
DELETE /mastering/presets/{id}Elimina uno dei tuoi preset di mastering. mastering:write quota: nessuna
POST /mastering/jobsCarica un audio e avvia un rendering di mastering con un preset o con impostazioni. mastering:write quota: mastering (3/settimana gratis, illimitato con Premium)
GET /mastering/jobs/{id}Ottiene lo stato di un lavoro di mastering. mastering:read quota: nessuna
DELETE /mastering/jobs/{id}Annulla un lavoro di mastering. mastering:write quota: nessuna
GET /mastering/jobs/{id}/resultScarica il WAV masterizzato. mastering:read quota: nessuna

Rilevamento di musica IA 7 + 1 interna
Metodo Percorso Portata Quota
GET /ai-music/availabilityDisponibilità dello strumento, formati accettati e quote residue dell’account o del visitatore. pubblico (nessuna chiave richiesta) quota: nessuna
POST /ai-music/jobsInvia un file audio, un link Spotify, un link audio diretto o un ISRC. Un solo lavoro non concluso per account; YouTube non è supportato. audio:write quota: rilevamento IA
GET /ai-music/jobsRitrova la tua analisi in corso o la più recente. queue:read quota: nessuna
GET /ai-music/jobs/{id}Segue un’analisi e ne legge il resoconto. queue:read quota: nessuna
DELETE /ai-music/jobs/{id}Annulla un’analisi ed elimina i suoi file temporanei. audio:write quota: nessuna
GET /ai-music/historyCronologia privata degli ultimi 90 giorni, in pagine da 30; account richiesto, nessun audio conservato. queue:read quota: nessuna
DELETE /ai-music/history/{id}Elimina una scansione dalla tua cronologia; la quota di un’analisi riuscita non viene restituita. audio:write quota: nessuna
GET /ai-music/source/{token}/{filename}Indirizzo temporaneo riservato al fornitore del rilevamento, valido al massimo 180 secondi: nessun client lo chiama. interna quota: nessuna

Stato e specifica 2
Metodo Percorso Portata Quota
GET /healthStato del servizio e disponibilità per motore (OMR, audio, video...); nessuna autenticazione richiesta. pubblico (nessuna chiave richiesta) quota: nessuna
GET /openapi.jsonQuesto contratto, in formato JSON leggibile da una macchina. pubblico (nessuna chiave richiesta) quota: nessuna

Contratto completo e leggibile da una macchina, sempre sincronizzato con questa tabella:

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

Quote e limiti

Il saldo esatto è in GET /me/usage e nelle intestazioni X-Quota-* di ogni risposta.

Conversione

Account gratuito
6 / settimana
Premium
500 / mese
Senza chiave né sessione
3 / 24 h

Lo stesso contatore dell’esportazione del carnet nell’app.

Letture e scritture

al giorno UTCAccount gratuitoPremium
Letture (carnet, profili)200020.000
Scritture (carnet)2005000

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

Tracce separate via conversione

POST /jobs · output=stems

Serve una chiave API Premium: senza Premium la risposta è un 403 (premium-required).

Premium
200 al giorno UTC

Chiamando queste rotte garantisci di detenere i diritti sull’audio inviato.

Nel dettaglio
  • POST /jobs con output=stems restituisce uno .zip: vocals, accompaniment e manifest.json.
  • Portate richieste: stems:write e convert:write.
  • Un contatore a parte, distinto da quello delle conversioni, conteggiato per giorno UTC (non su 24 ore mobili).
  • Da non confondere con lo strumento Separazione stems (/stem-tool/*): lì una chiave API richiede un account Premium, con limiti propri (GET /stem-tool/capabilities).

Ottenere una chiave API

Crea un account Jam Jam gratuito, poi apri Impostazioni, Chiavi API nell'app (mobile o web) e crea una chiave. Inizia con jj_live_ e viene mostrata una sola volta: copiala subito. Fino a 5 chiavi per account, revocabili in qualsiasi momento.

Gestisci le mie chiavi API

Errori

Ogni errore, su ogni rotta, è un oggetto application/problem+json (RFC 9457) con un campo code stabile su cui un client può basare la propria logica: quota-exhausted, rate-limited, unsupported-pair, not-found... Il catalogo completo è nello schema OpenAPI (components.schemas.Problem).

Conservazione

I file caricati e i risultati generati vengono eliminati 24 ore dopo la creazione del job. Nulla viene conservato più a lungo, inclusi i job falliti. Richiedere un risultato oltre questa finestra restituisce 410 Gone.

Crediti open source

Questa API si basa su motori open source reali. Usati onestamente, citati per nome:

Modelli e dati

Rilevamento dei parlanti (Studio): modello di impronta vocale WeSpeaker ResNet34-LM, progetto WeNet (github.com/wenet-e2e/wespeaker), addestrato su VoxCeleb (VGG, Università di Oxford), licenza CC BY 4.0 (creativecommons.org/licenses/by/4.0/). Modificato da Jam Jam: pesi convertiti in mezza precisione.