Skip to Content
平台能力抖快数据获取TikHub API Service

TikHub API Service

tikhub-api-service 是 FunClaw 对外开放的 TikHub API 产品能力。调用方只使用这个 capability key，并通过 input.action 选择 FunClaw 定义的业务 action，例如当前已开放的 douyin.top.search 和 kuaishou.account.search。

TikHub 原生 endpoint 由平台内部的 tikhub-api-adapter 和业务 workflow 编排。douyin.search.fetch_video_search_v2、kuaishou.app.search_user_v2 这类 raw endpoint action 是 INTERNAL_ONLY 实现细节，不作为普通外部应用的调用契约。

能力信息

字段值
能力 Keytikhub-api-service
能力名称TikHub API Service
分类数据
能力层级开放能力层
能力类型data_service
开放状态可通过统一开放能力执行入口创建异步任务，并通过统一任务查询入口轮询结果

业务 Action

action状态说明
douyin.top.search已开放抖音 Top 内容搜索。内部由 DouyinTopTikHubWorkflowService 编排 TikHub 原生 API，并返回 FunClaw 标准 Top schema。
kuaishou.account.search已开放快手账号资料和作品摘要搜索。内部由 KuaishouAccountTikHubWorkflowService 编排 TikHub 原生 API，并返回旧快手达人信息兼容 schema。

执行抖音 Top 搜索

POST /api/open/v1/organizations/{orgId}/capabilities/tikhub-api-service:execute
Authorization: Bearer <sk-organization-application-api-key>
Content-Type: application/json
{
  "applicationId": "organization-application-id",
  "input": {
    "action": "douyin.top.search",
    "params": {
      "query": "短剧",
      "limit": 10,
      "publishTime": "不限",
      "videoDuration": "不限",
      "sortType": "最多点赞",
      "contentType": "视频",
      "requiredText": [],
      "strictQueryPart": [],
      "skipVideoStatistics": false,
      "skipProfileEnrichment": false
    }
  }
}

字段说明：

字段必填说明
applicationId否调用方团队应用 ID。传入时必须和 API Key 绑定的应用一致；不传时平台使用 API Key 绑定的应用。
input.action是当前对外开放 douyin.top.search。
input.params.query是搜索关键词，会映射到 TikHub keyword。建议传入完整主题词，例如剧名、品牌名、人物名或组合关键词。
input.params.limit否最多返回条数，默认 10，范围 1 到 50。这是“最多返回”，不是保证返回；上游召回不足、去重或调用方二次过滤后，实际结果可能少于 limit。
input.params.publishTime否发布时间过滤，会映射到 TikHub publish_time。可选 不限、一天内、一周内、半年内，默认 不限。对应 TikHub 值分别为 0、1、7、180。
input.params.videoDuration否视频时长过滤，会映射到 TikHub filter_duration。可选 不限、1分钟以下、1-5分钟、5分钟以上，默认 不限。对应 TikHub 值分别为 0、0-1、1-5、5-10000。
input.params.sortType否搜索排序方式，会映射到 TikHub sort_type。可选 最多点赞、综合排序、最新发布，默认 最多点赞。对应 TikHub 值分别为 1、0、2。当选择 综合排序 或 最新发布 时，平台保留 TikHub 返回顺序；当选择 最多点赞 时，平台会按点赞量倒序返回。
input.params.contentType否内容类型过滤，会映射到 TikHub content_type。可选 视频、不限、图片、文章，默认 视频。对应 TikHub 值分别为 1、0、2、3。
input.params.requiredText否兼容字段。当前 douyin.top.search 默认按 TikHub 返回结果输出，不再使用该字段做本地文本过滤；调用方需要严格文本命中时，建议在结果侧自行过滤。
input.params.strictQueryPart否兼容字段。当前 douyin.top.search 默认按 TikHub 返回结果输出，不再使用该字段做本地严格关键词过滤；调用方需要严格关键词命中时，建议在结果侧自行过滤。
input.params.skipVideoStatistics否是否跳过视频统计补齐，默认 false。为 false 时平台会尽量补齐播放、点赞、评论、分享等统计字段；为 true 时速度更快，但统计字段可能不完整。
input.params.skipProfileEnrichment否是否跳过作者资料和最近作品补齐，默认 false。为 false 时平台会尽量补齐作者主页、粉丝数、获赞数、最近发布时间等资料；为 true 时速度更快，但 creatorProfile 可能为空或不完整。

