Jam Jam
Un'API REST dietro lo stesso identico motore
L'API vive su jam-jam.org/api/v1 e fa girare la stessa pipeline dell'app web, dell'app mobile e di jam-jam.org/app/convert: un file caricato da uno qualsiasi di questi segue lo stesso codice e dà lo stesso risultato. La documentazione completa, con esempi curl e Python reali e un modo per generare una chiave, è su jam-jam.org/developers. La specifica OpenAPI 3.1, leggibile da una macchina, su jam-jam.org/api/v1/openapi.json, include una sequenza di chiamate consigliata per un agente o uno script, e jam-jam.org/llms.txt elenca ogni capacità qui sotto per un assistente che lo legge direttamente. Un server MCP (Model Context Protocol) ufficiale, @jam-jam/convert-mcp, espone la stessa API come cinque strumenti, list_formats, convert_file, convert_text, get_job e get_usage, per agenti compatibili con MCP come Claude Desktop, Claude Code o Cursor.
Una chiave, una quota, e nessuna coda da fare
Chiamare GET /formats non richiede alcuna autenticazione e restituisce ogni formato che questo server accetta oggi, con i suoi limiti di dimensione e durata, così uno script può controllare prima di caricare qualcosa. Tutto il resto si aspetta un'intestazione Authorization: Bearer, un token di sessione Supabase o una chiave API personale con prefisso jj_live_..., creata gratis in Impostazioni > Chiavi API dentro l'app. Senza chiave, la chiamata è trattata come anonima: 3 conversioni ogni 24 ore mobili. Un account gratuito porta questo a 10 a settimana, la stessa quota mobile che import ed export del carnet già condividono; Premium la porta a 500 al mese. Ogni risposta che consuma quota porta intestazioni X-Quota-* con il saldo esatto, e sia i file caricati sia i risultati vengono eliminati 24 ore dopo la creazione del job, che vada a buon fine o no.
Invia un job, poi seguilo o ascoltalo
Una conversione è un job, non una risposta immediata: POST /jobs con un file come multipart/form-data, o un URL o del testo incollato come JSON, restituisce un 202 con l'id del job. Da lì, GET /jobs/{id} interroga il suo stato (rispettando l'intestazione Retry-After), oppure GET /jobs/{id}/events apre un flusso Server-Sent Events dello stesso job per uno script che preferisce aspettare piuttosto che richiedere. Quando la fase arriva a done, GET /jobs/{id}/result scarica il file finito, e GET /jobs/{id}/result/songbook restituisce lo stesso risultato del pivot JSON proprio di Jam Jam, accordi, testo, sezioni, tonalità, tempo, pronto da leggere direttamente. Ogni errore torna come un corpo application/problem+json standard invece di un semplice codice di stato.
In entrata: una registrazione, un link, una scansione o una foto
Un file audio o video diventa un carnet con accordi, testo, tonalità e tempo già determinati, la stessa rilevazione che l'app fa girare su un microfono dal vivo o un file caricato, e da lì può andare direttamente in un video karaoke generato o in una base di accompagnamento. Una pagina incollata tramite URL, o una ricerca, si legge allo stesso modo di un sito di tablature dentro l'app. Un PDF o una foto, un foglio di accordi stampato, uno spartito scansionato, un intero carnet, una tablatura per chitarra, persino la foto di una lavagna scattata col telefono, passa per OCR e riconoscimento ottico della musica verso lo stesso pivot. Trasformare l'audio grezzo direttamente in notazione, in pentagramma o in tablatura, resta per ora dietro un filtro di qualità: quella direzione richiede una fonte che porti già la melodia, non una registrazione dal vivo.
In entrata: testo e notazione che hai già
I file ChordPro e OnSong, testo semplice con accordi o testo o una tablatura ASCII, un documento Word o RTF, diapositive, un foglio di calcolo o una scaletta in CSV, e l'HTML di una pagina web incollata si convertono tutti nello stesso carnet, perché un foglio di accordi arriva raramente in una sola forma. I file MusicXML e MIDI portano le proprie note e, quando le hanno, il proprio testo; un file di progetto Guitar Pro o MuseScore (.gp, .gpx, .mscz ed estensioni simili) raggiunge il carnet allo stesso modo, in beta; un file di testo sincronizzato (.lrc, .srt, .vtt, .ass) porta la sua sincronizzazione; e un file .jamsong o un export zippato si reimporta senza perdite, esattamente come è uscito da Jam Jam.
In uscita: qualsiasi formato serva davvero al job
Dallo stesso carnet, l'API esporta un PDF degli accordi, del testo o di una griglia vuota; un'immagine PNG, una pagina HTML, testo semplice, ChordPro, un'annotazione di accordi chords-lab o chords-csv, o solo tonalità e tempo; una versione trasportata o con capotasto; diagrammi di accordi per chitarra, ukulele, piano e gli altri strumenti coperti da Jam Jam; testo sincronizzato in .lrc o .srt; un video karaoke; una base di accompagnamento generata; o il file .jamsong senza perdite, pronto per la stampa su richiesta. Una volta che una melodia è davvero presente, importata da un MusicXML, un MIDI, un progetto Guitar Pro, uno spartito scansionato o una tablatura invece che da audio grezzo, lo stesso carnet si esporta anche come spartito, come PDF di tablatura per chitarra, come MIDI o come MusicXML, questi ultimi due in Premium.
Per la visione d'insieme della pipeline di conversione di Jam Jam, leggi l'articolo sulla conversione universale dei file.
Domande frequenti sull'API
Cos'è l'API di Jam Jam?
Un'API REST pubblica su jam-jam.org/api/v1 che fa girare il motore di conversione proprio di Jam Jam: mandale un file audio, un PDF, una foto, un link, MIDI, MusicXML, ChordPro o testo semplice, e ricevi un carnet strutturato (accordi, testo, tonalità, tempo) o un export portabile come un PDF, un video karaoke o una base di accompagnamento.
L'API è gratuita?
Sì, fino a una quota. Le chiamate anonime hanno 3 conversioni ogni 24 ore mobili, un account gratuito 10 a settimana, e Premium porta questo a 500 al mese. I file caricati e i risultati vengono eliminati 24 ore dopo l'esecuzione del job.
L'API può trasformare un file audio in accordi e testo?
Sì. Inviare un file audio o video con output: songbook restituisce accordi con marca temporale, tonalità, tempo e testo, la stessa rilevazione che fa girare l'app stessa. La notazione melodica completa a partire da audio grezzo (MIDI, MusicXML, un pentagramma o una tablatura) non ne fa parte: richiede una fonte che porti già la melodia.
Esiste un server MCP per gli agenti IA?
Sì, @jam-jam/convert-mcp espone la stessa API come cinque strumenti, list_formats, convert_file, convert_text, get_job e get_usage, così un agente compatibile con MCP come Claude Desktop, Claude Code o Cursor può chiamarla direttamente.
Dove ottengo una chiave API?
Crea un account Jam Jam gratuito, poi apri Impostazioni > Chiavi API nell'app (mobile o web) e generane una. Viene mostrata una sola volta, inizia con jj_live_, e può essere revocata in qualsiasi momento; fino a 5 chiavi per account.
Leggi il riferimento completo, con esempi curl e Python reali, su jam-jam.org/developers: