视频抽帧算子 las_video_frame_extract 用于按指定频率从视频中均匀抽取图片帧，并将结果写入您指定的 TOS 路径。您可以利用该算子快速为视频理解、检测审核、封面生成和低频采样分析等场景准备结构化帧数据。

描述 #

视频抽帧算子支持对输入视频按指定帧率进行抽帧，将抽取的图片帧上传至指定 TOS 存储路径。任务完成后，您可以获取视频元信息以及每一帧的访问地址。算子支持可配置的抽帧频率、最大帧数限制、输出图片格式和缩放策略，适用于视频理解、检测、审核、摘要、封面生成等场景。

使用限制 #

• 输入限制：输入视频需可被服务访问，支持 http、https 和 tos:// 协议。
• 输出限制：
  • 输出图片格式仅支持 jpg 和 png。
  • 输出的图片仅支持写入 TOS 中，通过output_path_template 参数设置输出路径，必须以 tos:// 开头，且必须包含 {index} 占位符。例如 tos://bucket/frames/frame_{index}.{autoext}。
  • 如果当前环境无法访问对应 TOS 路径，任务会返回 Tos.AccessFailed 错误。
• 抽帧能力参数限制：
  • 抽帧频率 fps 的取值范围为 0.1 ~ 10.0。
  • resize_short_side 与 resize_hw 互斥，不能同时设置。
  • resize_hw 为长度固定为 2 的数组 [width, height]。当某一项为 null 时，表示按另一边等比缩放。

核心功能 #

• 按帧率抽帧：按指定 FPS（0.1 ~ 10.0）对视频进行均匀抽帧。
• 最大帧数限制：可设置 max_frames 参数控制输出帧数上限，避免长视频产生过多帧。
• 多格式输出：支持输出 jpg 和 png 两种图片格式。
• 灵活缩放：支持按短边缩放（resize_short_side）或指定目标分辨率（resize_hw），满足不同场景需求。
• 自定义输出路径：通过输出路径模板自定义抽帧图片在 TOS 上的存储路径。
• 长视频支持：适合处理长时间视频，可通过 max_frames 控制输出规模。

• 计费标准

  细分项	计费标准说明
  计费项	对输入视频采样后的图片张数统计用量，并进行计费。
  计费类型	按量计费，单位：元/千张，按实际的计费用量每小时出账。
  单价	0.1 元/千张

• 计费详情
  计费公式：总费用 = 单价 * 用量

调用 las_video_frame_extract 时，您需要先通过 Submit 提交异步任务，待任务进入完成状态后，再通过 Poll 获取抽帧结果。

Submit #

接口说明 #

调用视频抽帧算子提交异步任务，对输入视频按指定帧率进行抽帧，并将抽取的图片帧上传至指定 TOS 路径。提交成功后会返回任务 ID，您可以基于该 ID 通过 Poll 接口继续查询处理进度和结果。

请求参数 #

返回数据 #

示例 #

请求示例

curl --location "https://operator.las.cn-beijing.volces.com/api/v1/submit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $LAS_API_KEY" \
--data '{
  "operator_id": "las_video_frame_extract",
  "operator_version": "v1",
  "data": {
    "video_url": "tos://my-bucket/videos/sample.mp4",
    "output_path_template": "tos://my-bucket/frames/frame_{index}.{autoext}",
    "fps": 1.0,
    "max_frames": 200,
    "image_format": "jpg",
    "resize_short_side": 720
  }
}'

返回示例

{
  "metadata": {
    "task_id": "task-20260420120000-abc123",
    "task_status": "PENDING",
    "business_code": "0",
    "error_msg": ""
  }
}

错误码 #

Poll #

接口说明 #

调用 Poll 接口查询视频抽帧任务的执行状态和结果。当任务状态为 COMPLETED 时，接口会返回视频元信息和抽取后的帧列表。

请求参数 #

返回数据 #

示例 #

请求示例

curl --location "https://operator.las.cn-beijing.volces.com/api/v1/poll" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $LAS_API_KEY" \
--data '{
  "operator_id": "las_video_frame_extract",
  "operator_version": "v1",
  "task_id": "task-20260420120000-abc123"
}'

返回示例

