Skip to Content
平台能力抖快数据获取抖音 Top10 单条

抖音 Top10 单条

douyin-top10-single 用于创建单次抖音 Top10 爆款视频榜单任务，适合外部应用按一次查询条件异步生成榜单。

能力信息

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

底层执行会复用平台已有的 session-hub creator-data task、任务队列和资产写入能力。外部应用只需要调用本能力，不需要自行写入任务或资产。对外返回和查询使用平台任务 ID，session-hub 任务 ID 属于内部实现细节。

开始任务

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

请求体

剧名模式：

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

标签模式：

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

字段说明：

字段必填说明
applicationId否调用方团队应用 ID。传入时必须和 API Key 绑定的应用一致；不传时平台会使用 API Key 绑定的应用。
input.platform是当前使用 douyin。
input.queryMode否dramaTitle 或 tag，默认按剧名模式处理。
input.dramaTitle剧名模式必填剧名或作品名。
input.dramaType剧名模式必填剧集、短剧、电影等类型描述。
input.directorOrActor剧名模式必填导演或演员。
input.tags标签模式必填标签列表，最多 5 个。

开始任务成功表示平台已接收请求，并创建平台任务、底层执行和资产写入链路。

{
  "capabilityKey": "douyin-top10-single",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "RUNNING",
    "request": {
      "platform": "douyin",
      "queryMode": "dramaTitle",
      "dramaTitle": "庆余年",
      "dramaType": "剧集",
      "directorOrActor": "张若昀",
      "tags": []
    },
    "result": null,
    "error": null,
    "artifacts": [],
    "createdAt": "2026-05-11T09:00:00Z",
    "updatedAt": "2026-05-11T09:00:01Z"
  }
}

顶层 message/code 表示本次开放能力入口调用成功；data.status 表示异步任务状态。

Agent CLI 映射

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

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

查询当前运行任务

douyin-top10-single、douyin-top10-batch、kuaishou-creator-info-single 和 kuaishou-creator-info-batch 共享底层 douyin-top10 数据获取队列。队列容量由平台配置决定；所有 slot 都被占满时，新的 Top10 或快手达人信息创建请求会返回 409。调用方可以先查询当前队列 owner：

GET /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-single/current-task
Authorization: Bearer <sk-organization-application-api-key>
{
  "capabilityKey": "douyin-top10-single",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "running": true,
    "queueKey": "douyin-top10",
    "ownerCapabilityKey": "douyin-top10-batch",
    "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-batch",
        "taskId": "platform-task-id",
        "executionId": "platform-execution-id",
        "status": "RUNNING",
        "acquiredAt": "2026-05-12T02:00:00Z"
      },
      {
        "slotIndex": 1,
        "ownerCapabilityKey": "kuaishou-creator-info-single",
        "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-batch，使用 GET /api/open/v1/organizations/{orgId}/capabilities/douyin-top10-batch/tasks/{taskId} 查询任务详情。

查询任务

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

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

运行中：

{
  "capabilityKey": "douyin-top10-single",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "RUNNING",
    "request": {
      "platform": "douyin",
      "queryMode": "dramaTitle",
      "dramaTitle": "庆余年",
      "dramaType": "剧集",
      "directorOrActor": "张若昀",
      "tags": []
    },
    "result": null,
    "error": null,
    "artifacts": []
  }
}

成功后：

