更新时间:2024-03-25 GMT+08:00

新建截图任务

功能介绍

新建截图任务,视频截图将从首帧开始,按设置的时间间隔截图,最后截取末帧。 待截图的视频文件需要存储在与媒体处理服务同区域的OBS桶中,且该OBS桶已授权。

约束: 暂只支持生成JPG格式的图片文件。

调用方法

请参见如何调用API

URI

POST /v1/{project_id}/thumbnails

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID。获取方法请参考获取项目ID

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。

Authorization

String

使用AK/SK方式认证时必选,携带的鉴权信息。

X-Project_Id

String

使用AK/SK方式认证时必选,携带项目ID信息, 与路径参数中的项目ID相同。

X-Sdk-Date

String

使用AK/SK方式认证时必选,请求的发生时间。

表3 请求Body参数

参数

是否必选

参数类型

描述

input

ObsObjInfo object

源文件地址。

output

ObsObjInfo object

输出地址。

user_data

String

用户自定义数据。

thumbnail_para

ThumbnailPara object

截图参数

tar

Integer

是否压缩抽帧图片生成tar包。

取值如下:

  • 0:压缩。

  • 1:不压缩 默认值:1

sync

Integer

是否同步处理,同步处理是指不下载全部文件,快速定位到截图位置进行截图。

取值如下:

  • 0:排队处理,异步截图。

  • 1:同步处理,同步截图,暂只支持按时间点截单张图。

默认值:0

original_dir

Integer

是否使用原始输出目录。

取值如下:

  • 0:不使用原始输出目录,下发的输出目录后面追加随机目录,防止截图文件outputUri相同被覆盖。

  • 1:使用原始输出目录。 默认值:0

表4 ObsObjInfo

参数

是否必选

参数类型

描述

bucket

String

OBS的bucket名称。

location

String

OBS桶所在的区域,且必须与使用的MPC区域保持一致。

object

String

OBS对象路径,遵守OSS Object定义。

  • 当用于指示input时,需要指定到具体对象。

  • 当用于指示output时,只需指定到转码结果期望存放的路径。

