Spotify Web API 指南:完整教程 (2026)
利用 Spotify API 构建音乐驱动的应用程序
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
Spotify Web API 指南:完整教程 (2026)
Spotify Web API 为开发者提供了访问 Spotify 庞大的音乐库、用户播放列表、播放控制、音频特征以及推荐引擎的能力。无论您是正在构建音乐发现应用、播放列表生成器、数据可视化工具,还是将 Spotify 集成到现有产品中,本指南都涵盖了入门所需的所有内容。
您可以使用 Spotify API 构建什么?
| 使用场景 | 使用的端点 (Endpoints) |
|---|---|
| 音乐搜索与发现 | Search, Recommendations, Browse |
| 播放列表创建与管理 | Playlists, Tracks |
| 用户资料与收听数据 | User Profile, Top Items, Recently Played |
| 音频分析 (BPM, 调性, 能量值) | Audio Features, Audio Analysis |
| 播放控制 | Player (需要 Premium 会员) |
| 艺人与专辑数据 | Artists, Albums |
入门指南
第一步:创建 Spotify 开发者账号
- 访问 developer.spotify.com。
- 使用您的 Spotify 账号登录(免费版或 Premium 版均可)。
- 导航至 Dashboard(控制台)。
- 点击 Create App。
- 填写应用名称、描述和重定向 URI(Redirect URI,开发环境可使用
http://localhost:3000/callback)。 - 记下您的 Client ID 和 Client Secret。
第二步:理解身份验证流程 (Authentication Flows)
Spotify 使用 OAuth 2.0,根据您的使用场景提供几种不同的流程:
| 流程 | 使用场景 | 是否需要用户登录 | 是否可访问用户数据 |
|---|---|---|---|
| Client Credentials | 服务器对服务器,仅限公开数据 | 否 | 否 |
| Authorization Code | 需要用户数据的 Web 应用 | 是 | 是 |
| Authorization Code + PKCE | 单页应用 (SPA) 和移动应用 | 是 | 是 |
| Implicit Grant | 已弃用(请勿使用) | 是 | 是 |
对于大多数应用程序,您将使用 Client Credentials(用于公开数据)或 Authorization Code + PKCE(用于用户特定数据)。
第三步:安装 SDK
Python:
pip install spotipy
Node.js:
npm install spotify-web-api-node
或者在任何语言中使用原始 HTTP 请求 —— 该 API 是基于 REST 的。
身份验证:Client Credentials 流程
当您只需要公开数据(搜索、艺人信息、专辑曲目)且不需要访问任何用户的私人数据时,请使用此流程。
Python 代码示例(使用 Spotipy)
import spotipy
from spotipy.oauth2 import SpotifyClientCredentials
client_credentials_manager = SpotifyClientCredentials(
client_id="your-client-id",
client_secret="your-client-secret",
)
sp = spotipy.Spotify(client_credentials_manager=client_credentials_manager)
# 搜索曲目
results = sp.search(q="artist:Radiohead", type="track", limit=10)
for track in results["tracks"]["items"]:
print(f"{track['name']} - {track['album']['name']}")
Node.js 示例
import SpotifyWebApi from "spotify-web-api-node";
const spotifyApi = new SpotifyWebApi({
clientId: "your-client-id",
clientSecret: "your-client-secret",
});
// 获取访问令牌
const data = await spotifyApi.clientCredentialsGrant();
spotifyApi.setAccessToken(data.body["access_token"]);
// 搜索曲目
const results = await spotifyApi.searchTracks("artist:Radiohead", { limit: 10 });
results.body.tracks.items.forEach((track) => {
console.log(`${track.name} - ${track.album.name}`);
});
cURL 示例
# 获取访问令牌
TOKEN=$(curl -s -X POST https://accounts.spotify.com/api/token \
-u "your-client-id:your-client-secret" \
-d "grant_type=client_credentials" | jq -r '.access_token')
# 搜索曲目
curl -s "https://api.spotify.com/v1/search?q=artist:Radiohead&type=track&limit=5" \
-H "Authorization: Bearer $TOKEN" | jq '.tracks.items[] | {name, album: .album.name}'
身份验证:带有 PKCE 的 Authorization Code 流程
当您需要访问用户特定数据(如他们的播放列表、最常收听的主题或播放控制)时,请使用此流程。
使用 Flask 的 Python 示例
import spotipy
from spotipy.oauth2 import SpotifyOAuth
from flask import Flask, redirect, request, session
app = Flask(__name__)
app.secret_key = "your-secret-key"
SCOPE = "user-read-recently-played user-top-read playlist-modify-public"
@app.route("/login")
def login():
sp_oauth = SpotifyOAuth(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="http://localhost:3000/callback",
scope=SCOPE,
)
auth_url = sp_oauth.get_authorize_url()
return redirect(auth_url)
@app.route("/callback")
def callback():
sp_oauth = SpotifyOAuth(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="http://localhost:3000/callback",
scope=SCOPE,
)
code = request.args.get("code")
token_info = sp_oauth.get_access_token(code)
session["token_info"] = token_info
return redirect("/top-tracks")
@app.route("/top-tracks")
def top_tracks():
token_info = session.get("token_info")
sp = spotipy.Spotify(auth=token_info["access_token"])
results = sp.current_user_top_tracks(limit=20, time_range="medium_term")
tracks = []
for track in results["items"]:
tracks.append(f"{track['name']} by {track['artists'][0]['name']}")
return "<br>".join(tracks)
常用 API 端点
搜索 (Search)
在曲目、艺人、专辑、播放列表和播客中进行搜索:
# 搜索曲目
results = sp.search(q="genre:electronic year:2025-2026", type="track", limit=20)
# 搜索艺人
results = sp.search(q="Daft Punk", type="artist", limit=5)
# 进行多种类型搜索
results = sp.search(q="jazz", type="track,artist,album", limit=10)
获取音频特征 (Audio Features)
音频特征提供了曲目的音乐属性:
# 获取单个曲目的音频特征
features = sp.audio_features("track-id-here")[0]
print(f"BPM: {features['tempo']}")
print(f"Key: {features['key']}")
print(f"Energy: {features['energy']}")
print(f"Danceability: {features['danceability']}")
print(f"Valence (mood): {features['valence']}")
音频特征值及其含义:
| 特征 | 范围 | 低值代表 | 高值代表 |
|---|---|---|---|
energy |
0.0-1.0 | 平静、安静 | 响亮、激烈 |
danceability |
0.0-1.0 | 难以随之起舞 | 容易起舞 |
valence |
0.0-1.0 | 悲伤、愤怒 | 快乐、欢快 |
tempo |
BPM | 慢速 | 快速 |
acousticness |
0.0-1.0 | 电子音效 | 原声/不插电 |
instrumentalness |
0.0-1.0 | 包含人声 | 纯乐器 |
speechiness |
0.0-1.0 | 音乐 | 纯人声/语言 |
获取推荐 (Recommendations)
使用种子曲目、艺人或流派构建推荐引擎:
# 根据种子曲目和目标音频特征获取推荐
recommendations = sp.recommendations(
seed_tracks=["track-id-1", "track-id-2"],
seed_genres=["electronic"],
limit=20,
target_energy=0.8,
target_danceability=0.7,
min_tempo=120,
max_tempo=140,
)
for track in recommendations["tracks"]:
print(f"{track['name']} by {track['artists'][0]['name']}")
管理播放列表 (Playlists)
创建、读取和修改播放列表:
# 创建一个新的播放列表
playlist = sp.user_playlist_create(
user=sp.current_user()["id"],
name="My AI-Generated Playlist",
public=True,
description="Created with the Spotify API",
)
# 向播放列表添加曲目
track_uris = ["spotify:track:id1", "spotify:track:id2", "spotify:track:id3"]
sp.playlist_add_items(playlist["id"], track_uris)
# 获取播放列表的曲目
tracks = sp.playlist_tracks("playlist-id")
for item in tracks["items"]:
track = item["track"]
print(f"{track['name']} by {track['artists'][0]['name']}")
控制播放(需要 Premium 会员)
# 获取当前播放的曲目
current = sp.current_playback()
if current and current["is_playing"]:
track = current["item"]
print(f"Now playing: {track['name']} by {track['artists'][0]['name']}")
# 切到下一首
sp.next_track()
# 设置音量
sp.volume(75)
# 在特定设备上开始播放
devices = sp.devices()
device_id = devices["devices"][0]["id"]
sp.start_playback(device_id=device_id, uris=["spotify:track:track-id"])
构建播放列表生成器
这是一个根据心情参数创建播放列表的完整示例:
import spotipy
from spotipy.oauth2 import SpotifyOAuth
MOOD_PRESETS = {
"workout": {
"seed_genres": ["electronic", "hip-hop"],
"target_energy": 0.9,
"target_danceability": 0.8,
"min_tempo": 130,
},
"chill": {
"seed_genres": ["ambient", "chill"],
"target_energy": 0.3,
"target_valence": 0.4,
"max_tempo": 100,
},
"focus": {
"seed_genres": ["classical", "ambient"],
"target_instrumentalness": 0.8,
"target_energy": 0.4,
"target_speechiness": 0.0,
},
"party": {
"seed_genres": ["pop", "dance"],
"target_energy": 0.85,
"target_danceability": 0.9,
"target_valence": 0.8,
},
}
def create_mood_playlist(sp, mood, num_tracks=25):
if mood not in MOOD_PRESETS:
raise ValueError(f"Unknown mood: {mood}. Options: {list(MOOD_PRESETS.keys())}")
params = MOOD_PRESETS[mood]
recommendations = sp.recommendations(limit=num_tracks, **params)
track_uris = [track["uri"] for track in recommendations["tracks"]]
user_id = sp.current_user()["id"]
playlist = sp.user_playlist_create(
user=user_id,
name=f"{mood.capitalize()} Mix - AI Generated",
description=f"A {mood} playlist generated with the Spotify API.",
)
sp.playlist_add_items(playlist["id"], track_uris)
return playlist["external_urls"]["spotify"]
# 使用示例
sp = spotipy.Spotify(auth_manager=SpotifyOAuth(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="http://localhost:3000/callback",
scope="playlist-modify-public",
))
url = create_mood_playlist(sp, "workout")
print(f"Playlist created: {url}")
速率限制与最佳实践
速率限制 (Rate Limits)
Spotify 使用滑动窗口速率限制。具体限制尚未公开记录,但通用准则如下:
| 准则 | 建议 |
|---|---|
| 每秒请求数 | 大多数端点保持在 10 次以下 |
| 批量端点 | 使用批量版本(例如,在一个调用中获取多个曲目) |
| 429 错误重试 | 遵循 Retry-After 响应头 |
| 令牌刷新 | 在过期前刷新(令牌有效期通常为 1 小时) |
错误处理
from spotipy.exceptions import SpotifyException
import time
def safe_request(func, *args, max_retries=3, **kwargs):
for attempt in range(max_retries):
try:
return func(*args, **kwargs)
except SpotifyException as e:
if e.http_status == 429:
retry_after = int(e.headers.get("Retry-After", 5))
print(f"Rate limited. Waiting {retry_after}s...")
time.sleep(retry_after)
elif e.http_status == 401:
print("Token expired. Refreshing...")
# 处理令牌刷新逻辑
raise
else:
raise
raise Exception("Max retries exceeded")
分页 (Pagination)
许多 Spotify 端点返回分页结果。务必处理分页以获取完整数据:
def get_all_playlist_tracks(sp, playlist_id):
tracks = []
results = sp.playlist_tracks(playlist_id, limit=100)
while results:
tracks.extend(results["items"])
results = sp.next(results) if results["next"] else None
return tracks
可用的 OAuth 范围 (Scopes)
| 范围 | 访问权限 |
|---|---|
user-read-private |
用户的订阅详情和国家/地区 |
user-read-email |
用户的邮箱地址 |
user-top-read |
用户最常听的艺人和曲目 |
user-read-recently-played |
用户最近播放的曲目 |
playlist-read-private |
用户的私人播放列表 |
playlist-modify-public |
创建和编辑公开播放列表 |
playlist-modify-private |
创建和编辑私人播放列表 |
user-read-playback-state |
当前播放状态 |
user-modify-playback-state |
控制播放(仅限 Premium) |
user-library-read |
用户保存的曲目和专辑 |
user-library-modify |
保存和移除曲目及专辑 |
仅请求您的应用程序需要的范围。用户在授权期间会看到所请求的权限,如果您请求过多权限,用户可能会拒绝。
结语
Spotify Web API 是目前文档最全且对开发者最友好的音乐 API 之一。无论您是构建简单的播放列表生成器,还是复杂的音乐分析平台,搜索、推荐、音频特征和用户数据的结合都为您提供了坚实的基础。
如果您正在开发将音乐与 AI 生成媒体相结合的应用 —— 例如创建可视化效果、数字人视频或 AI 生成的专辑封面 —— 请关注 Hypereal AI。Hypereal 提供了一套统一的 API,用于图像生成、视频创作和数字人生成,并支持按需付费。
