Jam Jam

API REST · OpenAPI 3.1 · Servidor MCP

API para desenvolvedores

Converta arquivos, links e textos em acordes e letras, depois leia e preencha seu caderno a partir de um script ou de um assistente.

Criar uma chave de API Conta gratuita · 6 conversões por semana Contrato OpenAPI
  • Plano gratuito
  • O mesmo motor do app
  • Servidor MCP oficial
URL base https://jam-jam.org/api/v1 openapi.json llms.txt

O que a API permite

Cada recurso é liberado por um escopo que você marca ao criar sua chave.

Conversão

Áudio, PDF, imagens, texto ou link para songbook, PDF, MIDI, MusicXML e mais.

convert:writeconvert:read

Caderno privado

Listar, ler, criar, editar e organizar suas músicas e playlists.

carnet:readcarnet:write

Perfis públicos

Somente leitura: perfis, músicas publicadas, seguidores. Nenhuma trilha de áudio.

social:read

Separação de faixas

Uma conversão (output=stems) separa a voz do acompanhamento; a ferramenta /stem-tool separa em duas ou quatro faixas. Com uma chave de API, ambas exigem uma conta Premium.

stems:write Chave de API Premium

Fila de áudio

Análise de acordes e letras na mesma fila do aplicativo.

audio:writequeue:read

Detecção de música IA

Um indício de geração para um arquivo, um link do Spotify, um link de áudio direto ou um ISRC.

Limites, cotas e privacidade

A música gerada por IA é cada vez mais comum. O Jam Jam ajuda a procurar indícios: cole um link ou envie um arquivo para obter um resultado indicativo.

Máx. 100 MB · Máx. 10 min · Spotify, link de áudio direto ou ISRC. YouTube não é aceito. Os links do Spotify podem ser analisados apenas a partir de um trecho.

Um arquivo em espera ou em processamento por conta. As contas Premium têm prioridade na fila.

Visitante: 2 análises/dia e 5/mês. Conta gratuita: 5/dia e 50/mês. Premium: 30/dia e 300/mês. Limites compartilhados entre site, app e API; falhas não contam. Reinício à meia-noite UTC e no primeiro dia do mês UTC.

O áudio é enviado ao nosso fornecedor SH Labs para análise. Segundo a política da empresa, não é armazenado nem usado para treinar modelos. Se estiver indisponível, o arquivo pode ser analisado localmente quando o serviço de reserva estiver disponível. Os arquivos temporários são excluídos após o processamento, erro ou cancelamento. A conta conserva nome ou link, data, status e resultado por 90 dias; visitantes, por 24 h. Os limites de visitantes usam um token e um identificador de rede pseudonimizado, sem armazenar o IP em texto claro.

Este índice não é uma probabilidade nem uma prova. Um índice baixo não garante uma origem humana.

Conhecer a ferramenta
audio:writequeue:read

Formatos compatíveis

A lista completa e atualizada, com os limites exatos e o que este servidor realmente oferece, está sempre em GET /formats. Em resumo:

Formatos de entrada

  • Arquivos de áudio e vídeo
  • PDF: acordes, letras, partitura, tablatura, cancioneiro digitalizado
  • Imagens: acordes, letras, partitura, tablatura
  • Texto simples, ChordPro, OnSong
  • Links e busca na web (page-link, web-search)
  • MusicXML, MIDI
  • JamSong, .zip misto, songbook (pivô)

Formatos de saída

  • Songbook (pivô JSON, sempre disponível)
  • PDF: acordes, letras, partitura, tablatura, grade
  • PNG, HTML, texto simples, ChordPro
  • chords-lab, chords-csv, tom e BPM
  • MusicXML, MIDI (Premium)
  • Letras sincronizadas: .lrc, .srt
  • Vídeo de karaokê (.mp4), áudio de acompanhamento, JamSong

Comece em quatro passos

