# 收藏音乐

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[收藏音乐](/openapi/favorite-music)
- 完整接口约束：[JSON Schema](/openapi/operations/favoriteTikTokShopMusic.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/creator/tiktokshop/music/favorite

接口标识：`favoriteTikTokShopMusic`

收藏音乐。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `musicId` | body | string | 是 | 平台音乐 ID |
| `title` | body | string | 否 | 标题；收藏匹配时不区分大小写 |
| `author` | body | string | 否 | 音乐艺人或作者 |
| `duration` | body | string | 否 | 时长快照 |
| `coverUrl` | body | string | 否 | 封面 URL 快照 |
| `playUrl` | body | string | 否 | 播放/试听 URL 快照 |

请求格式：`application/json`

### 请求示例

```json
{
  "musicId": "7567668059796720391",
  "title": "Sunrise",
  "author": "Example artist",
  "duration": "30",
  "coverUrl": "https://cdn.example.com/music-cover.jpg",
  "playUrl": "https://cdn.example.com/music.mp3"
}
```

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 否 | — |
| `message` | string | 否 | — |
| `data` | null | 否 | — |
| `timestamp` | integer | 否 | — |

### 接入说明与限制

- 收藏音乐（幂等）。platform 由服务端固定为 TIKTOK_SHOP。
已存在则刷新传入的非空展示字段（title/author/duration/coverUrl/playUrl）。

coverUrl / playUrl 建议取搜索结果 coverThumb.urlList[0]、playUrl.urlList[0]。

### 相关接口

- [收藏音乐列表](/openapi/favorite-music-list) · [Markdown](/openapi/operations/listTikTokShopFavoriteMusic.md)
- [取消收藏音乐](/openapi/unfavorite-music) · [Markdown](/openapi/operations/unfavoriteTikTokShopMusic.md)