TikHub 搜索 API 当前没有提供点赞量阈值筛选入参，所以 tikhub-api-service 不提供 minLikeCount / maxLikeCount 这类参数。调用方如果需要“点赞量大于 N”或“点赞量区间”筛选，应基于返回结果中的 likeCount 自行过滤；过滤后结果条数可能少于 limit。

minRecords、maxPages、enrichStatistics、enrichCreatorProfile 是 workflow 内部调优/兼容字段，不作为普通外部应用的开放契约展示。

响应格式

tikhub-api-service 是异步任务型能力。execute 成功只表示平台已受理任务，不表示 TikHub workflow 已经完成。调用方应保存 data.taskId，并使用 data.pollUrl 或统一任务查询接口轮询结果。

{
  "capabilityKey": "tikhub-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "RUNNING",
    "pollUrl": "/api/open/v1/organizations/{orgId}/capabilities/tikhub-api-service/tasks/platform-task-id"
  }
}

查询任务：

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

任务成功时，data.result 内返回业务结果和 trace 摘要：

注意：任务成功响应中的 data.result.data.videos[].videoId/videoUrl 是 workflow 返回格式；平台自动写入的结果资产不再使用这套字段。资产下载内容统一使用旧 Top10 资产 schema：根字段 douyin_top_videos，视频字段为 video_id、video_url、original_video_url 等 snake_case 字段。

{
  "capabilityKey": "tikhub-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "status": "SUCCEEDED",
    "taskId": "platform-task-id",
    "request": {
      "action": "douyin.top.search",
      "params": {
        "query": "短剧",
        "limit": 10
      }
    },
    "result": {
      "action": "douyin.top.search",
      "provider": "tikhub",
      "status": "SUCCEEDED",
      "data": {
        "query": "短剧",
        "limit": 10,
        "videos": [
          {
            "publishDate": "2026-06-24",
            "playCount": 123456,
            "likeCount": 12345,
            "shareCount": 100,
            "commentCount": 200,
            "videoName": "视频标题",
            "durationSeconds": 58,
            "coverUrl": "https://example.com/cover.jpg",
            "creatorName": "创作者昵称",
            "platformId": "sec_user_id",
            "videoUrl": null,
            "originalVideoUrl": "https://www.douyin.com/video/123",
            "videoId": "123",
            "profileBio": "作者简介",
            "creatorProfile": {
              "name": "创作者昵称",
              "profileUrl": "https://www.douyin.com/user/sec_user_id",
              "followingCount": 10,
              "followerCount": 1000,
              "totalFavorited": 20000,
              "latestThreePublishDates": ["2026-06-23", "2026-06-21", "2026-06-19"]
            }
          }
        ]
      },
      "trace": {
        "workflow": "DouyinTopTikHubWorkflowService",
        "fallbackUsed": false,
        "rawCandidateCount": 30,
        "dedupedCandidateCount": 24,
        "filteredCandidateCount": 18,
        "returnedCount": 10,
        "statisticsMatchedCount": 10,
        "creatorProfileMatchedCount": 8
      },
      "artifact": {
        "id": "artifact-id",
        "sourceType": "TIKHUB_API_SERVICE_DOUYIN_TOP_SEARCH",
        "sourceKey": "douyin.top.search::<sha256(action + params)>",
        "title": "TikHub Douyin Top Search - 短剧 - 20260625T120000",
        "mimeType": "application/json",
        "downloadUrl": "/api/open/v1/organizations/{orgId}/artifacts/{artifactId}/download",
        "metadata": {
          "sourceCapabilityKey": "tikhub-api-service",
          "feature": "douyin.top.search",
          "action": "douyin.top.search",
          "platform": "douyin",
          "provider": "tikhub",
          "artifactSchema": "douyin_top_videos"
        }
      }
    },
    "error": null,
    "artifacts": [
      {
        "id": "artifact-id",
        "downloadUrl": "/api/open/v1/organizations/{orgId}/artifacts/{artifactId}/download"
      }
    ],
    "createdAt": "2026-06-29T00:00:00Z",
    "updatedAt": "2026-06-29T00:02:00Z"
  }
}