A conversão é assíncrona: você envia, acompanha e recupera.

  1. Criar uma chave

    Configurações › Chaves de API. Prefixo jj_live_, exibida uma única vez, 5 chaves por conta, revogáveis.

    Gerenciar minhas chaves de API

  2. Enviar

    Um arquivo, uma URL ou texto, com o formato de saída desejado.

    POST /jobs

  3. Acompanhar

    Consulte respeitando Retry-After, ou abra um fluxo Server-Sent Events.

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

  4. Recuperar

    O resultado fica disponível por 24 horas; depois, 410 Gone.

    GET /jobs/{id}/result

Exemplos

Chamadas completas, prontas para copiar como estão.

Listar os formatos oferecidos por este servidorcurl

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

Converter um arquivo para 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

Converter uma URL em um cadernocurl

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

Acompanhar o progresso (SSE ou 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

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

Analisar uma música com a detecção de música de 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

Exemplos de código

Exemplos prontos para executar em curl, JavaScript e Python, de código aberto sob licença MIT:

jam-jam-api-examples

Assistentes e MCP

Um assistente lê o contrato e monta as próprias chamadas. O servidor MCP oficial oferece 42 ferramentas prontas.

Para agentes de IA

Leia primeiro GET /openapi.json: ele documenta a sequência de chamadas recomendada (descobrir formatos, enviar, acompanhar, buscar), autenticação e cotas em um bloco x-agent-guide pensado para ser interpretado por um modelo. O llms.txt deste site lista cada capacidade de conversão como uma entrada própria.

openapi.json llms.txt

Servidor MCP

Chave lida em JAM_JAM_API_KEY: só aparecem as ferramentas que os escopos dela permitem. Ele não segue ninguém, não curte nada e não publica nada por conta própria.

Claude DesktopClaude CodeCursor
Em detalhes

Um servidor oficial Model Context Protocol expõe a API a um assistente como 42 ferramentas com o prefixo jj_: conversão de arquivos e de texto, leitura e organização do seu caderno privado, leitura de perfis públicos, separação de stems, análise de áudio e fila, detecção de música com IA e masterização. Ele lê a sua chave de API da variável de ambiente JAM_JAM_API_KEY e mostra apenas as ferramentas que os escopos dessa chave permitem. Ele cuida do polling, dos erros de cota e da obtenção dos arquivos por você, para que um assistente como Claude Desktop, Claude Code ou Cursor possa converter um arquivo ou organizar o seu caderno sem que você escreva nenhum código HTTP. Ele nunca segue ninguém, nunca curte nada e nunca publica uma música por conta própria.

Instalaçãoshell 
npx -y @jam-jam/convert-mcp

Página do pacote no npm: npmjs.com/package/@jam-jam/convert-mcp

Configuração (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"
      }
    }
  }
}

Ferramentas e escopos necessários 42

Conversão

formatos, arquivos, texto e status dos jobs.

  • jj_list_formatssem escopo
  • jj_convert_fileconvert:write
  • jj_convert_textconvert:write
  • jj_get_jobconvert:read
Cota sem escopo

o que a chave pode fazer e quanto ainda resta.

  • jj_check_usage
Caderno privado, leitura carnet:read

músicas e playlists.

  • jj_list_songs
  • jj_get_song
  • jj_list_playlists
  • jj_get_playlist
Caderno privado, escrita carnet:write

criar, alterar e excluir músicas e playlists.

  • jj_create_song
  • jj_update_song
  • jj_delete_song
  • jj_create_playlist
  • jj_update_playlist
  • jj_delete_playlist
Perfis públicos, leitura social:read

cartões de perfil, músicas e playlists publicadas, seguidores e seguindo.

  • jj_get_profile
  • jj_list_profile_songs
  • jj_list_profile_playlists
  • jj_list_followers
  • jj_list_following
Separação de stems

capacidades, jobs e arquivos.

  • 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álise de áudio e fila

analisar um arquivo e listar, ler e cancelar jobs.

  • jj_audio_analyzeaudio:write
  • jj_queue_listqueue:read
  • jj_queue_get_jobqueue:read
  • jj_queue_cancel_jobaudio:write
Detecção de música com IA

disponibilidade, análise, histórico e jobs.

  • 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
Masterização

