Skip to Content
平台能力抖快数据获取抖音热榜数据

抖音热榜数据

douyin-hot-rank-data 属于开放能力层的“数据”类能力，用于接收外部采集到的抖音热榜、日榜 JSON 数据，并支持获取当天或指定日期最新一份榜单数据。调用方只调用本开放能力；平台内部会使用基础能力 artifact.write 和 artifact.read 完成资产读写。

外部应用接入仍然只使用产品能力 Key douyin-hot-rank-data。Agent CLI 指令映射见本页下方和 CLI 目录；数字员工如何读取授权后的 CLI 视图见“数字员工 CLI 文档”。

该能力处理的是一次提交即一份数据的同步能力，不创建平台任务，也不占用 Top10 的异步任务队列。平台基础能力层不理解榜单业务结构，只负责资产读写；rank_type、rank_date、scraped_at 和读取时可选的 date 是“抖音热榜数据”这个开放能力层定义的入参契约，用于组织来源键和榜单查询，其他 JSON 字段都会作为原始数据内容保存。

能力信息

字段值
能力 Keydouyin-hot-rank-data
能力名称抖音热榜数据
分类数据
能力层级开放能力层
能力类型data_snapshot
开放状态可通过统一开放能力执行入口调用

Agent CLI 映射

Agent CLI 目录会把本产品能力中的业务动作整理成三条结构化指令：

CLI 指令外部应用调用方式
write_douyin_hot_rank_data调用 douyin-hot-rank-data:execute，提交榜单数据。
read_latest_douyin_hot_rank_data调用 douyin-hot-rank-data:execute，并在 input.action 中传 latest。
read_douyin_hot_rank_data_by_date调用 douyin-hot-rank-data:execute，并在 input.action 中传 latest 和 rank_date。

CLI 指令不是外部应用的 capabilityKey；外部应用仍只使用产品能力 Key douyin-hot-rank-data。完整指令目录见 CLI 目录。

提交榜单数据

POST /api/open/v1/organizations/{orgId}/capabilities/douyin-hot-rank-data:execute
Authorization: Bearer <sk-organization-application-api-key>
Content-Type: application/json

提交时直接把榜单 JSON 放在 input 中。平台会根据 rank_date 的业务日期做存储收敛：最近 30 天内的榜单快照会写入资产；早于北京时间今天往前 30 天或晚于今天的数据仍会被接收但不存储。每次提交时，平台也会顺带清理当前组织下已经存在的超期抖音热榜数据资产，避免历史快照持续累积。

{
  "applicationId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "input": {
    "rank_type": "hot",
    "rank_date": "2026-05-13",
    "scraped_at": "2026-05-13 15:40:30",
    "data": {
      "theatrical_movies": [
        {
          "category": "院线电影",
          "rank": 1,
          "title": "作品名",
          "heat": "2.4亿",
          "release_info": "2026-04-30 上映",
          "people": "主演名 / 主演名",
          "genre": "喜剧 / 爱情",
          "details": [
            "作品名",
            "2026-04-30 上映",
            "主演名 / 主演名",
            "喜剧 / 爱情"
          ],
          "source_text": "热度：2.4亿,2531人想看"
        }
      ],
      "series": [],
      "variety_shows": [],
      "online_movies": []
    }
  }
}

日榜提交同一个开放能力，只需要把 rank_type 改为 daily：

{
  "applicationId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "input": {
    "rank_type": "daily",
    "rank_date": "2026-05-13",
    "scraped_at": "2026-05-13 15:40:30",
    "items": [
      {
        "rank": 1,
        "title": "作品名",
        "heat": "2.4亿"
      }
    ]
  }
}

字段说明：