message/code 表示开放能力入口执行成功；data.status 表示任务状态。data.result.status 表示业务 workflow 结果。trace 只返回排障摘要，不包含 TikHub API Key、Authorization header 或完整 TikHub raw response。

结果资产格式

douyin.top.search 任务执行成功后，平台会通过内部 artifact.write 自动写入 JSON 结果资产。调用方可以使用任务查询响应里的 data.artifacts[].downloadUrl 或 data.result.artifact.downloadUrl 下载资产内容。

资产 contentText 不使用任务结果里的 data.result.data.videos[].videoId/videoUrl，而是统一使用旧 Top10 资产 schema，便于和 douyin-video-url-backfill、历史 Top10 资产和资产索引逻辑保持一致：

{
  "merge_update_event": {
    "event_time": "2026-06-25T12:00:00+08:00",
    "event_timezone": "Asia/Shanghai",
    "record_count": 1
  },
  "douyin_top_videos": [
    {
      "publish_date": "2026-06-24",
      "play_count": 123456,
      "like_count": 12345,
      "share_count": 100,
      "comment_count": 200,
      "video_name": "视频标题",
      "duration_seconds": 58,
      "cover_url": "https://example.com/cover.jpg",
      "creator_name": "创作者昵称",
      "platform_id": "sec_user_id",
      "video_url": null,
      "original_video_url": "https://www.douyin.com/video/123",
      "video_id": "123",
      "profile_bio": "作者简介",
      "creator_profile": {
        "name": "创作者昵称",
        "profile_url": "https://www.douyin.com/user/sec_user_id",
        "following_count": 10,
        "follower_count": 1000,
        "total_favorited": 20000,
        "latest_three_publish_dates": ["2026-06-23", "2026-06-21", "2026-06-19"]
      }
    }
  ]
}

需要回填真实视频地址时，douyin-video-url-backfill 会按当前应用资产中的 douyin_top_videos[].video_id 定位条目，并更新 douyin_top_videos[].video_url。因此，调用方处理资产下载内容时应读取 douyin_top_videos，不要读取 data.videos。

提交快手账号搜索任务

POST /api/open/v1/organizations/{orgId}/capabilities/tikhub-api-service:execute
Authorization: Bearer <sk-organization-application-api-key>
Content-Type: application/json
{
  "applicationId": "organization-application-id",
  "input": {
    "action": "kuaishou.account.search",
    "params": {
      "kuaishouId": "lidaliang666",
      "limit": 10
    }
  }
}

字段说明：

字段必填说明
input.action是固定为 kuaishou.account.search。
input.params.kuaishouId是快手号，和旧 kuaishou-creator-info-single 的主入参保持一致，例如 lidaliang666。
input.params.limit否返回作品条数，默认 10，范围 1-50。

kuaishou.account.search 的产品含义是“按快手号定位账号并返回账号资料 + 作品摘要”，不是只返回搜索候选列表。它不复用旧的 kuaishou-creator-info-single / kuaishou-creator-info-batch 队列链路。

kuaishou.account.search 走 tikhub-api-service 独立任务队列。execute 只负责创建异步任务并返回平台 taskId，不在创建请求里直接返回账号资料和作品列表。调用方应保存 data.taskId，再使用 data.pollUrl 或统一任务查询接口轮询结果。

提交任务成功响应示例：

{
  "capabilityKey": "tikhub-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "RUNNING",
    "pollUrl": "/api/open/v1/organizations/{orgId}/capabilities/tikhub-api-service/tasks/platform-task-id"
  }
}

查询任务状态：

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

任务成功后，查询响应中的 data.result.data 与自动写入的资产 contentText 使用同一份旧快手达人信息兼容 schema：