capacidades, predefinições, renderização, status e cancelamento dos jobs.

  • jj_mastering_capabilitiessem escopo
  • jj_list_mastering_presetsmastering:read
  • jj_create_mastering_presetmastering:write
  • jj_master_audiomastering:write
  • jj_mastering_get_jobmastering:read
  • jj_mastering_cancel_jobmastering:write

Referência de endpoints

Todas as rotas servidas, por família, com escopo e cota. O contrato completo é a referência oficial.

Conversão (jobs) 6
Método Caminho Escopo Cota
POST /jobsEnvie uma conversão: um arquivo (multipart/form-data), uma URL ou texto bruto/ChordPro (application/json). Com output=stems também são necessários o escopo stems:write e uma chave de API Premium, com uma cota própria (200/dia UTC). convert:write cota: conversão
GET /jobs/{id}Status do job (fase, porcentagem, etapas). Faça polling respeitando o cabeçalho Retry-After. convert:read cota: nenhuma
DELETE /jobs/{id}Cancela um job e apaga seus arquivos; reembolsa a cota apenas se ele ainda estivesse na fila. convert:write cota: nenhuma
GET /jobs/{id}/eventsAlternativa ao polling via Server-Sent Events: eventos state, done, error e ping de keep-alive. convert:read cota: nenhuma
GET /jobs/{id}/resultBaixa o artefato principal (ou um específico via ?artifact=). Disponível por 24 horas após a criação do job. convert:read cota: nenhuma
GET /jobs/{id}/result/songbookO pivô JSON canônico do caderno (cifras, letras, estrutura), sempre disponível assim que o job termina. convert:read cota: nenhuma

Formatos 1
Método Caminho Escopo Cota
GET /formatsRegistro dos pares de entrada/saída realmente oferecidos por este servidor, com os limites (maxBytes, maxPages, maxDurationS). público (sem necessidade de chave) cota: nenhuma

Uso e cotas 1
Método Caminho Escopo Cota
GET /me/usageO saldo das suas cotas (conversão, leitura, escrita, stems) e os escopos que sua identidade pode realmente exercer, em uma única chamada. convert:read cota: nenhuma

Caderno, leitura 4
Método Caminho Escopo Cota
GET /me/songsLista as músicas do seu caderno privado, paginadas por cursor opaco; use updatedSince para uma exportação incremental. carnet:read cota: leitura
GET /me/songs/{songId}Uma música completa do seu caderno, incluindo cifras, letras e estrutura. carnet:read cota: leitura
GET /me/playlistsLista as playlists do seu caderno, planas e com múltipla associação, com a mesma paginação das músicas. carnet:read cota: leitura
GET /me/playlists/{playlistId}Uma playlist e suas músicas, em ordem, em formato resumido. carnet:read cota: leitura

Caderno, escrita 8
Método Caminho Escopo Cota
POST /me/songsAdiciona uma música ao seu caderno, o mesmo payload pivô retornado por uma conversão. Defina Idempotency-Key para evitar duplicatas. carnet:write cota: escrita
PUT /me/songs/{songId}Substitui uma música por completo (declarativo); cria-a sob esse id se ainda não existir. carnet:write cota: escrita
PATCH /me/songs/{songId}Atualiza somente os campos enviados (tom, capotraste, bpm, playlistIds...); também publica ou despublica a música no seu perfil. carnet:write cota: escrita
DELETE /me/songs/{songId}Remove uma música do seu caderno; exclusão lógica, idempotente, e ela também sai de todas as playlists. carnet:write cota: escrita
POST /me/playlistsCria uma playlist; songIds é a lista ordenada de músicas que ela contém, mantida exatamente como enviada. carnet:write cota: escrita
PUT /me/playlists/{playlistId}Substitui uma playlist por completo (declarativo); songIds é obrigatório. carnet:write cota: escrita
PATCH /me/playlists/{playlistId}Renomeia, altera o emoji de capa ou reordena totalmente as músicas de uma playlist. carnet:write cota: escrita
DELETE /me/playlists/{playlistId}Exclui a própria playlist; suas músicas permanecem no seu caderno e em suas outras playlists. carnet:write cota: escrita

