Skip to Content
平台能力抖快数据获取抖音 Top10 批量

抖音 Top10 批量

douyin-top10-batch 用于按 JSON 数组批量创建抖音 Top10 爆款视频榜单任务。调用方只提交结构化 JSON，不上传 Excel；Excel 解析应在调用方系统内完成。

能力信息

字段值
能力 Keydouyin-top10-batch
能力名称抖音 Top10 批量
能力类型workflow_execute
开放状态可通过统一开放能力执行入口调用

底层执行会复用平台任务、批量 item 编排、session-hub creator-data task、抖音 Top10 数据获取、资产写入和任务状态追踪能力。外部应用只感知平台 taskId、batchId、批量 item 状态和产出资产。

开始任务

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

请求体

剧名模式：

{
  "applicationId": "organization-application-id",
  "input": {
    "platform": "douyin",
    "items": [
      {
        "externalItemId": "row-1",
        "queryMode": "dramaTitle",
        "dramaTitle": "庆余年",
        "dramaType": "剧集",
        "directorOrActor": "张若昀",
        "tags": []
      }
    ]
  }
}

标签模式：

{
  "applicationId": "organization-application-id",
  "input": {
    "platform": "douyin",
    "items": [
      {
        "externalItemId": "row-2",
        "queryMode": "tag",
        "tags": ["古装", "动作"]
      }
    ]
  }
}

字段说明：

字段必填说明
applicationId否调用方团队应用 ID。传入时必须和 API Key 绑定的应用一致；不传时平台会使用 API Key 绑定的应用。
input.platform是当前使用 douyin。
input.items是批量任务列表，至少 1 条，最多 100 条。
input.items[].externalItemId否调用方系统内的行 ID 或幂等辅助标识，用于结果回看。
input.items[].queryMode否dramaTitle 或 tag，默认按剧名模式处理。
input.items[].dramaTitle剧名模式必填剧名或作品名。
input.items[].dramaType剧名模式必填剧集、短剧、电影等类型描述。
input.items[].directorOrActor剧名模式必填导演或演员。
input.items[].tags标签模式必填标签列表，最多 5 个。

开始任务成功表示平台已接收批量请求，并创建平台任务与批量执行记录。

{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "batchId": "batch-id",
    "status": "RUNNING",
    "totalCount": 2,
    "succeededCount": 0,
    "failedCount": 0,
    "pendingCount": 2,
    "items": [
      {
        "itemIndex": 1,
        "externalItemId": "row-1",
        "status": "RUNNING",
        "ossUrl": null,
        "artifact": null,
        "errorCode": null,
        "errorMessage": null,
        "startedAt": null,
        "finishedAt": null
      },
      {
        "itemIndex": 2,
        "externalItemId": "row-2",
        "status": "RUNNING",
        "ossUrl": null,
        "artifact": null,
        "errorCode": null,
        "errorMessage": null,
        "startedAt": null,
        "finishedAt": null
      }
    ],
    "createdAt": "2026-05-11T09:00:00Z",
    "updatedAt": "2026-05-11T09:00:01Z"
  }
}

Agent CLI 映射

Agent CLI 目录中，collect_douyin_top10_batch 会映射到本开放能力 douyin-top10-batch。CLI 指令用于 Agent / 数字员工大脑选择和补参数，不改变外部应用的开放 API 契约。

CLI 指令不是外部应用的 capabilityKey；外部应用仍调用本页的 douyin-top10-batch:execute。完整指令目录见 CLI 目录。

查询当前运行任务

douyin-top10-batch、douyin-top10-single、kuaishou-creator-info-single 和 kuaishou-creator-info-batch 共享底层 douyin-top10 数据获取队列。批量任务本身会串行执行内部 item，并作为父任务占用一个 slot；内部 item 不单独抢占队列。队列容量由平台配置决定，所有 slot 都被占满时，新的 Top10 或快手达人信息创建请求会返回 409。

