tencent cloud

文档反馈

模板操作

最后更新时间:2024-03-13 10:07:11

    简介

    本文档提供关于数据万象媒体处理任务的相关 API 概览以及 SDK 示例代码,此处以动图任务举例。
    API
    操作名
    操作描述
    创建模板
    用于创建一个新的模板
    删除模板
    删除一个模板
    查询模板
    查询模板列表
    修改模板
    修改一个模板

    基本操作

    创建模板

    功能说明

    用于创建一个新的模板。

    方法原型

    public MediaTemplateResponse createMediaTemplate(MediaTemplateRequest request);

    参数说明

    Request 的具体参数描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    Tag
    Request
    模板类型:Animation 动图,Snapshot 截图,Transcode 转码,Watermark 水印,SmartCover 智能封面
    String
    Name
    Request
    模板名称仅支持中文、英文、数字、_、-和*
    String
    Container
    Request
    容器格式
    Container
    Video
    Request
    视频信息
    Container
    TimeInterval
    Request
    时间区间
    Container
    Snapshot
    Request
    截图
    Container
    Watermark
    Request
    水印
    Container
    Audio
    Request
    音频信息
    Container
    TransConfig
    Request
    转码配置
    Container
    Request 节点 Container 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    Format
    Request.Container
    容器格式:gif,hgif,webp hgif 为高质量 gif,即清晰度比较高的 gif 格式图
    String
    Request 节点 Video 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Codec
    Request.Video
    编解码格式
    String
    gif、webp
    Width
    Request.Video
    String
    视频原始宽度
    值范围:[128,4096]
    单位:px
    若只设置 Width 时,按照视频原始比例计算 Height
    Height
    Request.Video
    String
    视频原始高度
    值范围:[128,4096]
    单位:px
    若只设置 Height 时,按照视频原始比例计算 Width
    Fps
    Request.Video
    帧率
    String
    视频原始帧率
    值范围:(0,60]
    单位:fps
    如果不设置,那么播放速度按照原来的时间戳。这里设置 fps 为动图的播放帧率。
    AnimateOnly KeepKeyFrame
    Request.Video
    动图只保留关键帧
    String
    true、false
    动图保留关键帧参数
    AnimateTime IntervalOfFrame
    Request.Video
    动图抽帧间隔时间
    String
    (0,视频时长]
    动图抽帧时间间隔
    若设置 TimeInterval.Duration,则小于该值
    AnimateFrames PerSecond
    Request.Video
    Animation 每秒抽帧帧数
    String
    (0,视频帧率)
    动图抽帧频率
    优先级:AnimateFrames PerSecond > AnimateOnlyKeepKeyFrame > AnimateTimeIntervalOfFrame
    Quality
    Request.Video
    设置相对质量
    String
    [1, 100)
    webp 图像质量设定生效,gif 没有质量参数
    Request 节点 TimeInterval 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Start
    Request.TimeInterval
    开始时间
    String
    0
    [0 视频时长]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    Duration
    Request.TimeInterval
    持续时间
    String
    视频时长
    [0 视频时长]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    Container 类型 Snapshot 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Mode
    Request.Snapshot
    截图模式
    String
    Interval
    值范围:{Interval, Average}
    Interval 表示间隔模式 Average 表示平均模式
    Interval 模式:Start,TimeInterval,Count 参数生效。当设置 Count,未设置 TimeInterval 时,表示截取所有帧,共 Count 张图片
    Average 模式:Start,Count 参数生效。表示从 Start 开始到视频结束,按平均间隔截取共 Count 张图片
    Start
    Request.Snapshot
    开始时间
    String
    0
    [0 视频时长]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    TimeInterval
    Request.Snapshot
    截图频率
    String
    (0 3600]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    Count
    Request.Snapshot
    截图数量
    String
    (0 10000]
    Width
    Request.Snapshot
    String
    视频原始宽度
    值范围:[128,4096]
    单位:px
    若只设置 Width 时,按照视频原始比例计算 Height
    Height
    Request.Snapshot
    String
    视频原始高度
    值范围:[128,4096]
    单位:px
    若只设置 Height 时,按照视频原始比例计算Width
    Container 类型 Watermark 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Type
    Request.Watermark
    水印类型
    String
    Text:文字水印、 Image:图片水印
    Pos
    Request.Watermark
    基准位置
    String
    TopRight、TopLeft、BottomRight、 BottomLeft
    LocMode
    Request.Watermark
    偏移方式
    String
    Relativity:按比例、 Absolute:固定位置
    Dx
    Request.Watermark
    水平偏移
    String
    当 locMode 为 Relativity 时, 单位为%,取值范围[0 100]
    当 locMode 为 Absolute 时, 单位为px,取值范围[0 4096]
    Dy
    Request.Watermark
    垂直偏移
    String
    当 locMode 为 Relativity 时, 单位为%,取值范围[0 100]
    当 locMode 为 Absolute 时, 单位为px,取值范围[0 4096]
    StartTime
    Request.Watermark
    水印开始时间
    String
    0
    [0 视频时长]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    EndTime
    Request.Watermark
    水印结束时间
    String
    视频结束时间
    [0 视频时长]
    单位为秒
    支持 float 格式,执行精度精确到毫秒
    Image
    Request.Watermark
    图片水印节点
    Container
    Text
    Request.Watermark
    文本水印节点
    Container
    Container 类型 Image 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Url
    Request.Watermark.Image
    水印图地址
    String
    同 bucket 的水印图片地址
    Mode
    Request.Watermark.Image
    尺寸模式
    String
    Original:原有尺寸
    Proportion:按比例
    Fixed:固定大小
    Width
    Request.Watermark.Image
    String
    当 Mode 为 Original,水印图宽
    当 Mode 为 Proportion,单位为%,取值范围:[1 100]
    当 Mode 为 Fixed,单位为px,取值范围:[1,4096]
    若只设置 Width 时,按照视频原始比例计算 Height
    Height
    Request.Watermark.Image
    String
    当 Mode 为 Original,水印图高
    当 Mode 为 Proportion,单位为%,取值范围:[1 100]
    当 Mode 为 Fixed,单位为px,取值范围:[1,4096]
    若只设置 Height 时,按照视频原始比例计算 Width
    Transparency
    Request.Watermark.Image
    透明度
    String
    值范围:[1 100],单位%
    水印位置说明:
    image.png
    
    
    Container 类型 Text 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    FontSize
    Request.Watermark.Text
    字体大小
    String
    值范围:[5 100],单位为px
    FontType
    Request.Watermark.Text
    字体类型
    String
    参考下表
    FontColor
    Request.Watermark.Text
    字体颜色
    String
    格式:0xRRGGBB
    Transparency
    Request.Watermark.Text
    透明度
    String
    值范围:[1 100],单位为%
    Text
    Request.Watermark.Text
    水印内容
    String
    长度不超过64个字符,仅支持中文、英文、数字、_、-和*
    Text 的 FontType 具体数据描述如下:
    字体名称
    支持的语言
    描述
    simfang.ttf
    中/英
    仿宋
    simhei.ttf
    中/英
    黑体
    simkai.ttf
    中/英
    楷体
    simsun.ttc
    中/英
    宋体
    STHeiti-Light.ttc
    中/英
    华文黑体
    STHeiti-Medium.ttc
    中/英
    华文黑体中
    youyuan.TTF
    中/英
    幼圆
    ariblk.ttf
    arial.ttf
    ahronbd.ttf
    Helvetica.dfont
    HelveticaNeue.dfont
    Audio 音频视频支持的格式如下表:
    Container
    Audio Codecs
    Video Codecs
    flv/mp4/ts/hls
    AAC、MP3
    H.264
    aac
    aac
    不支持
    mp3
    mp3
    不支持
    Audio 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Codec
    Request.Audio
    编解码格式
    String
    aac
    取值 aac、mp3
    Samplerate
    Request.Audio
    采样率
    String
    44100
    单位:Hz
    可选 11025、22050、32000、44100、48000、96000
    不同的封装,mp3 支持不同的采样率,如下表所示
    Bitrate
    Request.Audio
    原始音频码率
    String
    单位:Kbps
    值范围:[8,1000]
    Channels
    Request.Audio
    声道数
    String
    当 Codec 设置为 aac,支持1、2、4、5、6、8
    当 Codec 设置为 mp3,支持1、2
    Remove
    Request.Audio
    是否删除音频流
    String
    false
    取值 true、false
    Y表示支持这种采样率,N表示不支持。
    封装格式/音频采样率
    11025
    22050
    32000
    44100
    48000
    96000
    flv
    Y
    Y
    N
    Y
    N
    N
    mp4
    N
    Y
    Y
    Y
    Y
    N
    avi/hls/ts/mp3
    Y
    Y
    Y
    Y
    Y
    N
    TransConfig 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    AdjDarMethod
    Request.TransConfig
    分辨率调整方式
    String
    none
    取值 scale、crop、pad、none
    当输出视频的宽高比与原视频不等时,需要此参数进行执行调整方式
    IsCheckReso
    Request.TransConfig
    是否检查分辨率
    String
    false
    true、false
    当为 false 时,按照配置参数转码
    ResoAdjMethod
    Request.TransConfig
    分辨率调整方式
    String
    0
    取值0、1;0 表示使用原视频分辨率;1表示返回转码失败
    当 IsCheckReso 为 true 时生效
    IsCheckVideoBitrate
    Request.TransConfig
    是否检查视频码率
    String
    false
    true、false
    当为 false 时,按照配置参数转码
    VideoBitrateAdjMethod
    Request.TransConfig
    视频码率调整方式
    String
    0
    取值0、1;0 表示使用原视频码率;1表示返回转码失败
    当 IsCheckVideoBitrate 为 true 时生效
    IsCheckAudioBitrate
    Request.TransConfig
    是否检查音频码率
    String
    false
    true、false
    当为 false 时,按照配置参数转码
    AudioBitrateAdjMethod
    Request.TransConfig
    音频码率调整方式
    String
    0
    取值0、1;0 表示使用原音频码率;1表示返回转码失败
    当 IsCheckAudioBitrate 为 true 时生效
    Video 的具体数据描述如下:
    节点名称(关键字)
    父节点
    描述
    类型
    必选
    默认值
    限制
    Codec
    Request.Video
    编解码格式
    String
    H.264
    H.264
    Width
    Request.Video
    String
    视频原始宽度
    值范围:[128,4096]
    单位:px
    若只设置 Width 时,按照视频原始比例计算 Height
    Height
    Request.Video
    String
    视频原始高度
    值范围:[128,4096]
    单位:px
    若只设置 Height 时,按照视频原始比例计算 Width
    Fps
    Request.Video
    帧率
    String
    值范围:(0,60]
    单位:fps
    Remove
    Request.Video
    是否删除视频流
    String
    false
    true、false
    Profile
    Request.Video
    编码级别
    String
    high
    支持 baseline、main、high
    baseline:适合移动设备
    main:适合标准分辨率设备
    high:适合高分辨率设备
    仅 H.264 支持此参数
    Bitrate
    Request.Video
    视频输出文件的码率
    String
    值范围:[10,50000]
    单位:Kbps
    Crf
    Request.Video
    码率-质量控制因子
    String
    值范围:(0,51]
    如果设置了 Crf,则 Bitrate 的设置失效
    Gop
    Request.Video
    关键帧间最大帧数
    String
    值范围:[0,100000]
    Preset
    Request.Video
    视频算法器预置
    String
    medium
    仅 H.264 支持该参数
    取值 veryfast、fast、medium、slow、slower
    Bufsize
    Request.Video
    缓冲区大小
    String
    值范围:[1000,128000]
    单位:Kb
    Maxrate
    Request.Video
    视频码率峰值
    String
    值范围:[10,50000]
    单位:Kbps
    HlsTsTime
    Request.Video
    hls分片时间
    String
    5
    (0 视频时长]
    单位为秒
    Pixfmt
    Request.Video
    视频颜色格式
    String
    支持 yuv420p、yuv422p、yuv444p、yuvj420p、yuvj422p、yuvj444p

    返回结果说明

    成功:返回 MediaTemplateResponse 对象响应信息,内含创建的模板详情。
    失败:发生错误(如 Bucket 不存在),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    请求示例

    //1.创建模板请求对象
    MediaTemplateRequest request = new MediaTemplateRequest();
    //2.添加请求参数 参数详情请见api接口文档
    request.setBucketName("examplebucket-1250000000");
    request.setTag("Animation");
    request.setName("TestTemplate40");
    request.getContainer().setFormat("gif");
    request.getVideo().setCodec("gif");
    request.getVideo().setWidth("1280");
    request.getVideo().setFps("15");
    request.getVideo().setAnimateOnlyKeepKeyFrame("true");
    request.getTimeInterval().setStart("0");
    request.getTimeInterval().setDuration("60");
    //3.调用接口,获取模板响应对象
    MediaTemplateResponse response = client.createMediaTemplate(request);

    删除模板

    功能说明

    删除一个模板

    方法原型

    public Boolean deleteMediaTemplate(MediaTemplateRequest request);

    参数说明

    参数名称
    描述
    类型
    必选
    bucketName
    Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述
    String
    templateId
    要取消的模板 id
    String

    返回结果说明

    成功: 返回一个布尔类型,删除成功则返回 true。
    失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    请求示例

    MediaTemplateRequest request = new MediaTemplateRequest();
    request.setBucketName("examplebucket-1250000000");
    request.setTemplateId("t19c4a60ae1a694621a01f0c7130c*****");
    Boolean response = client.deleteMediaTemplate(request);

    查询模板列表

    功能说明

    查询模板列表

    方法原型

    public MediaJobResponse describeMediaJob(MediaJobsRequest req);

    参数说明

    参数名称
    描述
    类型
    必选
    bucketName
    Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述
    String
    tag
    模板 Tag: Animation 动图,Snapshot 截图,Transcode 转码,Watermark 水印,SmartCover 智能封面
    String
    category
    Official,Custom,默认值:Custom
    String
    ids
    模板 ID,以,符号分割字符串
    String
    name
    模板名称前缀
    String
    pageNumber
    第几页
    Integer
    pageSize
    每页个数
    Integer

    返回结果说明

    成功: 返回模板响应包装类,其中包含模板详情集合 templateList。
    失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    请求示例

    //1.创建任务请求对象
    MediaTemplateRequest request = new MediaTemplateRequest();
    request.setBucketName("examplebucket-1250000000");
    MediaListTemplateResponse response = client.describeMediaTemplates(request);
    List<MediaTemplateObject> templateList = response.getTemplateList();

    修改模板

    功能说明

    修改模板

    方法原型

    public Boolean updateMediaTemplate(MediaTemplateRequest request);

    参数说明

    节点名称(关键字)
    描述
    类型
    必选
    bucketName
    Bucket 的命名规则为 BucketName-APPID,详情请参见 存储桶概述
    String
    templateId
    修改的模板 ID
    String
    说明:
    其余参数请参见 创建模板接口,与其参数一致。

    返回结果说明

    成功: 修改成功则返回 true。
    失败: 发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    请求示例

    MediaTemplateRequest request = new MediaTemplateRequest();
    request.setBucketName("examplebucket-1250000000");
    request.setTemplateId("t19c4a60ae1a694621a01f0c7130*****");
    request.setTag("Animation");
    request.setName("updateName");
    request.getContainer().setFormat("gif");
    Boolean aBoolean = client.updateMediaTemplate(request);
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持