Social, somente leitura 5
Método Caminho Escopo Cota
GET /users/{handle}Cabeçalho do perfil público de uma conta pelo handle; uma conta privada que você não segue retorna um cartão fechado (sem bio, sem contadores). social:read cota: leitura
GET /users/{handle}/songsMúsicas que uma conta publicou em seu perfil; audioPlayable só é verdadeiro quando vocês se seguem mutuamente. social:read cota: leitura
GET /users/{handle}/playlistsPlaylists publicadas por uma conta; songCount conta apenas o que você realmente pode ver. social:read cota: leitura
GET /me/followersContas que seguem você; status=accepted (padrão) ou requested. social:read cota: leitura
GET /me/followingContas que você segue; status=requested lista as solicitações pendentes para contas privadas. social:read cota: leitura

Fila de áudio e stems 4
Método Caminho Escopo Cota
POST /audioColoca na fila a análise automática de cifras e letras, seguida do alinhamento, para uma música já presente no seu caderno. Mesma fila do app; songId deve ser sua. audio:write cota: nenhuma
GET /queueA fila de processamento de áudio da sua conta: ativa, em espera (com rank) e as concluídas dos últimos 7 dias. queue:read cota: nenhuma
GET /queue/{id}Um job da fila de áudio, apenas o seu; o mesmo 404 indistinguível para um job desconhecido ou de outra pessoa. queue:read cota: nenhuma
DELETE /queue/{id}Cancela um dos jobs da sua fila de áudio; reembolsa apenas se a análise ainda não tivesse sido concluída. audio:write cota: nenhuma

Separação de stems 6
Método Caminho Escopo Cota
GET /stem-tool/capabilitiesVerifica a disponibilidade, os limites, os modelos e a cota de separação de stems de quem fez a chamada. convert:read cota: nenhuma
GET /stem-tool/jobsLista as separações privadas de quem fez a chamada, com cursor de paginação opcional. convert:read cota: nenhuma
POST /stem-tool/jobsEnvia um arquivo de áudio para separá-lo em duas ou quatro faixas. Chaves de API exigem Premium. stems:write cota: stems
GET /stem-tool/jobs/{id}Consulta o status, o progresso e os arquivos disponíveis de uma separação sua. convert:read cota: nenhuma
DELETE /stem-tool/jobs/{id}Cancela uma separação sua. stems:write cota: nenhuma
GET /stem-tool/jobs/{id}/files/{name}Obtém uma URL assinada temporária para baixar uma faixa MP3 ou um arquivo ZIP. convert:read cota: nenhuma

Com uma chave de API, todas estas rotas exigem uma conta Premium; caso contrário, a resposta é um 403 (api-premium-required). Os limites de quem chama estão em GET /stem-tool/capabilities.

Masterização 8
Método Caminho Escopo Cota
GET /mastering/capabilitiesLimites, faixas dos ajustes, alvos de loudness, predefinições integradas e direito de renderização. público (sem necessidade de chave) cota: nenhuma
GET /mastering/presetsLista as suas predefinições de masterização. mastering:read cota: nenhuma
POST /mastering/presetsCria uma predefinição de masterização (Idempotency-Key obrigatória). mastering:write cota: nenhuma
DELETE /mastering/presets/{id}Exclui uma das suas predefinições de masterização. mastering:write cota: nenhuma
POST /mastering/jobsEnvia um áudio e inicia uma masterização com uma predefinição ou ajustes. mastering:write cota: mastering (3/semana grátis, ilimitado com Premium)
GET /mastering/jobs/{id}Obtém o estado de um trabalho de masterização. mastering:read cota: nenhuma
DELETE /mastering/jobs/{id}Cancela um trabalho de masterização. mastering:write cota: nenhuma
GET /mastering/jobs/{id}/resultBaixa o WAV masterizado. mastering:read cota: nenhuma