GET /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-batch/current-task
Authorization: Bearer <sk-organization-application-api-key>
{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "running": true,
    "queueKey": "douyin-top10",
    "ownerCapabilityKey": "douyin-top10-single",
    "taskId": "platform-task-id",
    "executionId": "platform-execution-id",
    "status": "RUNNING",
    "acquiredAt": "2026-05-12T02:00:00Z",
    "activeCount": 2,
    "capacity": 2,
    "owners": [
      {
        "slotIndex": 0,
        "ownerCapabilityKey": "douyin-top10-single",
        "taskId": "platform-task-id",
        "executionId": "platform-execution-id",
        "status": "RUNNING",
        "acquiredAt": "2026-05-12T02:00:00Z"
      },
      {
        "slotIndex": 1,
        "ownerCapabilityKey": "kuaishou-creator-info-batch",
        "taskId": "platform-task-id-2",
        "executionId": "platform-execution-id-2",
        "status": "RUNNING",
        "acquiredAt": "2026-05-12T02:01:00Z"
      }
    ]
  }
}

顶层 ownerCapabilityKey/taskId/executionId/status/acquiredAt 保留为兼容字段，指向 owners[0]。新接入方应优先读取 activeCount、capacity 和 owners，用于判断共享队列当前占用情况。

如果 ownerCapabilityKey 是 douyin-top10-single，使用 GET /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-single/tasks/{taskId} 查询任务详情。

查询任务

GET /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-batch/tasks/{taskId}
Authorization: Bearer <sk-organization-application-api-key>

taskId 使用开始任务返回的 data.taskId，即平台任务 ID。

运行中：

{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "batchId": "batch-id",
    "status": "RUNNING",
    "totalCount": 2,
    "succeededCount": 1,
    "failedCount": 0,
    "pendingCount": 1,
    "items": [
      {
        "itemIndex": 1,
        "externalItemId": "row-1",
        "status": "SUCCEEDED",
        "ossUrl": "/api/open/v1/organizations/{orgId}/artifacts/artifact-row-1/download",
        "artifact": {
          "merge_update_event": {
            "event_time": "2026-05-11T09:18:00Z",
            "event_timezone": "Asia/Shanghai",
            "record_count": 1
          },
          "douyin_top_videos": [
            {
              "publish_date": "2026-05-08",
              "play_count": 1280000,
              "like_count": 86000,
              "creator_name": "影视观察员",
              "platform_id": "douyin_123456",
              "video_url": "https://www.douyin.com/video/0000000000000000001"
            }
          ]
        },
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-05-11T09:00:10Z",
        "finishedAt": "2026-05-11T09:18:00Z"
      },
      {
        "itemIndex": 2,
        "externalItemId": "row-2",
        "status": "RUNNING",
        "ossUrl": null,
        "artifact": null,
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-05-11T09:18:05Z",
        "finishedAt": null
      }
    ]
  }
}

全部成功：

