您有一个短音频片段或直接链接到歌曲预览,您需要快速识别曲目,以便本周可以发布您的音乐功能。在本指南结束时,您将能够使用 Zyla API Hub 上的 Shazam API 通过 URL(或原始音频)识别歌曲,解析所需字段(艺术家、标题、Apple Music 链接、封面艺术),并将其集成到您的服务中,采用最小的、生产就绪的工作流程。
此 API 的功能及使用时机
Zyla API Hub 上的 Shazam API 识别来自短音频样本的音乐,并返回关于曲目的结构化元数据。典型应用包括:
- 识别用户上传或现场录音中的背景音乐。
- 将链接中的曲目预览与规范元数据匹配以进行显示或目录链接。
- 支持音乐发现功能(例如,应用中的“正在播放?”按钮)。
有两个端点可用于识别:
- 识别歌曲(POST):发送短音频样本并接收识别的曲目和元数据。
- 通过 URL 识别歌曲(GET):提供直接的媒体 URL(mp3、wav、ogg、mp4、wav 或 avi),并接收识别结果。
API 期望音频长度约为 3-5 秒,大小不超过 3 MB(最佳约为 500 KB)。一种实用的方法是发送数据块,直到找到匹配。
在 Zyla API Hub 上入门
打开 Zyla API Hub 上的 Shazam API 列表,点击订阅或开始可用的试用,并复制您的 API 密钥。身份验证通过 Authorization: Bearer YOUR_API_KEY。计费为订阅 + 配额(不是按调用计费)。对于首次集成,您可以使用列表上提供的 7 天试用。请查看 API 页面以获取当前访问选项和定价。
您将使用的端点
1) 识别歌曲(POST)
通过发送短音频样本文件(3-5 秒,≤ 3 MB;500 KB 是最佳)来识别曲目。当找到匹配时,API 返回一个匹配集和一个详细的 track 对象。
- 方法:POST
- URL:https://zylalabs.com/api/2219/shazam-api/2068/recognize-song
- 头部:Authorization: Bearer YOUR_API_KEY
- 请求参数:未记录(根据您的客户端能力发送音频;最佳实践是分块直到找到匹配)
官方 cURL 示例:
curl -s -X POST "https://zylalabs.com/api/2219/shazam-api/2068/recognize-song"
-H "Authorization: Bearer YOUR_API_KEY"
官方示例响应:
{"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…
在响应中要查找的内容:
matches:包含匹配的时间/偏差数据的数组;可以与其他字段一起用于验证置信度。tagid、timestamp、timezone:识别上下文和时间(时区是类似 Europe/Moscow 的字符串)。track:核心元数据块:alias:类似 slug 的曲目别名。artists:贡献者的数组;用于显示和目录交叉引用。genres.primary:主要流派标签。hub:操作和深层链接(例如,Apple Music 播放和打开 URI)。images:用于用户体验的艺术作品和背景图像。isrc:用于目录匹配的国际声音录制代码。key:Shazam 曲目关键标识符。
2) 通过 URL 识别歌曲(GET)
通过提供直接的音频/视频文件 URL 来识别曲目。支持的格式包括 mp3、wav、ogg、mp4、wav 或 avi。使用短片段:3-5 秒(≤ 3 MB,~500 KB 是最佳)。建议在找到匹配之前进行分块。
- 方法:GET
- URL:https://zylalabs.com/api/2219/shazam-api/7767/recognize-song-by-url
- 头部:Authorization: Bearer YOUR_API_KEY
- 查询参数:
url(字符串,必需):直接媒体 URL,例如https://p.scdn.co/mp3-preview/d4d9aa2c6b44dda05115e4e983e741caf4efde40
当找到匹配时,API 返回一个匹配数组和与 POST 端点类似的曲目元数据。
您可以发布的代码
Python 示例:通过 URL 识别歌曲
此示例调用通过 URL 识别歌曲的端点,并提取一些对您的产品 UI 有用的字段。将 YOUR_API_KEY 替换为您的 Zyla API 密钥。
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()
# 最小解析带保护
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 存在;预览可能通过另一个 'uri' 操作可用
continue
if a.get("type") == "uri" and a.get("name") == "apple":
apple_preview = a.get("uri")
break
# 如果存在,回退到 hub.options 以获取深层链接
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("匹配的别名:", title_alias)
print("艺术家:", ", ".join([a for a in artists if a]))
print("ISRC:", isrc)
print("封面艺术:", cover_art)
print("Apple 预览:", apple_preview)
print("Apple Music 深层链接:", apple_open_uri)
节省时间的注意事项:
- 发送短媒体:3-5 秒。避免完整曲目;大文件会减慢识别速度并可能超出大小预期。
- API 返回时区作为字符串(例如,Europe/Moscow)和数字
timestamp。如果您缓存结果,请存储请求 URL 和媒体字节的哈希以确保幂等性。 hub.actions和hub.options可以包含 Apple Music 预览和深层链接;检查两者以填充您的播放和“在中打开” CTA。- 对于 UI 图像渲染,优先使用
coverarthq(如果存在);回退到coverart或images.background。
通过 URL 识别的生产检查清单
- 在调用 API 之前将媒体时长标准化为 ~3-5 秒。
- 确保 URL 可直接获取(没有需要 cookies 或身份验证的重定向)。
- 通过
isrc和 Shazamkey缓存正匹配;对负匹配进行短 TTL 缓存以避免重复未命中。 - 记录
tagid和您的请求 ID 以便在服务器端关联识别尝试。 - 遵守您计划的配额(订阅 + 配额,而不是按调用计费)。对于初始开发,使用列表上的 7 天试用;如果您需要更多流量,请查看 API 页面以获取当前访问选项和定价。
如何将其接入您的应用程序
基于 URL 的识别的后端流程
- 接收客户端提交的媒体 URL(例如,短 mp3 预览)。
- 验证 URL 并确保其指向支持的格式(mp3、wav、ogg、mp4、wav 或 avi)。
- 使用编码的 URL 和您的授权头调用通过 URL 识别歌曲。
- 成功时,映射
track.alias、track.artists、track.isrc、来自track.images的艺术作品,以及来自track.hub的可播放/深层链接 URI。 - 如果没有匹配,请重试不同的 3-5 秒片段(分块)或返回优雅的“没有匹配”状态。
原始音频样本的后端流程
- 在客户端录制或接受短 3-5 秒片段并将其传输到您的后端。
- 调用识别歌曲(POST)。最佳实践:发送数据块直到找到匹配。
- 提取与 URL 流相同的字段并持久化结果以供将来重用。
通过 MCP 从 AI 代理调用 API
如果您使用兼容 MCP 的工具自动化任务,您可以通过 Zyla MCP 端点进行相同的识别调用。将您的代理指向:
像往常一样使用您的 Zyla API 密钥(Authorization: Bearer YOUR_API_KEY)。从那里,指示您的 MCP 客户端(例如,在代码导向助手中)对通过 URL 识别歌曲端点发出 GET 请求,或对原始音频发出 POST 请求。这对于快速原型设计或当您希望代理链式操作时非常有用:“获取短预览 → 识别 → 后处理元数据 → 更新数据库。”
错误处理、可靠性和字段使用提示
- 重试:对于瞬态网络故障,通常只需一次带抖动的重试即可。避免热循环以保持在配额内。
- 部分匹配:在更新 UI 之前检查
matches数组的存在和非空性,以及track对象的可用性。 - 区域数据:响应中包含
timezone标签;不要假设它与用户的区域匹配——将其视为识别发生时/发生地点的上下文。 - 可播放链接:Apple Music 预览和深层链接位于
hub.actions和hub.options下。在显示按钮之前确认类型和名称。
测试和验证想法
- 使用少量已知的预览 URL(短 mp3)并验证
isrc、艺术家别名和封面艺术是否按预期在您的 UI 中加载。 - 测试同一曲目的不同 3-5 秒片段,以确认您的分块逻辑在第一次尝试未找到匹配时优雅地重试。
- 以不同音量和轻微背景噪音录制片段,以确保您的预处理保持文件在大小指南和持续时间内。
常见问题
音频可以多短?
建议约 3-5 秒。文件大小不应超过 3 MB,~500 KB 被认为是最佳。
支持哪些格式进行基于 URL 的识别?
通过 URL 识别歌曲端点支持 mp3、wav、ogg、mp4、wav 或 avi,前提是通过直接、可获取的 URL 提供。
我应该存储哪些字段以供将来查找?
存储 track.isrc、track.key、艺术家别名,以及您实际渲染的任何艺术作品 URL,以及您在 UI 中显示的可播放/深层链接 URI。如果您需要审计能力,请包括 tagid 和 timestamp。
是否有免费计划?
没有免费计划。API 使用订阅 + 配额(不是按调用计费)。首次使用时,您可以访问列表上的 7 天试用。请查看 API 页面以获取当前访问选项和定价。
我可以从 AI 编码助手调用这个吗?
可以。使用 Zyla MCP 端点让您的代理使用您的授权头进行相同的 GET/POST 调用。
发布它
您现在拥有通过 URL 或原始音频识别歌曲的确切端点和工作模式,映射曲目元数据,并在您的产品中显示艺术作品和 Apple Music 链接。从短的 3-5 秒片段开始,解析 track 块,并接入分块重试以确保可靠性。当您准备好时,获取您的密钥并开始使用列表上的 7 天试用进行测试: 开始 Shazam API 的 7 天试用。
官方 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":"在中打开","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"在 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…
官方 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":"在中打开","colouroverflowimage":false,"image":"https://images.shazam.com/static/icons/hub/web/v5/overflow-open-option.png","listcaption":"在 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…