开发者文档 / 带货内容发布

搜索音乐

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

GET/v1/creator/tiktokshop/searchMusic

鉴权：: 请求头 x-api-key: <YOUR_API_KEY>；密钥仅保存在服务端。
成功判断：: HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

Query 参数

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

首次请求不传 pageToken 和 searchId；翻页时分别使用响应中的 nextPageToken 和 searchId。

favorited 按当前公司、用户及 TIKTOK_SHOP 回填；默认音乐列表可调用收藏音乐列表接口。

成功响应

{
  "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`	否	响应时间戳，单位毫秒。

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

参数、权限或授权错误需先修正。创建发布或生成任务超时后先查询已有任务，避免重复创建；不要因轮询中断而重复提交。

最后更新 · 2026-09-29