Você tem um clipe de áudio curto ou um link direto para uma prévia de uma música e precisa identificar a faixa rapidamente para que possa lançar seu recurso musical esta semana. Ao final deste guia, você será capaz de reconhecer uma música por URL (ou por áudio bruto) usando a API Shazam no Zyla API Hub, analisar os campos que você precisa (artista, título, links do Apple Music, arte da capa) e integrá-lo ao seu serviço com um fluxo de trabalho mínimo e pronto para produção.
O que esta API faz e quando usá-la
A API Shazam no Zyla API Hub reconhece músicas a partir de amostras de áudio curtas e retorna metadados estruturados sobre a faixa. Aplicações típicas incluem:
- Identificação de músicas de fundo em uploads de usuários ou gravações ao vivo.
- Correspondência de prévias de faixas a partir de links para metadados canônicos para exibição ou vinculação de catálogo.
- Impulsionamento de recursos de descoberta musical (por exemplo, botões “O que está tocando?” em aplicativos).
Dois endpoints estão disponíveis para reconhecimento:
- Reconhecer Música (POST): envie uma amostra de áudio curta e receba a faixa reconhecida e os metadados.
- Reconhecer Música Por URL (GET): forneça uma URL direta para mídia (mp3, wav, ogg, mp4, wav ou avi) e receba os resultados do reconhecimento.
A API espera cerca de 3–5 segundos de áudio, não mais que 3 MB (idealmente ~500 KB). Uma abordagem prática é enviar pedaços até que você obtenha uma correspondência.
Começando no Zyla API Hub
Abra a listagem da API Shazam no Zyla API Hub, clique em Inscrever-se ou inicie o teste disponível, e copie sua chave da API. A autenticação é via Authorization: Bearer YOUR_API_KEY. A cobrança é por assinatura + cota (não pay-per-call). Para primeiras integrações, você pode usar o teste de 7 dias disponível na listagem. Verifique a página da API para opções de acesso e preços atuais.
Iniciar teste de 7 dias na API Shazam
Endpoints que você usará
1) Reconhecer Música (POST)
Identifique uma faixa enviando um arquivo de amostra de áudio curto (3–5 segundos, ≤ 3 MB; 500 KB é o ideal). A API retorna um conjunto de correspondências e um objeto track detalhado quando uma correspondência é encontrada.
- Método: POST
- URL: https://zylalabs.com/api/2219/shazam-api/2068/recognize-song
- Headers: Authorization: Bearer YOUR_API_KEY
- Parâmetros de solicitação: não documentados (envie áudio de acordo com as capacidades do seu cliente; a melhor prática é enviar pedaços até que uma correspondência seja encontrada)
Exemplo oficial de cURL:
curl -s -X POST "https://zylalabs.com/api/2219/shazam-api/2068/recognize-song"
-H "Authorization: Bearer YOUR_API_KEY"
Exemplo de resposta oficial:
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…
O que procurar na resposta:
matches: array com dados de tempo/desvio para a correspondência; pode ser usado para verificar a confiança heurística ao lado de outros campos.tagid,timestamp,timezone: contexto e tempo de reconhecimento (timezone é uma string como Europe/Moscow).track: o bloco de metadados principal:alias: alias da faixa semelhante a um slug.artists: array de colaboradores; útil para exibição e referência cruzada de catálogo.genres.primary: rótulo do gênero primário.hub: ações e links profundos (por exemplo, Apple Music play e abrir URIs).images: arte e imagens de fundo para UX.isrc: código internacional de gravação de som para correspondência de catálogo.key: identificador de chave da faixa Shazam.
2) Reconhecer Música Por URL (GET)
Identifique uma faixa fornecendo uma URL direta para um arquivo de áudio/vídeo. Os formatos suportados incluem mp3, wav, ogg, mp4, wav ou avi. Use um clipe curto: 3–5 segundos (≤ 3 MB, ~500 KB é o ideal). O envio de pedaços é recomendado até que uma correspondência seja encontrada.
- Método: GET
- URL: https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url
- Headers: Authorization: Bearer YOUR_API_KEY
- Parâmetros de consulta:
url(string, obrigatório): URL direta da mídia, por exemplo,https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40
A API retorna um array de correspondências e metadados da faixa semelhantes ao endpoint POST quando uma correspondência é encontrada.
Código para copiar e colar que você pode enviar
Exemplo em Python: Reconhecer uma música por URL
Este exemplo chama o endpoint Reconhecer Música Por URL e extrai alguns campos úteis para a interface do seu produto. Substitua YOUR_API_KEY pela sua chave da API Zyla.
import os
import urllib.parse
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
base = "https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url"
media_url = "https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40"
params = {"url": media_url}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(base, headers=headers, params=params, timeout=30)
resp.raise_for_status()
data = resp.json()
# Análise mínima com proteções
track = data.get("track", {})
title_alias = track.get("alias")
artists = [a.get("alias") for a in track.get("artists", []) if isinstance(a, dict)]
isrc = track.get("isrc")
images = track.get("images", {})
cover_art = images.get("coverart") or images.get("coverarthq")
hub = track.get("hub", {})
actions = hub.get("actions", []) if isinstance(hub, dict) else []
apple_preview = None
apple_open_uri = None
for a in actions:
if a.get("type") == "applemusicplay" and "id" in a:
# ID presente; a prévia pode estar disponível via outra ação 'uri'
continue
if a.get("type") == "uri" and a.get("name") == "apple":
apple_preview = a.get("uri")
break
# Fallback em hub.options para deeplinks se presentes
options = hub.get("options", []) if isinstance(hub, dict) else []
for opt in options:
for act in opt.get("actions", []):
if act.get("type") in ("applemusicopen", "uri"):
apple_open_uri = act.get("uri")
break
if apple_open_uri:
break
print("Matched alias:", title_alias)
print("Artists:", ", ".join([a for a in artists if a]))
print("ISRC:", isrc)
print("Cover art:", cover_art)
print("Apple preview:", apple_preview)
print("Apple Music deeplink:", apple_open_uri)
Notas que economizam tempo:
- Envie mídia curta: 3–5 segundos. Evite faixas completas; arquivos grandes desaceleram o reconhecimento e podem exceder a expectativa de tamanho.
- A API retorna o fuso horário como uma string (por exemplo, Europe/Moscow) e um
timestampnumérico. Se você armazenar resultados em cache, armazene tanto a URL da solicitação quanto um hash dos bytes da mídia para idempotência. hub.actionsehub.optionspodem conter prévias do Apple Music e links profundos; verifique ambos para preencher suas opções de reprodução e CTAs “Abrir em”.- Para renderização de imagem na interface, prefira
coverarthqquando presente; recorra acoverartouimages.backgroundse necessário.
Lista de verificação de produção para reconhecimento por URL
- Normalize as durações da mídia para ~3–5 segundos antes de chamar a API.
- Certifique-se de que a URL seja diretamente acessível (sem redirecionamentos que exijam cookies ou autenticação).
- Armazene correspondências positivas por
isrce chave Shazamkey; armazene negativas por um curto TTL para evitar misses repetidos. - Registre
tagidcom seu ID de solicitação para correlacionar tentativas de reconhecimento no lado do servidor. - Respeite a cota do seu plano (assinatura + cota, não pay-per-call). Para desenvolvimento inicial, use o teste de 7 dias na listagem; se precisar de mais volume, verifique a página da API para opções de acesso e preços atuais.
Como integrar isso ao seu aplicativo hoje
Fluxo de backend para reconhecimento baseado em URL
- Receba uma URL de mídia enviada pelo cliente (por exemplo, uma prévia mp3 curta).
- Valide a URL e verifique se ela aponta para um formato suportado (mp3, wav, ogg, mp4, wav ou avi).
- Chame Reconhecer Música Por URL com a URL codificada e seu cabeçalho de Autorização.
- Em caso de sucesso, mapeie
track.alias,track.artists,track.isrc, arte da capa detrack.images, e URIs jogáveis/deeplink detrack.hub. - Se não houver correspondência, tente novamente com um segmento diferente de 3–5 segundos (chunking) ou retorne um estado “sem correspondência” de forma elegante.
Fluxo de backend para amostras de áudio bruto
- Grave ou aceite um clipe curto de 3–5 segundos no lado do cliente e transmita-o para seu backend.
- Chame Reconhecer Música (POST). Melhor prática: envie pedaços até que uma correspondência seja encontrada.
- Extraia os mesmos campos que o fluxo de URL e persista os resultados para reutilização futura.
Chame a API de agentes de IA via MCP
Se você automatiza tarefas usando ferramentas compatíveis com MCP, pode fazer as mesmas chamadas de reconhecimento através do endpoint MCP da Zyla. Direcione seu agente para:
Use sua chave da API Zyla como de costume (Authorization: Bearer YOUR_API_KEY). A partir daí, instrua seu cliente MCP (por exemplo, dentro de um assistente orientado a código) a emitir um GET para o endpoint Reconhecer Música Por URL com o parâmetro url, ou um POST para Reconhecer Música para áudio bruto. Isso é útil para prototipagem rápida ou quando você deseja que um agente encadeie: “buscar prévia curta → reconhecer → pós-processar metadados → atualizar um banco de dados.”
Tratamento de erros, confiabilidade e dicas de uso de campos
- Tentativas: Para falhas de rede transitórias, uma única tentativa com jitter geralmente é suficiente. Evite loops quentes para permanecer dentro da cota.
- Correspondências parciais: Inspecione a presença e não-vazios do array
matchesao lado da disponibilidade de um objetotrackantes de atualizar sua interface. - Dados regionais: A resposta inclui um rótulo
timezone; não assuma que corresponde à localidade do usuário—trate-o como contexto para quando/onde o reconhecimento ocorreu. - Links jogáveis: A prévia do Apple Music e links profundos estão sob
hub.actionsehub.options. Confirme o tipo e o nome antes de exibir um botão.
Ideias de testes e validação
- Use um punhado de URLs de prévia conhecidas (mp3s curtos) e verifique se
isrc, aliases de artistas e arte da capa carregam conforme esperado em sua interface. - Teste diferentes fatias de 3–5 segundos da mesma faixa para confirmar que sua lógica de chunking tenta novamente de forma elegante quando uma correspondência não é encontrada na primeira tentativa.
- Grave clipes em volumes variados e com leve ruído de fundo para garantir que seu pré-processamento mantenha os arquivos dentro da diretriz de tamanho e duração.
Perguntas frequentes
Qual é a duração mínima do áudio?
Cerca de 3–5 segundos é recomendado. Os arquivos não devem ter mais de 3 MB, com ~500 KB considerado ideal.
Quais formatos são suportados para reconhecimento baseado em URL?
O endpoint Reconhecer Música Por URL suporta mp3, wav, ogg, mp4, wav ou avi, fornecidos através de uma URL direta e acessível.
Quais campos devo armazenar para futuras consultas?
Armazene track.isrc, track.key, aliases de artistas e quaisquer URLs de arte que você realmente renderiza, além de URIs jogáveis/deeplink que você exibe em sua interface. Inclua tagid e timestamp se precisar de auditabilidade.
Há um plano gratuito?
Não há plano gratuito. A API utiliza assinatura + cota (não pay-per-call). Para uso pela primeira vez, você pode acessar um teste de 7 dias na listagem. Verifique a página da API para opções de acesso e preços atuais.
Posso chamar isso de um assistente de codificação de IA?
Sim. Use o endpoint MCP da Zyla para permitir que seu agente faça as mesmas chamadas GET/POST com seu cabeçalho de Autorização.
Envie isso
Agora você tem os endpoints exatos e um padrão funcional para reconhecer músicas por URL ou áudio bruto, mapear metadados de faixas e exibir arte e links do Apple Music em seu produto. Comece com clipes curtos de 3–5 segundos, analise o bloco track e integre tentativas em pedaços para confiabilidade. Quando estiver pronto, obtenha sua chave e comece a testar com o teste de 7 dias na listagem: Iniciar teste de 7 dias na API Shazam.
Resposta oficial da API
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…
Resposta oficial da API
{"location":{"accuracy":0.01},"matches":[{"frequencyskew":0.0003222227,"id":"299052394","offset":48.000933593,"timeskew":0.0003027916}],"tagid":"75274D5F-ECCE-4104-B963-86CDC8059A13","timestamp":2453123822,"timezone":"Europe/Moscow","track":{"albumadamid":"495924692","alias":"freak-the-freak-out","artists":[{"adamid":"367602854","alias":"victorious-cast","id":"42"},{"adamid":"422753971","alias":"victoria-justice","id":"42"}],"genres":{"primary":"Soundtrack"},"highlightsurls":{},"hub":{"actions":[{"id":"495924694","name":"apple","type":"applemusicplay"},{"name":"apple","type":"uri","uri":"https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview115/v4/44/9b/fb/449bfb1f-8f65-fc6a-61e7-61e9b3e7cfba/mzaf_75952485968949724.plus.aac.ep.m4a"}],"displayname":"APPLE MUSIC","explicit":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/applemusic.png","options":[{"actions":[{"name":"hub:applemusic:deeplink","type":"applemusicopen","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"},{"name":"hub:applemusic:deeplink","type":"uri","uri":"https://music.apple.com/gb/album/freak-the-freak-out/495924692?i=495924694&mttnagencyid=s2n&mttnsiteid=125115&mttn3pid=Apple-Shazam&mttnsub1=Shazam_web&mttnsub2=5348615A-616D-3235-3830-44754D6D5973&itscg=30201&app=music&itsct=Shazam_web"}],"beacondata":{"providername":"applemusic","type":"open"},"caption":"OPEN IN","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"Open in Apple Music","overflowimage":"https://images.shazam.com/static/icons/hub/web/v5/applemusic-overflow.png","providername":"applemusic","type":"open"}],"type":"APPLEMUSIC"},"images":{"background":"https://is1-ssl.mzstatic.com/image/thumb/Features115/v4/09/9d/29/099d2956-660c-f175-2ae7-172272fdf971/mzl.whswoyuz.jpg/800x800cc.jpg","coverart":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","coverarthq":"https://is1-ssl.mzstatic.com/image/thumb/Music/2b/3c/ca/mzi.xkxafcng.jpg/400x400cc.jpg","joecolor":"b:151235p:e0abacs:e39577t:b78c94q:ba7b6a"},"isrc":"USSM11004546","key":"52910892","layout":"5","relatedtracksurl":"https://cdn.shazam.com/shazam/v3/en-US/GB/web/-/tracks/track-similarities-id-52910892?startFrom=0&pageSize=20&connected=","releasedate":"1…