Spotify Web API 指南：完整教程 (2026)

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 开发者账号

1. 访问 developer.spotify.com。
2. 使用您的 Spotify 账号登录（免费版或 Premium 版均可）。
3. 导航至 Dashboard（控制台）。
4. 点击 Create App。
5. 填写应用名称、描述和重定向 URI（Redirect URI，开发环境可使用 http://localhost:3000/callback）。
6. 记下您的 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，用于图像生成、视频创作和数字人生成，并支持按需付费。