# 搜索音乐

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

## GET /v1/creator/tiktokshop/searchMusic

接口标识：`searchTikTokShopMusic`

按关键词搜索达人可用的 TikTok 音乐。翻页时复用响应中的 searchId 和 nextPageToken。

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

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

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | query | integer | 是 | 创作者账号 ID |
| `keyword` | query | string | 是 | 搜索关键词 |
| `language` | query | string | 否 | BCP-47 语言标签 |
| `pageSize` | query | integer | 是 | 每页数量 |
| `pageToken` | query | string \| null | 否 | 分页令牌，首次请求传 null 或不传 |
| `region` | query | string | 否 | ISO 3166-1 alpha-2 地区代码 |
| `searchId` | query | string | 否 | 首次搜索返回的搜索会话 ID，翻页时复用 |

### 成功响应

```json
{
  "code": 0,
  "data": {
    "music": [
      {
        "id": "7567668059796720391",
        "title": "original sound",
        "author": "Ivan",
        "duration": "15",
        "coverThumb": {
          "urlList": [
            "https://cdn.example.com/music-cover.jpg"
          ]
        },
        "playUrl": {
          "urlList": [
            "https://cdn.example.com/music-preview.mp3"
          ]
        },
        "favorited": false
      }
    ],
    "nextPageToken": "next_page_token",
    "hasMore": true,
    "searchId": "music_search_xxx"
  },
  "message": "success"
}
```

### 响应字段

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

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.music` | object[] | 是 | — |
| `data.music[].id` | string | 是 | — |
| `data.music[].title` | string | 是 | — |
| `data.music[].author` | string | 是 | — |
| `data.music[].duration` | string | 是 | — |
| `data.music[].coverThumb` | object | 是 | — |
| `data.music[].coverThumb.urlList` | string[] | 是 | — |
| `data.music[].playUrl` | object | 是 | — |
| `data.music[].playUrl.urlList` | string[] | 是 | — |
| `data.music[].favorited` | boolean | 否 | — |
| `data.nextPageToken` | string | 是 | — |
| `data.hasMore` | boolean | 是 | — |
| `data.searchId` | string | 是 | — |
| `timestamp` | integer | 否 | 响应时间戳，单位毫秒。 |

### 接入说明与限制

- 首次请求不传 pageToken 和 searchId；翻页时分别使用响应中的 nextPageToken 和 searchId。
- favorited 按当前公司、用户及 TIKTOK_SHOP 回填；默认音乐列表可调用收藏音乐列表接口。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。

### 相关接口

- [收藏音乐列表](/openapi/favorite-music-list) · [Markdown](/openapi/operations/listTikTokShopFavoriteMusic.md)
- [收藏音乐](/openapi/favorite-music) · [Markdown](/openapi/operations/favoriteTikTokShopMusic.md)
- [创建发布任务](/openapi/create-post) · [Markdown](/openapi/operations/createCreatorPost.md)
- [编辑发布记录](/openapi/update-post) · [Markdown](/openapi/operations/updateCreatorPost.md)