{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "a09b851f-d6a0-469e-9dc5-06aaf7722ef6",
    "batchId": "913c0b5a-c3c6-4eb1-a3c2-c3ca7e4de93e",
    "status": "SUCCEEDED",
    "totalCount": 1,
    "succeededCount": 1,
    "failedCount": 0,
    "pendingCount": 0,
    "items": [
      {
        "itemIndex": 1,
        "externalItemId": "curl-row-1",
        "status": "SUCCEEDED",
        "ossUrl": "/api/open/v1/organizations/3c2b41c7-012b-46fc-bac2-7d5de5e504ed/artifacts/bf381f9d-bd1a-435a-9cfe-f6681bf33d42/download",
        "artifact": {
          "merge_update_event": {
            "event_time": "2026-05-16T01:43:55+08:00",
            "event_timezone": "Asia/Shanghai",
            "record_count": 10
          },
          "douyin_top_videos": [
            {
              "publish_date": "2020-06-27",
              "play_count": null,
              "like_count": 1831381,
              "video_name": "#隐秘的角落 结束了，但一起去爬山的约定还没有结束哦~走吧，来赴#秦昊爬山邀约  一起爬向山顶？",
              "creator_name": "秦昊",
              "platform_id": "MS4wLjABAAAAsT6xjcmOKw2NzKZSv2ujsr4HN9NdZmkjfavGO1tTUu9CYJYIIHp3fpfCT4f6908D",
              "video_url": null,
              "original_video_url": "https://www.douyin.com/video/6842857368078847244",
              "video_id": "6842857368078847244",
              "profile_bio": null,
              "creator_profile": {
                "name": "秦昊",
                "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAsT6xjcmOKw2NzKZSv2ujsr4HN9NdZmkjfavGO1tTUu9CYJYIIHp3fpfCT4f6908D",
                "following_count": null,
                "follower_count": null,
                "total_favorited": null,
                "latest_three_publish_dates": [
                  "2025-12-06",
                  "2025-07-27",
                  "2025-07-12"
                ]
              }
            },
            {
              "publish_date": "2025-05-14",
              "play_count": null,
              "like_count": 340921,
              "video_name": "近十年最好的悬疑剧？五万字精讲《隐秘的角落》合集P1 #好剧推荐 #抖音精选 #dou来聊影视  #隐秘的角落 #悬疑",
              "creator_name": "我是十四哦",
              "platform_id": "MS4wLjABAAAA6LML80MGtF5M7MNbMpM7rzbWJQvEIerHQUYNBYGU7iw",
              "video_url": null,
              "original_video_url": "https://www.douyin.com/video/7503948248986471731",
              "video_id": "7503948248986471731",
              "profile_bio": null,
              "creator_profile": {
                "name": "我是十四哦",
                "profile_url": "https://www.douyin.com/user/MS4wLjABAAAA6LML80MGtF5M7MNbMpM7rzbWJQvEIerHQUYNBYGU7iw",
                "following_count": null,
                "follower_count": null,
                "total_favorited": null,
                "latest_three_publish_dates": [
                  "2026-05-14",
                  "2026-05-14",
                  "2026-05-08"
                ]
              }
            }
          ]
        },
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-05-15T17:41:20.087336Z",
        "finishedAt": "2026-05-15T17:46:23.912689Z"
      }
    ],
    "createdAt": "2026-05-15T17:41:19.367975Z",
    "updatedAt": "2026-05-15T17:47:32.851632Z"
  }
}

items[].ossUrl 是单个 item 的结果文件入口，会继续保留；新增的 items[].artifact 是该 item 的实际 Top10 JSON 数据，不替代也不废弃 ossUrl。成功 item 会同时返回下载入口和结构化数据，douyin_top_videos[] 保持原始视频字段。上面的成功响应示例只截取了两条视频，真实响应会按 record_count 返回完整 Top10 数组。批次级统计直接读取 totalCount、succeededCount、failedCount、pendingCount；单个 item 的展示不需要依赖底层 session-hub 任务 ID 或原始快照。

产物 JSON 文件示例：

{
  "merge_update_event": {
    "event_time": "2026-05-11T09:18:00Z",
    "event_timezone": "Asia/Shanghai",
    "record_count": 1
  },
  "douyin_top_videos": [
    {
      "publish_date": "2026-05-08",
      "play_count": 1280000,
      "like_count": 86000,
      "creator_name": "影视观察员",
      "platform_id": "douyin_123456",
      "video_url": "https://www.douyin.com/video/0000000000000000001",
      "profile_bio": "电影剧集热点解析",
      "creator_profile": {
        "name": "影视观察员",
        "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAexample",
        "following_count": 128,
        "follower_count": 560000,
        "total_favorited": 2300000,
        "latest_three_publish_dates": [
          "2026-05-10",
          "2026-05-08",
          "2026-05-06"
        ]
      }
    }
  ]
}

部分失败：

