Douyin Creator Fetch Creator Hot Music Billboard
## Purpose Retrieve hot music rankings from the Douyin creator platform, filtered by category and time window and sorted by the selected criterion. ## Inputs All three inputs are optional integers: - `billboard_tag`: Category tag. Defaults to `0` for all categories. Other values must be obtained from category configuration; do not guess category IDs. - `order_key`: Sorting criterion. `1` = highest views (default), `2` = most likes, `4` = highest popularity, `5` = most submissions. - `time_filter`: Time window. `1` = 24 hours (default), `2` = 7 days, `3` = 30 days. No music ID or creator ID is required. ## Result Returns a response with hot music ranking content in `data`, which may be null. Individual ranking-entry fields are not specified in the available documentation. This is a ranking lookup, not an audio download. ## Example `{"billboard_tag":0,"order_key":1,"time_filter":1}` requests all categories, sorted by highest views, for the 24-hour window.
Pricing
| Condition | Charge |
|---|---|
| Each call | 2.07 credits/call |
Each call incurs a fixed charge of 2.07 credits/call. Charges are per query. A successful query is billed even if it returns no results.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
order_key | integer | No | 排序键/Order key (1=播放最高, 2=点赞最多, 4=热度最高, 5=投稿最多) | 1 |
time_filter | integer | No | 时间筛选/Time filter (1=24小时, 2=7天, 3=30天) | 1 |
billboard_tag | integer | No | 榜单标签/Billboard tag (0=全部,具体分类值可通过配置接口获取) | 0 |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_douyin_creator_fetch_creator_hot_music_billboard' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"billboard_tag": 0,
"order_key": 1,
"time_filter": 2
}
}'{
"code": 200,
"data": {
"item_list": [
{
"aweme_list": null,
"collection_count": 0,
"comment_count": 59078,
"cover": {
"url_list": [
"https://p26-sign.douyinpic.com/tos-cn-i-dy/d133d42bf424ce44cd12d17622d00cc3.png~noop.jpeg?lk3s=70809c85&x-expires=1794247200&x-signature=kFSFze3tF4bUAOiyf2aTfglxQhs%3D&from=1887476869"
]
},
"hot_involve_ratio": "",
"hot_involve_type": ""
}
]
},
"docs": "https://api.tikhub.io/#/Douyin-Creator-API/fetch_creator_hot_music_billboard_api_v1_douyin_creator_fetch_creator_hot_music_billboard_get",
"message": "Request successful. This request will incur a charge."
}This example shows part of the response. Copied content is valid JSON.