字段必填说明
applicationId否调用方团队应用 ID。传入时必须和 API Key 绑定的应用一致；不传时平台使用 API Key 绑定的应用。
input.action否获取实时榜单或历史榜单数据时传 latest；提交数据时不传。
input.rank_type是榜单类型。当前支持 hot 热榜、daily 日榜。该字段是本开放能力的业务契约，会参与默认 sourceKey 生成，并写入资产 metadata 的 rankType。
input.rank_date是榜单归属日期，格式为 yyyy-MM-dd。hot 和 daily 都以该字段作为业务日期，写入资产 metadata 的 rankDate，并用于查询和 30 天存储收敛。查询时不传则读取北京时间今天对应 rank_date 的最新一次数据。
input.date否读取榜单时的旧版兼容别名，格式为 yyyy-MM-dd。新接入请使用 rank_date。传入时读取指定 rank_date 的最新一次数据。指定日期只允许在最近一个月内，不能早于北京时间今天往前 1 个月，也不能晚于今天。
input.scraped_at是数据采集时间，格式为 yyyy-MM-dd HH:mm:ss。该字段会写入资产 metadata，并用于同一个 rank_date 下多份快照的新旧排序和默认 sourceKey 生成。
input.data / 其他业务字段否原始榜单数据内容。该开放能力按单份 JSON 数据保存，不拆成多个资产，也不要求必须存在 code、message 或固定的 data 结构。
input.sourceKey / input.snapshotKey否调用方自定义快照来源键。不传时默认生成 douyin-rank:{rank_type}:{rank_date}:yyyy-MM-ddTHH:mm:ss。
input.title否资产标题。不传时使用 Douyin Hot Rank {scraped_at} 或 Douyin Daily Rank {scraped_at}。

提交成功：

{
  "capabilityKey": "douyin-hot-rank-data",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "write",
    "sourceType": "DOUYIN_HOT_RANK_DATA",
    "sourceKey": "douyin-rank:hot:2026-05-13:2026-05-13T15:40:30",
    "rankType": "hot",
    "rankDate": "2026-05-13",
    "scrapedAt": "2026-05-13 15:40:30",
    "stored": true,
    "artifact": {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "capabilityKey": "douyin-hot-rank-data",
      "sourceType": "DOUYIN_HOT_RANK_DATA",
      "sourceKey": "douyin-rank:hot:2026-05-13:2026-05-13T15:40:30",
      "title": "Douyin Hot Rank 2026-05-13 15:40:30",
      "mimeType": "application/json",
      "fileName": "douyin-rank-hot-20260513T154030.json",
      "metadata": {
        "feature": "douyin-hot-rank-data",
        "platform": "douyin",
        "rankType": "hot",
        "rankDate": "2026-05-13",
        "scrapedAt": "2026-05-13 15:40:30",
        "sourceKey": "douyin-rank:hot:2026-05-13:2026-05-13T15:40:30",
        "categoryCount": 4,
        "itemCount": 1
      }
    },
    "artifacts": [
      {
        "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
        "sourceKey": "douyin-rank:hot:2026-05-13:2026-05-13T15:40:30"
      }
    ]
  }
}

rank_type + rank_date + scraped_at 共同构成该开放能力下榜单数据的默认业务身份。基础资产层不会为它们新增独立 artifact 表字段；该开放能力会把它们保存在资产 metadata 中，并体现在默认 sourceKey 里。比如同一榜单日期和采集时间下，热榜默认来源键是 douyin-rank:hot:2026-05-13:2026-05-13T15:40:30，日榜默认来源键是 douyin-rank:daily:2026-05-13:2026-05-13T15:40:30。

如果 rank_date 超出最近 30 天存储范围，提交仍返回成功，但 stored 为 false，且不会创建 artifact：

{
  "capabilityKey": "douyin-hot-rank-data",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "write",
    "sourceType": "DOUYIN_HOT_RANK_DATA",
    "sourceKey": null,
    "rankType": "hot",
    "rankDate": "2026-03-01",
    "scrapedAt": "2026-05-13 15:40:30",
    "stored": false,
    "message": "rank_date is outside the latest 30 days, snapshot was accepted but not stored",
    "artifact": null,
    "artifacts": []
  }
}

