---
title: "设置歌单置顶状态"
method: PUT
path: "/playlists/{id}/pin"
tags: ["歌单管理"]
---

# 设置歌单置顶状态

`PUT /playlists/{id}/pin`

置顶/取消置顶歌单。置顶歌单在歌单列表中始终排在最前，多个置顶歌单按置顶时间倒序（最近置顶的排最前）。内置歌单（收藏、电台收藏）同样允许置顶，不做特殊限制。

## Path parameters

- `id` integer, required

## Request body

- ModelsSetPlaylistPinnedRequest
  - `pinned` boolean — 是否置顶歌单

## Response `200`

更新后的歌单

- ModelsPlaylist
  - `cover_url` string — 封面图片 URL
  - `created_at` string — 创建时间
  - `description` string — 歌单描述
  - `id` integer — 歌单 ID
  - `labels` string[] — 歌单标签，如 ["built_in"]
  - `name` string — 歌单名称
  - `pinned_at` string — 置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列
  - `song_count` integer — 歌曲数量
  - `sort_by` string — 视图排序字段：position/added_at/file_modified_at/title/artist/duration
  - `sort_order` string — 视图排序方向：asc/desc
  - `type` 'normal' | 'radio' — 歌单类型：normal/radio
  - `updated_at` string — 最后更新时间

## Other responses

- `400` — 无效的歌单ID或请求数据
- `404` — 歌单不存在
- `500` — 服务器错误

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/revisions/d5abb8b643e9/schema)