媒体拆条内容

media-clip-api-service 是 FunClaw 对外开放的媒体拆条数据服务。它通过一个同步 action 提供全量、增量游标分页，以及按任务、剧名和频道查询，不保存调用方水位，不创建平台任务，也不自动写入 FunClaw 资产。

能力信息

字段	值
能力 Key	`media-clip-api-service`
action	`clips.list`
能力类型	`data_service`
执行方式	同步、无状态
服务端配置	`MEDIA_CLIP_API_BASE_URL`，可选超时和重试配置
资产写入	不自动写资产

上游接口无需登录，但 FunClaw 调用仍需携带有效 API Key，并且该 Key 必须获得 media-clip-api-service 授权。

调用入口

组织显式路径：


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

Skill/MCP key-only 路径：


POST /api/open/v1/capabilities/media-clip-api-service/execute
Authorization: Bearer <sk-external-agent-or-application-api-key>
Content-Type: application/json

也可以通过 /api/open/v1/mcp 的 funclaw.execute_open_capability 工具调用同一能力。

请求参数


{
  "input": {
    "action": "clips.list",
    "params": {
      "mode": "incremental",
      "limit": 50,
      "cursor": 485301511,
      "updateTime": "2026-07-27 00:00:00"
    }
  }
}

字段	必填	说明
`input.action`	是	固定为 `clips.list`。
`input.params`	是	参数对象，不接受未声明字段。
`mode`	否	`full` 或 `incremental`，默认 `full`。
`limit`	否	每页 `1-50` 条，默认 `50`。
`cursor`	否	上一页返回的 `nextCursor`，必须是正整数。
`updateTime`	增量必填	格式 `YYYY-MM-DD HH:mm:ss`；同一轮分页必须保持不变。
`taskId`	查询模式可选	第三方任务 ID，支持字符串或正整数；不能和 `mediaName/channel` 同时使用。
`mediaName`	查询模式可选	按媒体或剧名精确查询，可单独使用。
`channel`	查询模式可选	按频道精确查询，必须同时提供 `mediaName`。
`page`	查询模式可选	查询页码，从 `1` 开始，默认 `1`。

出现 taskId、mediaName 或 channel 时自动进入查询模式。查询模式会忽略 mode、cursor、updateTime；page 不能脱离查询条件单独使用。full 模式不得传 updateTime。开始新一轮增量拉取时重置 cursor，由调用方提供新的 updateTime。

全量拉取

第一页：


{
  "capabilityKey": "media-clip-api-service",
  "input": {
    "action": "clips.list",
    "params": { "mode": "full", "limit": 50 }
  }
}

当 hasMore=true 时，将本页 nextCursor 作为下一页的 cursor。循环至 hasMore=false。

增量拉取

第一页：


{
  "capabilityKey": "media-clip-api-service",
  "input": {
    "action": "clips.list",
    "params": {
      "mode": "incremental",
      "updateTime": "2026-07-27 00:00:00",
      "limit": 50
    }
  }
}

下一页继续传相同 updateTime，并追加上一页的 nextCursor。不得在一轮分页过程中推进 updateTime。

条件查询

按第三方任务 ID 查询：


{
  "capabilityKey": "media-clip-api-service",
  "input": {
    "action": "clips.list",
    "params": {
      "taskId": "78002",
      "page": 1,
      "limit": 50
    }
  }
}

按剧名查询：


{
  "capabilityKey": "media-clip-api-service",
  "input": {
    "action": "clips.list",
    "params": {
      "mediaName": "摩天楼",
      "page": 1,
      "limit": 50
    }
  }
}

按剧名和频道查询：


{
  "capabilityKey": "media-clip-api-service",
  "input": {
    "action": "clips.list",
    "params": {
      "mediaName": "摩天楼",
      "channel": "电影",
      "page": 1,
      "limit": 50
    }
  }
}

查询模式返回 paging.mode=query，使用 page 和 nextPage 分页；nextCursor 固定为 null。taskId 与媒体条件互斥，channel 不能单独使用。媒体查询由上游先筛选最多 200 个任务，再按 split_id DESC, clip_order ASC, id ASC 返回，优先较新的任务并保持任务内顺序稳定。

响应格式


{
  "capabilityKey": "media-clip-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "clips.list",
    "provider": "media-clip",
    "status": "SUCCEEDED",
    "data": {
      "clips": [
        {
          "id": 485301511,
          "taskId": "78002",
          "mediaName": "媒体名称",
          "channelName": "频道名称",
          "sequence": 1,
          "playUrl": "http://videoplay.funshion.com/video/example.mp4",
          "startTimeMs": 183000,
          "endTimeMs": 219000,
          "createdTime": "2026-07-27 10:00:00",
          "updatedTime": "2026-07-27 10:12:00"
        }
      ],
      "paging": {
        "mode": "incremental",
        "limit": 50,
        "nextCursor": 485301511,
        "hasMore": false
      }
    },
    "trace": {
      "requestId": "media-clip-request-id",
      "elapsedMs": 120,
      "upstreamHttpStatus": 200
    }
  }
}

taskId 始终输出为字符串。startTimeMs 和 endTimeMs 的单位为毫秒。全量和增量模式使用 nextCursor；查询模式使用可空的 nextPage。时间字段保持上游的 YYYY-MM-DD HH:mm:ss 格式，不进行时区转换。

查询分页示例：


{
  "mode": "query",
  "limit": 50,
  "page": 1,
  "nextPage": 2,
  "nextCursor": null,
  "hasMore": true
}

授权

应用级 API Key：应用必须被授予 media-clip-api-service。
组织级 admin API Key：组织直接授权或组织应用授权必须包含该能力。
数字员工 / External Agent API Key：对应数字员工必须被授予该能力。
上游免登录只表示 FunClaw 服务端不需要上游凭据，不会绕过 FunClaw 授权。

错误处理

HTTP 状态	错误码	说明
`400`	`MEDIA_CLIP_INVALID_REQUEST`	参数不合法或上游拒绝请求。
`403`	`open capability not granted`	当前 FunClaw Key 未获授权。
`500`	`MEDIA_CLIP_API_NOT_CONFIGURED`	服务端未配置上游基址。
`502`	`MEDIA_CLIP_UPSTREAM_QUERY_FAILED`	上游查询失败。
`502`	`MEDIA_CLIP_PLAY_URL_GENERATION_FAILED`	上游生成播放地址失败。
`502`	`MEDIA_CLIP_INVALID_RESPONSE`	上游响应不是预期结构。
`502`	`MEDIA_CLIP_UPSTREAM_UNAVAILABLE`	上游网络、超时或其他服务异常。

边界

每次最多返回 50 条，不自动聚合所有分页。
服务端不保存 cursor、updateTime、page 或拉取历史。
查询模式单次最多基于 200 个候选任务返回结果，排序由上游保证。
返回播放地址但不自动下载视频。
不自动创建 FunClaw 资产；需要沉淀时另行调用 application-asset-service。