获取实时榜单

实时榜单返回当天最新一次提交的数据。日期按 rank_date 判断，当前使用北京时间自然日。传 rank_type = hot 获取今日热榜，传 rank_type = daily 获取今日日榜。

POST /api/open/v1/organizations/{orgId}/capabilities/douyin-hot-rank-data:execute
Authorization: Bearer <sk-organization-application-api-key>
Content-Type: application/json
{
  "applicationId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "input": {
    "action": "latest",
    "rank_type": "hot"
  }
}

获取今日日榜：

{
  "applicationId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "input": {
    "action": "latest",
    "rank_type": "daily"
  }
}

获取成功：

{
  "capabilityKey": "douyin-hot-rank-data",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "latest",
    "rankType": "hot",
    "date": "2026-05-13",
    "rankDate": "2026-05-13",
    "artifact": {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "capabilityKey": "douyin-hot-rank-data",
      "sourceType": "DOUYIN_HOT_RANK_DATA",
      "sourceKey": "douyin-rank:hot:2026-05-13:2026-05-13T15:40:30",
      "contentText": "{\"rank_type\":\"hot\",\"rank_date\":\"2026-05-13\",\"scraped_at\":\"2026-05-13 15:40:30\",\"data\":{}}",
      "mimeType": "application/json",
      "downloadUrl": "/api/organizations/{orgId}/artifacts/dddddddd-dddd-dddd-dddd-dddddddddddd/download"
    },
    "json": {
      "rank_type": "hot",
      "rank_date": "2026-05-13",
      "scraped_at": "2026-05-13 15:40:30",
      "data": {},
      "extra_field": "该开放能力会原样保存调用方传入的其他字段"
    }
  }
}

如果保存内容是合法 JSON，响应会同时返回解析后的 data.json，调用方无需再自行解析 contentText。

获取指定日期榜单

指定日期榜单复用 action = latest，额外传入 rank_date。平台会按该 rank_date 匹配已写入资产 metadata 中的 rankDate，并返回该榜单日期下按 scrapedAt 排序后的最新一次提交数据。rank_type = hot 返回热榜历史榜单数据，rank_type = daily 返回日榜历史榜单数据。历史查询只支持最近一个月内的数据，不能查询更早日期或未来日期。

{
  "applicationId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "input": {
    "action": "latest",
    "rank_type": "daily",
    "rank_date": "2026-05-13"
  }
}

指定日期获取成功：

{
  "capabilityKey": "douyin-hot-rank-data",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "latest",
    "rankType": "daily",
    "date": "2026-05-13",
    "rankDate": "2026-05-13",
    "artifact": {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "sourceType": "DOUYIN_HOT_RANK_DATA",
      "sourceKey": "douyin-rank:daily:2026-05-13:2026-05-13T15:40:30"
    },
    "json": {
      "rank_type": "daily",
      "rank_date": "2026-05-13",
      "scraped_at": "2026-05-13 15:40:30",
      "items": []
    }
  }
}

无历史数据时仍返回成功响应，不返回 404：

{
  "capabilityKey": "douyin-hot-rank-data",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "latest",
    "rankType": "hot",
    "date": "2026-05-13",
    "rankDate": "2026-05-13",
    "hasData": false,
    "message": "2026-05-13 热榜历史数据不存在",
    "artifact": null,
    "json": null
  }
}

错误响应

状态码场景
400缺少 applicationId、提交时缺少 rank_type、rank_date 或 scraped_at、rank_type 不是 hot/daily、rank_date 或 scraped_at 格式错误、读取时 rank_date/date 格式错误、rank_date/date 超出最近一个月范围，或 action 不是 write/latest。
401API Key 缺失或无效。
403应用未获得 douyin-hot-rank-data 能力授权。
502内部基础能力执行失败。
Last updated on
抖音 Top10 批量抖音热点宝数据