{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "batchId": "batch-id",
    "status": "PARTIAL_FAILED",
    "totalCount": 2,
    "succeededCount": 1,
    "failedCount": 1,
    "pendingCount": 0,
    "items": [
      {
        "itemIndex": 1,
        "externalItemId": "row-1",
        "status": "SUCCEEDED",
        "ossUrl": "/api/open/v1/organizations/{orgId}/artifacts/artifact-row-1/download",
        "artifact": {
          "merge_update_event": {
            "event_time": "2026-05-11T09:18:00Z",
            "event_timezone": "Asia/Shanghai",
            "record_count": 1
          },
          "douyin_top_videos": [
            {
              "publish_date": "2026-05-08",
              "play_count": 1280000,
              "like_count": 86000,
              "creator_name": "影视观察员",
              "platform_id": "douyin_123456",
              "video_url": "https://www.douyin.com/video/0000000000000000001"
            }
          ]
        },
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-05-11T09:00:10Z",
        "finishedAt": "2026-05-11T09:18:00Z"
      },
      {
        "itemIndex": 2,
        "externalItemId": "row-2",
        "status": "FAILED",
        "ossUrl": null,
        "artifact": null,
        "errorCode": "UPSTREAM_TIMEOUT",
        "errorMessage": "session-hub task timed out",
        "startedAt": "2026-05-11T09:18:05Z",
        "finishedAt": "2026-05-11T09:38:05Z"
      }
    ],
    "createdAt": "2026-05-11T09:00:00Z",
    "updatedAt": "2026-05-11T09:38:05Z"
  }
}

部分失败时 data.status 为 PARTIAL_FAILED，批次级计数仍通过 totalCount、succeededCount、failedCount、pendingCount 返回。单个 item 的错误通过 items[].errorCode 和 items[].errorMessage 表达。

取消任务

运行中的批量任务可以使用平台任务 ID 取消：

POST /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-batch/tasks/{taskId}:cancel
Authorization: Bearer <sk-organization-application-api-key>

taskId 使用开始任务返回的 data.taskId。取消会停止当前正在运行的底层数据获取任务，将未完成的批量 item 标记为 CANCELED，释放共享 douyin-top10 队列，并把批量父任务更新为 CANCELED。已经成功或失败的 item 会保留原状态。

取消成功：

{
  "capabilityKey": "douyin-top10-batch",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "batchId": "batch-id",
    "status": "CANCELED",
    "totalCount": 2,
    "succeededCount": 1,
    "failedCount": 0,
    "pendingCount": 0,
    "items": [
      {
        "itemIndex": 1,
        "externalItemId": "row-1",
        "status": "SUCCEEDED",
        "ossUrl": "/api/open/v1/organizations/{orgId}/artifacts/artifact-row-1/download",
        "artifact": {
          "merge_update_event": {
            "event_time": "2026-05-11T09:18:00Z",
            "event_timezone": "Asia/Shanghai",
            "record_count": 1
          },
          "douyin_top_videos": [
            {
              "publish_date": "2026-05-08",
              "play_count": 1280000,
              "like_count": 86000,
              "creator_name": "影视观察员",
              "platform_id": "douyin_123456",
              "video_url": "https://www.douyin.com/video/0000000000000000001"
            }
          ]
        },
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-05-11T09:00:10Z",
        "finishedAt": "2026-05-11T09:18:00Z"
      },
      {
        "itemIndex": 2,
        "externalItemId": "row-2",
        "status": "CANCELED",
        "ossUrl": null,
        "artifact": null,
        "errorCode": "OPEN_CAPABILITY_CANCELLED_BY_USER",
        "errorMessage": "cancelled by open capability caller",
        "startedAt": "2026-05-11T09:18:05Z",
        "finishedAt": "2026-05-11T09:20:00Z"
      }
    ],
    "createdAt": "2026-05-11T09:00:00Z",
    "updatedAt": "2026-05-11T09:20:00Z"
  }
}

已处于 SUCCEEDED、FAILED 或 PARTIAL_FAILED 的终态批量任务不可取消，会返回 409。已取消任务重复调用取消接口时，会返回当前已取消状态。

常见错误

HTTP 状态场景
400缺少 platform、items 为空、items 超过 100 条，或单个 item 字段不符合当前 queryMode。
401未提供 Authorization: Bearer <sk-...>。
403API Key 不属于当前组织、未绑定该应用，或应用未获得本能力授权。
404能力不存在、未启用，或查询的任务不属于当前 API Key 绑定应用。
409当前应用已有 douyin-top10 共享队列任务仍在处理中，可能来自单条或批量能力。
501能力存在但后端 executor 尚未注册。
Last updated on
抖音 Top10 单条抖音热榜数据