Detecção de música de IA 7 + 1 interna
Método Caminho Escopo Cota
GET /ai-music/availabilityDisponibilidade da ferramenta, formatos aceitos e cotas restantes da conta ou do visitante. público (sem necessidade de chave) cota: nenhuma
POST /ai-music/jobsEnvia um arquivo de áudio, um link do Spotify, um link de áudio direto ou um ISRC. Um único trabalho não concluído por conta; YouTube não é compatível. audio:write cota: detecção de IA
GET /ai-music/jobsEncontra sua análise em andamento ou a mais recente. queue:read cota: nenhuma
GET /ai-music/jobs/{id}Acompanha uma análise e lê o relatório. queue:read cota: nenhuma
DELETE /ai-music/jobs/{id}Cancela uma análise e apaga seus arquivos temporários. audio:write cota: nenhuma
GET /ai-music/historyHistórico privado dos últimos 90 dias, em páginas de 30; conta obrigatória, nenhum áudio guardado. queue:read cota: nenhuma
DELETE /ai-music/history/{id}Apaga uma análise do seu histórico; a cota de uma análise bem-sucedida não é devolvida. audio:write cota: nenhuma
GET /ai-music/source/{token}/{filename}Endereço temporário reservado ao provedor de detecção, válido por no máximo 180 segundos: nenhum cliente o chama. interna cota: nenhuma

Status e especificação 2
Método Caminho Escopo Cota
GET /healthStatus do serviço e prontidão por motor (OMR, áudio, vídeo...); não requer autenticação. público (sem necessidade de chave) cota: nenhuma
GET /openapi.jsonEste contrato, em JSON legível por máquina. público (sem necessidade de chave) cota: nenhuma

Contrato completo e legível por máquina, sempre sincronizado com esta tabela:

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

Cotas e limites

O saldo exato está em GET /me/usage e nos cabeçalhos X-Quota-* de cada resposta.

Conversão

Conta gratuita
6 / semana
Premium
500 / mês
Sem chave nem sessão
3 / 24 h

O mesmo contador da exportação do caderno no aplicativo.

Leituras e gravações

por dia UTCConta gratuitaPremium
Leituras (caderno, perfis)2.00020.000
Gravações (caderno)2005.000

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

Faixas separadas por conversão

POST /jobs · output=stems

Exige uma chave de API Premium: sem Premium, a resposta é um 403 (premium-required).

Premium
200 por dia UTC

Ao chamar essas rotas, você garante ter os direitos sobre o áudio enviado.

Em detalhes
  • POST /jobs com output=stems retorna um .zip: vocals, accompaniment e manifest.json.
  • Escopos necessários: stems:write e convert:write.
  • Um contador à parte, separado do das conversões, contado por dia UTC (e não em 24 horas móveis).
  • Não confunda com a ferramenta Separação de stems (/stem-tool/*): nela, uma chave de API exige uma conta Premium, com limites próprios (GET /stem-tool/capabilities).

Obter uma chave de API

Crie uma conta Jam Jam gratuita, depois abra Configurações, Chaves de API no app (mobile ou web) e crie uma chave. Ela começa com jj_live_ e é exibida apenas uma vez: copie-a imediatamente. Até 5 chaves por conta, revogáveis a qualquer momento.

Gerenciar minhas chaves de API

Erros

Todo erro, em toda rota, é um objeto application/problem+json (RFC 9457) com um campo code estável no qual um cliente pode basear sua lógica: quota-exhausted, rate-limited, unsupported-pair, not-found... O catálogo completo está no esquema OpenAPI (components.schemas.Problem).

Retenção

Os arquivos enviados e os resultados gerados são excluídos 24 horas após a criação do job. Nada é mantido por mais tempo, incluindo jobs com falha. Buscar um resultado após esse prazo retorna 410 Gone.

Créditos de código aberto

Esta API se apoia em motores de código aberto reais. Usados com honestidade, creditados pelo nome:

Modelos e dados

Detecção de interlocutores (Studio): modelo de impressão de voz WeSpeaker ResNet34-LM, projeto WeNet (github.com/wenet-e2e/wespeaker), treinado no VoxCeleb (VGG, Universidade de Oxford), licença CC BY 4.0 (creativecommons.org/licenses/by/4.0/). Modificado pelo Jam Jam: pesos convertidos para meia precisão.