{
  "capabilityKey": "tikhub-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "status": "SUCCEEDED",
    "taskId": "platform-task-id",
    "request": {
      "action": "kuaishou.account.search",
      "params": {
        "kuaishouId": "lidaliang666",
        "limit": 10
      }
    },
    "result": {
      "action": "kuaishou.account.search",
      "provider": "tikhub",
      "status": "SUCCEEDED",
      "data": {
        "creator_name": "户外平头哥（荒野生存）",
        "profile_url": "https://www.kuaishou.com/profile/3x3eiumbwrckuwm",
        "kuaishou_id": "lidaliang666",
        "follow_count": 46,
        "fans_count": 12832000,
        "total_likes": 110000000,
        "bio": null,
        "work_count": 10,
        "works": [
          {
            "publish_date": "2026-05-02",
            "play_count": null,
            "like_count": 191000,
            "title": "探索澳大利亚 前往澳洲北领地",
            "work_url": "https://www.kuaishou.com/short-video/3xfdmx5tiyqaqhg"
          }
        ]
      },
      "artifact": {
        "id": "artifact-id",
        "sourceType": "TIKHUB_API_SERVICE_KUAISHOU_ACCOUNT_SEARCH",
        "sourceKey": "kuaishou.account.search::<sha256(action + params)>",
        "title": "TikHub Kuaishou Account Search - 户外平头哥 - 20260625T120000",
        "mimeType": "application/json",
        "downloadUrl": "/api/open/v1/organizations/{orgId}/artifacts/{artifactId}/download"
      }
    },
    "error": null,
    "artifacts": [
      {
        "id": "artifact-id",
        "downloadUrl": "/api/open/v1/organizations/{orgId}/artifacts/{artifactId}/download"
      }
    ]
  }
}

快手账号资产 contentText 不再额外投影 camelCase 字段；调用方应读取 creator_name、kuaishou_id、fans_count、total_likes、works[].work_url 等 snake_case 字段。

内部链路

Open Capability: tikhub-api-service
  -> action: douyin.top.search
  -> TikHubApiServiceOpenCapabilityExecutor
  -> TikHubApiServiceAsyncTaskPipeline
  -> DouyinTopTikHubWorkflowService
  -> tikhub-api-adapter
  -> TikHub 原生 API

Open Capability: tikhub-api-service
  -> action: kuaishou.account.search
  -> TikHubApiServiceOpenCapabilityExecutor
  -> TikHubApiServiceAsyncTaskPipeline
  -> KuaishouAccountTikHubWorkflowService
  -> tikhub-api-adapter
  -> TikHub 原生 API

该链路不经过旧的 session-hub -> session-worker -> arkclaw。现有 douyin-top10-single、douyin-top10-batch、kuaishou-creator-info-single 和 kuaishou-creator-info-batch 仍保持原链路。

禁止调用 raw endpoint action

普通外部应用不能通过本能力直接选择 TikHub 原生 endpoint action，例如：

  • douyin.search.fetch_video_search_v2
  • douyin.search.fetch_video_search_v1
  • kuaishou.app.search_user_v2
  • kuaishou.app.fetch_user_post_v2

这些 action 属于 tikhub-api-adapter 内部实现细节。对外产品文档只承诺 tikhub-api-service 下的业务 action 契约。

请求 raw endpoint action 会返回参数错误：

{
  "capabilityKey": "tikhub-api-service",
  "message": "raw TikHub API action is internal to tikhub-api-adapter; use a tikhub-api-service business action",
  "code": 400,
  "data": null
}

任务查询与取消

douyin.top.search 和 kuaishou.account.search 都使用 tikhub-api-service 这个 capability key 创建任务。调用方通过统一任务查询入口获取 RUNNING、SUCCEEDED、FAILED、CANCELLED 状态、业务结果和 artifact。

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

运行中的任务可以请求取消：

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

取消成功响应示例：

{
  "capabilityKey": "tikhub-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "taskId": "platform-task-id",
    "status": "CANCELLED",
    "request": {
      "action": "douyin.top.search",
      "params": {
        "query": "短剧",
        "limit": 10
      }
    },
    "result": null,
    "error": {
      "code": "OPEN_CAPABILITY_CANCELLED_BY_USER",
      "message": "cancelled by open capability caller"
    },
    "artifacts": []
  }
}

取消是 best-effort：如果后台 TikHub HTTP 调用已经发出，平台会先把本地任务标记为 CANCELLED 并释放本地队列；后台完成后不会覆盖已取消的终态。

Last updated on
ADX 达人数据 批量快手达人信息 单条