媒体拆条内容

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`；同一轮分页必须保持不变。

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。

响应格式


{
  "capabilityKey": "media-clip-api-service",
  "message": "SUCCEEDED",
  "code": 200,
  "data": {
    "action": "clips.list",
    "provider": "media-clip",
    "status": "SUCCEEDED",
    "data": {
      "clips": [
        {
          "id": 485301511,
          "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
    }
  }
}

startTimeMs 和 endTimeMs 的单位为毫秒。nextCursor 在没有数据时为 null。时间字段保持上游的 YYYY-MM-DD HH:mm:ss 格式，不进行时区转换。

授权

应用级 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 或拉取历史。
返回播放地址但不自动下载视频。
不自动创建 FunClaw 资产；需要沉淀时另行调用 application-asset-service。