{
  "capabilityKey": "douyin-top10-single",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "SUCCEEDED",
    "request": {
      "platform": "douyin",
      "queryMode": "dramaTitle",
      "dramaTitle": "庆余年",
      "dramaType": "剧集",
      "directorOrActor": "张若昀",
      "tags": []
    },
    "result": {
      "merge_update_event": {
        "event_time": "2026-05-15T23:23:06+08:00",
        "event_timezone": "Asia/Shanghai",
        "record_count": 10
      },
      "douyin_top_videos": [
        {
          "publish_date": "2019-01-30",
          "play_count": null,
          "like_count": 1390444,
          "video_name": "#电影流浪地球 空手套吴京？厉害了我的郭导儿",
          "creator_name": "电影流浪地球",
          "platform_id": "MS4wLjABAAAAMQDBQRv7bTUqgAnq0DkWRxZL7wxrm4r6A3tjTUgd_2g",
          "video_url": null,
          "original_video_url": "https://www.douyin.com/video/6652151927222193415",
          "video_id": "6652151927222193415",
          "profile_bio": null,
          "creator_profile": {
            "name": "电影流浪地球",
            "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAMQDBQRv7bTUqgAnq0DkWRxZL7wxrm4r6A3tjTUgd_2g",
            "following_count": null,
            "follower_count": 0,
            "total_favorited": 0,
            "latest_three_publish_dates": []
          }
        }
      ]
    },
    "error": null,
    "artifacts": [
      {
        "id": "artifact-id",
        "taskId": "platform-task-id",
        "artifactType": "DOCUMENT",
        "title": "douyin_top10_result.json",
        "mimeType": "application/json",
        "downloadUrl": "/api/open/v1/organizations/{orgId}/artifacts/artifact-id/download"
      }
    ],
    "createdAt": "2026-05-11T09:00:00Z",
    "updatedAt": "2026-05-11T09:02:00Z"
  }
}

成功后的 data.artifacts[].downloadUrl 会继续作为结果文件下载入口保留；data.result 是额外返回的实际 Top10 JSON 数据，结构和批量能力中单个成功 item 的 items[].artifact 一致。data.result.douyin_top_videos[] 会保留原始视频字段；video_id 仍保留为抖音侧业务 ID，不会被平台改写。

取消任务

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

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

taskId 使用开始任务返回的 data.taskId。取消会停止底层数据获取任务，释放共享 douyin-top10 队列，并把平台任务状态更新为已取消。

取消成功：

{
  "capabilityKey": "douyin-top10-single",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "CANCELLED",
    "request": {
      "platform": "douyin",
      "queryMode": "dramaTitle",
      "dramaTitle": "庆余年",
      "dramaType": "剧集",
      "directorOrActor": "张若昀",
      "tags": []
    },
    "result": null,
    "error": {
      "code": "OPEN_CAPABILITY_CANCELLED_BY_USER",
      "message": "cancelled by open capability caller"
    },
    "artifacts": []
  }
}

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

产物 JSON 文件示例：

{
  "merge_update_event": {
    "event_time": "2026-05-11T09:02:00Z",
    "event_timezone": "Asia/Shanghai",
    "record_count": 2
  },
  "douyin_top_videos": [
    {
      "publish_date": "2026-05-08",
      "play_count": 1280000,
      "like_count": 86000,
      "video_name": "示例视频标题 1",
      "creator_name": "影视观察员",
      "platform_id": "douyin_123456",
      "video_url": null,
      "original_video_url": "https://www.douyin.com/video/0000000000000000001",
      "video_id": "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"
        ]
      }
    },
    {
      "publish_date": "2026-05-07",
      "play_count": null,
      "like_count": 74200,
      "video_name": "示例视频标题 2",
      "creator_name": "剧集放映室",
      "platform_id": "douyin_789012",
      "video_url": null,
      "original_video_url": "https://www.douyin.com/video/0000000000000000002",
      "video_id": "0000000000000000002",
      "profile_bio": null,
      "creator_profile": {
        "name": "剧集放映室",
        "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAexample2",
        "following_count": null,
        "follower_count": 410000,
        "total_favorited": 1680000,
        "latest_three_publish_dates": [
          "2026-05-09",
          "2026-05-07",
          "2026-05-05"
        ]
      }
    }
  ]
}

失败后 data.status 为 FAILED，data.error 会携带底层失败信息，result 保持为 null。任务结果和产出资产会进入平台任务、资产视角，并带上触发它的 applicationId。

常见错误

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