在字幕场景下,字幕文件名称中禁止携带特殊符号,否则会导致转码任务失败,如:[

  • 正确示例: demo.srt

  • 错误示例: [demo.srt

file_name

String

文件名

  • 当指定了此参数时,输出的对象名为object/file_name。

  • 当不指定此参数时,输出的对象名为object/xxx,其中xxx由MPC指定。

在作为输出文件名时:

  • 在转封装场景有效,需要指定输出文件名称

  • 在转码场景下,如果需要指定输出的文件名称,请使用output_filenames参数

  • 在解析场景有效,解析场景如果指定文件名,则将解析参数写入指定文件名,通过查询接口响应json数据获取文件元数据信息

  • 在截图场景无效

  • 在转动图场景无效

表5 ThumbnailPara

参数

是否必选

参数类型

描述

type

String

采样类型。

取值如下:

  • "TIME":根据时间间隔采样截图。

  • "DOTS":指定时间点截图。选择同步截图时,需指定此类型。

  • "DOTS_MS": 同步截图指定时间点毫秒值。 默认值:"TIME"

time

Integer

采样截图的时间间隔值。

默认值:12。

单位:秒

start_time

Integer

采样类型为“TIME”模式的开始时间,和“time”配合使用。

默认值:0。

单位:秒。

说明:

start_time超过片源时长,不进行抽帧

duration

Integer

采样类型为“TIME”模式的持续时间,和“time”、“start_time”配合使用,表示从视频文件的第“start_time”开始,持续时间为“duration”,每间隔“time”生成一张截图。

取值范围:[数字,ToEND]。“ToEND”表示持续到视频结束。

默认值: ToEND。

单位:秒。

说明:

“duration”必须大于等0,若设置为0,则截图持续时间从“start_time”到视频结束。

dots

Array of integers

指定时间截图的时间点数组

例如输入[1,3,5],分别截取视频第1秒、第3秒、第5秒位置的图像帧

  • 异步截图:最多支持10个时间点

  • 同步截图时:只支持1个时间点

dots_ms

Array of integers

同步截图下,指定时间截图的时间点数组,单位毫秒

例如输入[1000],截取视频第1000毫秒位置的图像帧,仅支持一个时间点

output_filename

String

截图输出文件名。

  • 如果只抽一张图(即:按DOTS方式,指定1个时间点)则按该指定文件名输出图片。

  • 如果抽多张图(即:按DOTS方式指定多个时间点或按TIME间隔截图)则输出图片名在该指定文件名基础上在增加时间点(示例:output_filename_10.jpg)。

  • 如果指定了压缩抽帧图片生成tar包,则tar包按该指定文件名输出。

format

Integer

截图文件格式。

取值如下:

1:表示jpg格式 2:表示png格式 仅同步截图支持png格式

width

Integer

图片宽度

取值范围:

  • [96,3840]

  • 0:自适应,保持原有宽高

单位:px

height

Integer

图片高度

取值范围:

  • [96,2160]

  • 0:自适应,保持原有宽高

单位:px

max_length

Integer

截图最长边的尺寸。宽边尺寸按照该尺寸与原始视频像素等比缩放计算。

参考取值范围:[240,3840]

单位:像素

说明:

该参数和width/height选择使用,以width/height优先,若width/height都不等于0,则图片尺寸按width/height得出;反之,则图片尺寸按max_length 得出;若该参数和width/height都未选择,则按源片源宽高输出截图

响应参数

状态码: 202

表6 响应Body参数

参数

参数类型

描述

task_id

String

任务ID。

status

String

任务状态

create_time

String

任务创建时间

output

ObsObjInfo object

输出文件信息

output_file_name

String

截图文件名称

thumbnail_time

String

指定的截图时间点

description

String

截图任务描述,当截图出现异常时,此字段为异常的原因

表7 ObsObjInfo

参数

参数类型

描述

bucket

String

OBS的bucket名称。

location

String

OBS桶所在的区域,且必须与使用的MPC区域保持一致。

object

String

OBS对象路径,遵守OSS Object定义。

  • 当用于指示input时,需要指定到具体对象。

  • 当用于指示output时,只需指定到转码结果期望存放的路径。

在字幕场景下,字幕文件名称中禁止携带特殊符号,否则会导致转码任务失败,如:[

  • 正确示例: demo.srt

  • 错误示例: [demo.srt

file_name

String

文件名

  • 当指定了此参数时,输出的对象名为object/file_name。

  • 当不指定此参数时,输出的对象名为object/xxx,其中xxx由MPC指定。

在作为输出文件名时:

  • 在转封装场景有效,需要指定输出文件名称

  • 在转码场景下,如果需要指定输出的文件名称,请使用output_filenames参数

  • 在解析场景有效,解析场景如果指定文件名,则将解析参数写入指定文件名,通过查询接口响应json数据获取文件元数据信息

  • 在截图场景无效

  • 在转动图场景无效

状态码: 400

表8 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

请求示例

  • 新建异步截图任务,视频截图将从首帧开始,按设置的时间间隔截图,最后截取末帧。

    POST https://{endpoint}/v1/{project_id}/thumbnails
    
    {
      "input" : {
        "bucket" : "example-bucket",
        "location" : "region01",
        "object" : "example-path/input.mp4"
      },
      "output" : {
        "bucket" : "example-bucket",
        "location" : "region01",
        "object" : "example-path/output"
      },
      "tar" : 1,
      "thumbnail_para" : {
        "time" : 2,
        "format" : 1,
        "max_length" : 480
      },
      "sync" : 0
    }
  • 新建同步截图任务(将sync设置为1),视频截图将从首帧开始,按设置的时间间隔截图,最后截取末帧。

    POST https://{endpoint}/v1/{project_id}/thumbnails
    
    {
      "input" : {
        "bucket" : "example-bucket",
        "location" : "region01",
        "object" : "example-path/input.mp4"
      },
      "output" : {
        "bucket" : "example-bucket",
        "location" : "region01",
        "object" : "example-path/output"
      },
      "tar" : 1,
      "thumbnail_para" : {
        "time" : 2,
        "format" : 1,
        "max_length" : 480
      },
      "sync" : 1
    }

响应示例

状态码: 202

新建截图任务成功。

  • 新建异步截图任务成功。

    {
      "task_id" : "100211"
    }
  • 新建同步截图任务成功。

    {
      "task_id" : "100212",
      "status" : "FINISHED",
      "create_time" : "20231201020412",
      "output" : {
        "bucket" : "bucket-demo",
        "location" : "cn-north-4",
        "object" : "output/demo_object",
        "file_name" : ""
      },
      "output_file_name" : "H_270.png",
      "thumbnail_time" : "30",
      "description" : "任务处理成功。"
    }

状态码: 400

新建截图任务失败。

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter"
}

状态码

状态码

描述

202

新建截图任务成功。

400

新建截图任务失败。

错误码

请参见错误码