POSTTemplate

最近更新时间:2019-12-12 17:20:41

功能描述

创建自定义模板,包含容器格式、视频转码配置设置。

请求

请求示例

POST /template HTTP/1.1
Host: <BucketName-APPID>.ci.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
Content-Length: <length>
Content-Type: application/xml
<body>
说明:

Authorization: Auth String (详情请查阅 请求签名 文档)。

请求头

此接口仅使用公共请求头部,详情请参见 公共请求头部 文档。

请求体

该请求操作的实现需要有如下请求体。

<Request>
   <Tag>Animation</Tag>
   <Name>Template Name</Name>
   <Container>
      <Format>mp4</Format>
   </Container>
   <Video>
      <Codec>GIF</Codec>
      <Profile>high</Profile>
      <Bitrate>10-50000</Bitrate>
      <Crf>0-51</Crf>
      <Width>128-4096</Width>
      <Height>128-4096</Height>
      <Fps>1-60</Fps>
      <Gop>1-100000</Gop>
      <Preset>fast</Preset>
      <ScanMode>interlaced</ScanMode>
      <Bufsize>1000-128000</Bufsize>
      <Maxrate>10-50000</Maxrate>
      <PixFmt>yuv420p</PixFmt>
      <Remove>false</Remove>
      <Crop>border</Crop>
      <Pad></Pad>
      <LongShortMode>false</LongShortMode>
   </Video>
   <Audio>
      <Codec>AAC</Codec>
      <Profile>aac_he</Profile>
      <Samplerate>44100</Samplerate>
      <Bitrate>8</Bitrate>
      <Channels>2</Channels>
      <Remove>false</Remove>
   </Audio>
   <TransConfig>
      <TransMode>onepass</TransMode>
      <IsCheckReso>true</IsCheckReso>
      <IsCheckVideoBitrate>true</IsCheckVideoBitrate>
      <IsCheckAudioBitrate>true</IsCheckAudioBitrate>
   </TransConfig>
   <TimeInterval>
      <Start></Start>
      <Duration></Duration>
   </TimeInterval>
</Request>

<Request>
   <Tag>Snapshot</Tag>
   <Name>Template Name</Name>
   <Snapshot>
      <Width>128-4096</Width>
      <Height>128-4096</Height>
      <Start></Start>
      <TimeInterval></TimeInterval>
      <Count></Count>
   </Snapshot>
</Request>

具体数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选
Request 保存请求的容器 Container

Container 类型 Request 的具体数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选 限制
Tag Request 模板类型 Animation,Snapshot String 长度限制100字符
Name Request 模板名称 String 长度限制100字符
Container Request 容器格式 Container
Video Request 视频信息 Container
Audio Request 音频信息 Container
TransConfig Request 转码配置 Container
Snapshot Request 截图 Container

Container 类型 Container 的具体数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
Format Request.Container 容器格式 String mp4 参考 容器格式和视频音频编解码格式支持情况 表格

Container 类型 Video 的具体数据描述如下:

节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
Codec Request.Video 编解码格式 String H.264 可选值为:GIF、WEBP
Profile Request.Video 编码级别 String high 1. 支持 baseline、main、high
2. baseline:适合移动设备
3. main:适合标准分辨率设备
4. high:适合高分辨率设备
Bitrate Request.Video 视频的码率 String 1. 值范围:[10,50000]
2. 单位:Kbps
Crf Request.Video 码率-质量控制因子 String 26 1. 值范围:[0,51]
2. 如果设置了 Crf,则 Bitrate 的设置失效
Width Request.Video String 视频原始宽度 1. 值范围:[128,4096]
2. 单位:px
Height Request.Video String 视频原始高度 1. 值范围:[128,4096]
2. 单位:px
Fps Request.Video 帧率 String 视频原始帧率 1. 值范围:(0,60]
2. 单位:fps
3. 帧率超过60时,设置为60
Gop Request.Video 关键帧间最大时间间隔或者最大帧数 String 10s 1. 值范围:[0,100000]
2. 最大时间间隔单位 s
3. 最大帧数无单位
Preset Request.Video 视频算法器预置 String medium 1. H.264 支持该参数
2. veryfast、fast、medium、slow、slower
ScanMode Request.Video 扫描模式 String interlaced、progressive
Bufsize Request.Video 缓冲区大小 String 6000 1. 值范围:[1000,128000]
2. 单位:Kb
Maxrate Request.Video 视频码率峰值 String 6000 1. 值范围:[10,50000]
2. 单位:Kbps
PixFmt Request.Video 视频颜色格式 String yuv420p yuv420p、yuvj420p
Remove Request.Video 是否删除视频流 String false true、false
Crop Request.Video 视频画面裁切 String 1. 自动监测黑边并裁切:border
2. 自定义裁切:width:height:left:top
Pad Request.Video 视频贴黑边 String width:height:left:top
LongShortMode Request.Video 是否开启横竖屏自适应 String false true、false
AnimateOnlyKeepKeyFrame Request.Video 动图只保留关键帧 String false true、false
AnimateTimeIntervalOfFrame Request.Video 动图抽帧间隔时间 String 1 1. (0,视频时长]
2. 若设置 TimeInterval.Duration,则小于该值
AnimateFramesPerSecond Request.Video Animation 每秒抽帧帧数 String 1 (0,视频帧率)
Quality Request.Video 设置相对质量 String 1

动图转码参数说明:

参数 描述
动图相关参数 包括有 AnimateOnlyKeepKeyFrame、AnimateTimeIntervalOfFrame、AnimateFramesPerSecond。
  • 优先级:AnimateFramesPerSecond > AnimateOnlyKeepKeyFrame > AnimateTimeIntervalOfFrame
  • 优先级高的设置生效,那么其他的忽略。要求有一个设置,其他两个为0
  • Fps 帧率 用户可以设置 fps,如果不设置,那么播放速度按照原来的时间戳。这里设置 fps 为动图的播放帧率
    Width Heidht 转码之后的宽高
    Quality 质量参数 webp 图像质量设定生效,gif 没有质量参数设置。默认输出为无限循环

    Container 类型 Audio 的具体数据描述如下:

    节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
    Codec Request.Audio 编解码格式 String AAC AAC、MP3
    Profile Request.Audio 音频编码预置 String 1. 仅支持 AAC 编码
    2. aac_low、aac_he、aac_ld、aac_eld
    Samplerate Request.Audio 采样率 String 44100 单位:Hz。可选值为:44100、32000、44100、48000、96000
    Bitrate Request.Audio 原始音频码率 String 128 1. 单位:Kbps
    2. 值范围:[8,1000]
    Channels Request.Audio 声道数 String 2 1. 当 Codec 设置为 aac,支持1、2、4、5、6、8
    2. 当 Codec 设置为 mp3,支持1、2
    Remove Request.Audio 是否删除音频流 String false true、false

    Container 类型 TransConfig 的具体数据描述如下:

    节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
    TransMode Request.TransConfig 转码模式 String onepass 可选值为:onepass、twopass、CBR
    IsCheckReso Request.TransConfig 是否检查分辨率 String false 如果分辨率大于视频原始分辨率,则保持视频原始分辨率。可选值为:true、false
    IsCheckVideoBitrate Request.TransConfig 是否检查视频码率 String false 如果码率大于视频原始码率,则保持视频原始码率。可选值为:true、false
    IsCheckAudioBitrate Request.TransConfig 是否检查音频码率 String false 如果码率大于音频原始码率,则保持视频音频码率。可选值为:true、false

    Container 类型 TimeInterval 的具体数据描述如下:

    节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
    Start Request.TimeInterval 开始时间 String 0 [0,视频时长]
    Duration Request.TimeInterval 持续时间 String 视频时长 [0,视频时长]

    Container 类型 Snapshot 的具体数据描述如下:

    节点名称(关键字) 父节点 描述 类型 是否必选 默认值 限制
    Start Request.Snapshot 开始时间 String 0 [0,视频时长]
    TimeInterval Request.Snapshot 截图频率 String 0 [0,10]
    Count Request.Snapshot 截图数量 String 0 [0,100]
    Width Request.Snapshot String 视频原始宽度 1. 值范围:[128,4096]
    2. 单位:px
    Height Request.Snapshot String 视频原始高度 1. 值范围:[128,4096]
    2. 单位:px

    容器格式与视频音频编解码格式支持情况如下:

    Container Audio Codec Video Codec
    gif 不支持音频 GIF
    webp 不支持音频 WEBP
    m3u8 AAC、MP3 H.264、H.265
    flv AAC、MP3 H.264
    mp4 AAC、MP3 H.264、H.265

    视频编码格式与视频流配置参数支持情况如下:

    Video Codec H.264 H.265 GIF
    Profile 支持 不支持 不支持
    Bitrate 支持 支持 不支持
    Crf 支持 支持 不支持
    Width 支持 支持 支持
    Height 支持 支持 支持
    Fps 支持 支持 支持
    Gop 支持 支持 不支持
    Preset 支持 不支持 不支持
    ScanMode 支持 支持 支持
    Bufsize 支持 支持 不支持
    Maxrate 支持 支持 不支持
    PixFmt 支持 支持 不支持

    响应

    响应头

    此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

    响应体

    该响应体返回为 application/xml 数据,包含完整节点数据的内容展示如下:

    <Response>
        <Name>Template Name</Name>
        <TemplateID></TemplateID>
        <Tag>Animation</Tag>
        <TransTpl>
          <Container>
             <Format>mp4</Format>
          </Container>
          <Video>
             <Codec>GIF</Codec>
             <Profile>high</Profile>
             <Bitrate>10-50000</Bitrate>
             <Crf>0-51</Crf>
             <Width>128-4096</Width>
             <Height>128-4096</Height>
             <Fps>1-60</Fps>
             <Gop>1-100000</Gop>
             <Preset>fast</Preset>
             <ScanMode>interlaced</ScanMode>
             <Bufsize>1000-128000</Bufsize>
             <Maxrate>10-50000</Maxrate>
             <PixFmt>yuv420p</PixFmt>
             <Remove>false</Remove>
             <Crop>border</Crop>
             <Pad></Pad>
             <LongShortMode>false</LongShortMode>
          </Video>
          <Audio>
             <Codec>AAC</Codec>
             <Profile>aac_he</Profile>
             <Samplerate>44100</Samplerate>
             <Bitrate>8</Bitrate>
             <Channels>2</Channels>
             <Remove>false</Remove>
          </Audio>
          <TransConfig>
             <TransMode>onepass</TransMode>
             <IsCheckReso>true</IsCheckReso>
             <IsCheckVideoBitrate>true</IsCheckVideoBitrate>
             <IsCheckAudioBitrate>true</IsCheckAudioBitrate>
          </TransConfig>
          <TimeInterval>
             <Start></Start>
             <Duration></Duration>
          </TimeInterval>
       </TransTpl>
       <CreateTime></CreateTime>
       <UpdateTime></UpdateTime>
    </Response>

    错误码

    该请求操作可能会出现如下错误信息,常见的错误信息请参见 错误码 文档。

    错误码 描述 HTTP 状态码
    InternalErrror 服务端内部错误 500 Internal Server
    AccessDenied 签名或者权限不正确,拒绝访问 403 Forbidden

    实际案例

    截帧示例

    请求

    POST /template HTTP/1.1
    Authorization:q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR98JM&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0ea057
    Host:bucket-1250000000.ci.ap-beijing.myqcloud.com
    Content-Length: 1666
    Content-Type: application/xml
    
    <Request>
        <Name>Template Name</Name>
        <Tag>Animation</Tag>
        <Container>
            <Format>mp4</Format>
        </Container>
        <Video>
            <Codec>GIF</Codec>
            <Profile>high</Profile>
            <Bitrate>10-50000</Bitrate>
            <Crf>0-51</Crf>
            <Width>128-4096</Width>
            <Height>128-4096</Height>
            <Fps>1-60</Fps>
            <Gop>1-100000</Gop>
            <Preset>fast</Preset>
            <ScanMode>interlaced</ScanMode>
            <Bufsize>1000-128000</Bufsize>
            <Maxrate>10-50000</Maxrate>
            <PixFmt>yuv420p</PixFmt>
            <Remove>false</Remove>
            <Crop>border</Crop>
            <Pad></Pad>
            <LongShortMode>false</LongShortMode>
        </Video>
        <Audio>
            <Codec>AAC</Codec>
            <Profile>aac_he</Profile>
            <Samplerate>44100</Samplerate>
            <Bitrate>8</Bitrate>
            <Channels>2</Channels>
            <Remove>false</Remove>
        </Audio>
        <TransConfig>
            <TransMode>onepass</TransMode>
            <IsCheckReso>true</IsCheckReso>
            <IsCheckVideoBitrate>true</IsCheckVideoBitrate>
            <IsCheckAudioBitrate>true</IsCheckAudioBitrate>
        </TransConfig>
        <TimeInterval>
            <Start></Start>
            <Duration></Duration>
        </TimeInterval>
    </Request>

    响应

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 100
    Connection: keep-alive
    Date: Thu, 15 Jun 2017 12:37:29 GMT
    Server: tencent-ci
    x-ci-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhfMjc=
    
    <Response>
        <Tag>Animation</Tag>
        <Name>Template Name</Name>
        <TemplateID></TemplateID>
        <TransTpl>
          <Container>
             <Format>mp4</Format>
          </Container>
          <Video>
             <Codec>GIF</Codec>
             <Profile>high</Profile>
             <Bitrate>10-50000</Bitrate>
             <Crf>0-51</Crf>
             <Width>128-4096</Width>
             <Height>128-4096</Height>
             <Fps>1-60</Fps>
             <Gop>1-100000</Gop>
             <Preset>fast</Preset>
             <ScanMode>interlaced</ScanMode>
             <Bufsize>1000-128000</Bufsize>
             <Maxrate>10-50000</Maxrate>
             <PixFmt>yuv420p</PixFmt>
             <Remove>false</Remove>
             <Crop>border</Crop>
             <Pad></Pad>
             <LongShortMode>false</LongShortMode>
          </Video>
          <Audio>
             <Codec>AAC</Codec>
             <Profile>aac_he</Profile>
             <Samplerate>44100</Samplerate>
             <Bitrate>8</Bitrate>
             <Channels>2</Channels>
             <Remove>false</Remove>
          </Audio>
          <TransConfig>
             <TransMode>onepass</TransMode>
             <IsCheckReso>true</IsCheckReso>
             <IsCheckVideoBitrate>true</IsCheckVideoBitrate>
             <IsCheckAudioBitrate>true</IsCheckAudioBitrate>
          </TransConfig>
          <TimeInterval>
             <Start></Start>
             <Duration></Duration>
          </TimeInterval>
       </TransTpl>
       <CreateTime></CreateTime>
       <UpdateTime></UpdateTime>
    </Response>

    视频转动图示例

    请求

    POST /template HTTP/1.1
    Authorization:q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR98JM&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=28e9a4986df11bed0255e97ff90500557e0ea057
    Host:bucket-1250000000.ci.ap-beijing.myqcloud.com
    Content-Length: 1666
    Content-Type: application/xml
    
    <Request>
       <Tag>Snapshot</Tag>
       <Name>Template Name</Name>
       <Snapshot>
          <Width>128-4096</Width>
          <Height>128-4096</Height>
          <Start></Start>
          <TimeInterval></TimeInterval>
          <Count></Count>
       </Snapshot>
    </Request>

    响应

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 100
    Connection: keep-alive
    Date: Thu, 15 Jun 2017 12:37:29 GMT
    Server: tencent-ci
    x-ci-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhfMjc=
    
    <Response>
       <Tag>Snapshot</Tag>
       <Name>Template Name</Name>
       <TemplateID></TemplateID>
       <Snapshot>
          <Width>128-4096</Width>
          <Height>128-4096</Height>
          <Start></Start>
          <TimeInterval></TimeInterval>
          <Count></Count>
       </Snapshot>
       <CreateTime></CreateTime>
       <UpdateTime></UpdateTime>
    </Response>