{
  "metadata": {
    "task_id": "task-20260420120000-abc123",
    "task_status": "COMPLETED",
    "business_code": "0",
    "error_msg": ""
  },
  "data": {
    "video_duration": 11.234,
    "video_resolution": "1920x1080",
    "frame_count": 3,
    "frames": [
      {
        "index": 0,
        "timestamp_seconds": 0.5,
        "width": 720,
        "height": 405,
        "http_url": "https://example.com/frame_000.jpg",
        "tos_path": "tos://my-bucket/frames/frame_000.jpg"
      },
      {
        "index": 1,
        "timestamp_seconds": 1.5,
        "width": 720,
        "height": 405,
        "http_url": "https://example.com/frame_001.jpg",
        "tos_path": "tos://my-bucket/frames/frame_001.jpg"
      },
      {
        "index": 2,
        "timestamp_seconds": 2.5,
        "width": 720,
        "height": 405,
        "http_url": "https://example.com/frame_002.jpg",
        "tos_path": "tos://my-bucket/frames/frame_002.jpg"
      }
    ]
  }
}

错误码 #

算子参数 #

输入 #

输出 #

结构体数组，字段包括：

• frames: 采样帧图像的 array（H x W x C），可配置是否输出
• base64: 采样帧对应的 base64 编码（img_type 指定格式），可配置是否输出
• timestamps: 采样帧的时间戳（秒）
• frame_indices: 采样帧在解码序列中的帧索引
• tos_paths: 采样帧在 TOS 上的存储路径（若配置了 output_tos_dir）

参数 #

如参数没有默认值，则为必填参数

调用示例 #

下面的代码展示了如何使用 Daft（适用于分布式）从视频中按帧间隔采样若干图像帧。本示例设置 interval_frames=100，实际产出 6 张图片。

from __future__ import annotations

import os

import daft
from daft import col
from daft.las.functions.udf import las_udf
from daft.las.functions.video.video_frame_sampler import VideoFrameSampler

if __name__ == "__main__":

    # 更改完采样的帧会保存到指定的TOS路径下，因此，需要设置好环境变量以保证有权限写入TOS，包括：ACCESS_KEY,SECRET_KEY,TOS_ENDPOINT,TOS_REGION,TOS_TEST_DIR
    TOS_DIR = os.getenv("TOS_TEST_DIR", "tos_bucket")
    output_tos_dir = f"tos://{TOS_DIR}/video/video_frame_sampler"
    
    if os.getenv("DAFT_RUNNER", "native") == "ray":
        import logging

        import ray

        def configure_logging():
            logging.basicConfig(
                level=logging.INFO,
                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
                datefmt="%Y-%m-%d %H:%M:%S.%s".format(),
            )
            logging.getLogger("tracing.span").setLevel(logging.WARNING)
            logging.getLogger("daft_io.stats").setLevel(logging.WARNING)
            logging.getLogger("DaftStatisticsManager").setLevel(logging.WARNING)
            logging.getLogger("DaftFlotillaScheduler").setLevel(logging.WARNING)
            logging.getLogger("DaftFlotillaDispatcher").setLevel(logging.WARNING)

        ray.init(dashboard_host="0.0.0.0", runtime_env={"worker_process_setup_hook": configure_logging})
        daft.set_runner_ray()
    daft.set_execution_config(actor_udf_ready_timeout=600)
    daft.set_execution_config(min_cpu_per_task=0)

    # 使用环境变量构建URL
    tos_dir_url = os.getenv("TOS_DIR_URL", "las-cn-beijing-public-online.tos-cn-beijing.volces.com")
    samples = {
        "video_path": [
            f"https://{tos_dir_url}/public/shared_video_dataset/sample.mp4"
        ]
    }

    ds = daft.from_pydict(samples)

    sampler = las_udf(
        VideoFrameSampler,
        construct_args={
            "sample_mode": "by_interval_frames",
            "interval_frames": 100,
            "output_tos_dir": output_tos_dir,
            "img_type": ".jpg",
        },
    )

    # 使用 Daft 进行分布式处理
    ds = ds.with_column("results", sampler(col("video_path")))

    ds = ds.select(
        "video_path",
        col("results")["frames"].alias("frames"),
        col("results")["base64"].alias("base64"),
        col("results")["timestamps"].alias("timestamps"),
        col("results")["frame_indices"].alias("frame_indices"),
        col("results")["tos_paths"].alias("tos_paths"),
    )

    ds.show()
    # ╭────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
    # │ video_path                     ┆ results                                                                                                                          │
    # │ ---                            ┆ ---                                                                                                                                      │
    # │ Utf8                           ┆ Struct[frames: List[Binary], base64: List[Utf8], timestamps: List[Float64], frame_indices: List[Int64], tos_paths: List[Utf8]] │
    # ╞════════════════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╡
    # │ https://las-cn-beijing-publi-… ┆ {frames: […], base64: […], timestamps: […], frame_indices: […], tos_paths: ["tos://tos_bucket/video/video_frame_sampler/frame_0.jpg", …]} │
    # ╰────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