Tienes un clip de audio corto o un enlace directo a una vista previa de una canción y necesitas identificar la pista rápidamente para poder lanzar tu función musical esta semana. Al final de esta guía, podrás reconocer una canción por URL (o por audio en bruto) utilizando la API de Shazam en Zyla API Hub, analizar los campos que necesitas (artista, título, enlaces de Apple Music, carátula) e integrarlo en tu servicio con un flujo de trabajo mínimo y listo para producción.
Qué hace esta API y cuándo usarla
La API de Shazam en Zyla API Hub reconoce música a partir de muestras de audio cortas y devuelve metadatos estructurados sobre la pista. Las aplicaciones típicas incluyen:
- Identificación de música de fondo en cargas de usuarios o grabaciones en vivo.
- Coincidencia de vistas previas de pistas desde enlaces a metadatos canónicos para visualización o vinculación de catálogos.
- Impulsar funciones de descubrimiento musical (por ejemplo, botones de “¿Qué está sonando?” en aplicaciones).
Hay dos puntos finales disponibles para reconocimiento:
- Reconocer Canción (POST): envía una muestra de audio corta y recibe la pista reconocida y metadatos.
- Reconocer Canción Por URL (GET): proporciona una URL directa a medios (mp3, wav, ogg, mp4, wav o avi) y recibe resultados de reconocimiento.
La API espera alrededor de 3–5 segundos de audio, no más de 3 MB (óptimamente ~500 KB). Un enfoque práctico es enviar fragmentos hasta que obtengas una coincidencia.
Comenzando en Zyla API Hub
Abre la lista de la API de Shazam en Zyla API Hub, haz clic en Suscribirse o comienza la prueba disponible, y copia tu clave API. La autenticación es a través de Authorization: Bearer YOUR_API_KEY. La facturación es por suscripción + cuota (no por llamada). Para las primeras integraciones, puedes usar la prueba de 7 días disponible en la lista. Consulta la página de la API para las opciones de acceso y precios actuales.
Comienza la prueba de 7 días en la API de Shazam
Puntos finales que usarás
1) Reconocer Canción (POST)
Identifica una pista enviando un archivo de muestra de audio corto (3–5 segundos, ≤ 3 MB; 500 KB es óptimo). La API devuelve un conjunto de coincidencias y un objeto track detallado cuando se encuentra una coincidencia.
- Método: POST
- URL: https://zylalabs.com/api/2219/shazam-api/2068/recognize-song
- Encabezados: Authorization: Bearer YOUR_API_KEY
- Parámetros de solicitud: no documentados (envía audio de acuerdo con las capacidades de tu cliente; la mejor práctica es fragmentar hasta que se encuentre una coincidencia)
Ejemplo oficial de cURL:
curl -s -X POST "https://zylalabs.com/api/2219/shazam-api/2068/recognize-song"
-H "Authorization: Bearer YOUR_API_KEY"
Ejemplo de respuesta 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…
Qué buscar en la respuesta:
matches: array con datos de tiempo/desviación para la coincidencia; se puede usar para verificar la confianza heurísticamente junto con otros campos.tagid,timestamp,timezone: contexto y tiempo de reconocimiento (timezone es una cadena como Europe/Moscow).track: el bloque de metadatos central:alias: alias de pista tipo slug.artists: array de contribuyentes; útil para visualización y referencia cruzada de catálogos.genres.primary: etiqueta de género principal.hub: acciones y enlaces profundos (por ejemplo, URI para reproducir y abrir en Apple Music).images: arte y fondos para la experiencia del usuario.isrc: código internacional de grabación de sonido para coincidencia de catálogos.key: identificador clave de pista de Shazam.
2) Reconocer Canción Por URL (GET)
Identifica una pista proporcionando una URL directa a un archivo de audio/video. Los formatos compatibles incluyen mp3, wav, ogg, mp4, wav o avi. Usa un clip corto: 3–5 segundos (≤ 3 MB, ~500 KB es óptimo). Se recomienda fragmentar hasta que se encuentre una coincidencia.
- Método: GET
- URL: https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url
- Encabezados: Authorization: Bearer YOUR_API_KEY
- Parámetros de consulta:
url(cadena, requerido): URL directa de medios, por ejemplo,https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40
La API devuelve un array de coincidencias y metadatos de pista similares al punto final POST cuando se encuentra una coincidencia.
Código para copiar y pegar que puedes enviar
Ejemplo en Python: Reconocer una canción por URL
Este ejemplo llama al punto final Reconocer Canción Por URL y extrae algunos campos útiles para la interfaz de usuario de tu producto. Reemplaza YOUR_API_KEY con tu clave API de 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álisis mínimo con salvaguardias
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; la vista previa puede estar disponible a través de otra acción 'uri'
continue
if a.get("type") == "uri" and a.get("name") == "apple":
apple_preview = a.get("uri")
break
# Revertir a hub.options para enlaces profundos si están 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("Alias coincidente:", title_alias)
print("Artistas:", ", ".join([a for a in artists if a]))
print("ISRC:", isrc)
print("Arte de portada:", cover_art)
print("Vista previa de Apple:", apple_preview)
print("Enlace profundo de Apple Music:", apple_open_uri)
Notas que ahorran tiempo:
- Envía medios cortos: 3–5 segundos. Evita pistas completas; archivos grandes ralentizan el reconocimiento y pueden exceder la expectativa de tamaño.
- La API devuelve la zona horaria como una cadena (por ejemplo, Europe/Moscow) y un
timestampnumérico. Si almacenas resultados en caché, guarda tanto la URL de solicitud como un hash de los bytes de medios para idempotencia. hub.actionsyhub.optionspueden contener vistas previas de Apple Music y enlaces profundos; verifica ambos para poblar tu reproducción y CTAs de “Abrir en”.- Para la representación de imágenes en la interfaz de usuario, prefiere
coverarthqcuando esté presente; recurre acoverartoimages.background.
Lista de verificación de producción para reconocer por URL
- Normaliza las duraciones de los medios a ~3–5 segundos antes de llamar a la API.
- Asegúrate de que la URL sea directamente accesible (sin redirecciones que requieran cookies o autenticación).
- Almacena coincidencias positivas por
isrcy clave de Shazamkey; almacena negativas por un corto TTL para evitar fallos repetidos. - Registra
tagidcon tu ID de solicitud para correlacionar intentos de reconocimiento del lado del servidor. - Respeta la cuota de tu plan (suscripción + cuota, no por llamada). Para el desarrollo inicial, utiliza la prueba de 7 días en la lista; si necesitas más volumen, consulta la página de la API para las opciones de acceso y precios actuales.
Cómo integrar esto en tu aplicación hoy
Flujo de backend para reconocimiento basado en URL
- Recibe una URL de medios enviada por el cliente (por ejemplo, una vista previa corta en mp3).
- Valida la URL y que apunte a un formato compatible (mp3, wav, ogg, mp4, wav o avi).
- Llama a Reconocer Canción Por URL con la URL codificada y tu encabezado de autorización.
- En caso de éxito, mapea
track.alias,track.artists,track.isrc, arte detrack.images, y URIs reproducibles/enlaces profundos detrack.hub. - Si no hay coincidencia, vuelve a intentar con un segmento diferente de 3–5 segundos (fragmentación) o devuelve un estado de “sin coincidencia” de manera elegante.
Flujo de backend para muestras de audio en bruto
- Graba o acepta un clip corto de 3–5 segundos del lado del cliente y transmítelo a tu backend.
- Llama a Reconocer Canción (POST). Mejor práctica: envía fragmentos hasta que se encuentre una coincidencia.
- Extrae los mismos campos que el flujo de URL y persiste los resultados para su reutilización futura.
Llama a la API desde agentes de IA a través de MCP
Si automatizas tareas utilizando herramientas compatibles con MCP, puedes hacer las mismas llamadas de reconocimiento a través del punto final MCP de Zyla. Dirige tu agente a:
Usa tu clave API de Zyla como de costumbre (Authorization: Bearer YOUR_API_KEY). Desde allí, instruye a tu cliente MCP (por ejemplo, dentro de un asistente orientado a código) para emitir un GET al punto final Reconocer Canción Por URL con el parámetro url, o un POST a Reconocer Canción para audio en bruto. Esto es útil para prototipos rápidos o cuando deseas que un agente encadene: “obtener vista previa corta → reconocer → post-procesar metadatos → actualizar una base de datos.”
Manejo de errores, confiabilidad y consejos de uso de campos
- Reintentos: Para fallos de red transitorios, un solo reintento con jitter suele ser suficiente. Evita bucles calientes para mantenerte dentro de la cuota.
- Coincidencias parciales: Inspecciona la presencia y no vacuidad del array
matchesjunto con la disponibilidad de un objetotrackantes de actualizar tu interfaz de usuario. - Datos regionales: La respuesta incluye una etiqueta
timezone; no asumas que coincide con la localidad del usuario, trátala como contexto de cuándo/dónde ocurrió el reconocimiento. - Enlaces reproducibles: La vista previa de Apple Music y los enlaces profundos se encuentran bajo
hub.actionsyhub.options. Confirma el tipo y el nombre antes de mostrar un botón.
Ideas para pruebas y validación
- Usa un puñado de URLs de vista previa conocidas (mp3 cortos) y verifica que
isrc, alias de artistas y arte de portada se carguen como se espera en tu interfaz de usuario. - Prueba diferentes segmentos de 3–5 segundos de la misma pista para confirmar que tu lógica de fragmentación vuelve a intentar de manera elegante cuando no se encuentra una coincidencia en el primer intento.
- Graba clips a diferentes volúmenes y con ruido de fondo leve para asegurarte de que tu preprocesamiento mantenga los archivos dentro de la guía de tamaño y duración.
Preguntas frecuentes
¿Qué tan corto puede ser el audio?
Se recomienda alrededor de 3–5 segundos. Los archivos no deben superar los 3 MB, siendo ~500 KB considerados óptimos.
¿Qué formatos son compatibles para el reconocimiento basado en URL?
El punto final Reconocer Canción Por URL admite mp3, wav, ogg, mp4, wav o avi, proporcionados a través de una URL directa y accesible.
¿Qué campos debo almacenar para futuras búsquedas?
Almacena track.isrc, track.key, alias de artistas y cualquier URL de arte que realmente renderices, además de URIs reproducibles/enlaces profundos que muestres en tu interfaz de usuario. Incluye tagid y timestamp si necesitas auditoría.
¿Hay un plan gratuito?
No hay plan gratuito. La API utiliza suscripción + cuota (no por llamada). Para el primer uso, puedes acceder a una prueba de 7 días en la lista. Consulta la página de la API para las opciones de acceso y precios actuales.
¿Puedo llamar a esto desde un asistente de codificación de IA?
Sí. Usa el punto final MCP de Zyla para permitir que tu agente haga las mismas llamadas GET/POST con tu encabezado de autorización.
Lánzalo
Ahora tienes los puntos finales exactos y un patrón de trabajo para reconocer canciones por URL o audio en bruto, mapear metadatos de pistas y mostrar arte y enlaces de Apple Music en tu producto. Comienza con clips cortos de 3–5 segundos, analiza el bloque track y conecta reintentos fragmentados para mayor confiabilidad. Cuando estés listo, obtén tu clave y comienza a probar con la prueba de 7 días en la lista: Comienza la prueba de 7 días en la API de Shazam.
Respuesta oficial de la 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":"Abrir en 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…
Respuesta oficial de la 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":"Abrir en 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…