全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

创建视频转码任务

最近更新时间:2026-11-18 14:05:03

视频转码(video/convert)是 KS3 视频处理服务提供的核心功能,将已压缩编码的视频码流转换为另一种视频码流,支持调整格式、封装、分辨率、帧率及码率等参数,适配不同设备和平台播放,同时缩减文件大小以优化传输效率。

1. 转码为异步处理,必须通过管道符 | 连接 sys/saveas 指定输出位置,处理完成后结果持久化到 KS3。

2. 不建议将输出路径与源文件路径设置为一致,否则会覆盖源文件。

3. 任务完成15天后,任务记录将自动被删除。

4. 单个UID QPS建议不超50,如有更大需求,请联系商务或提交工单申请。

5. 当前仅支持北京区域。

6. 源文件大小建议不超25GB,视频时长建议不超5小时。

使用场景

  • 多设备适配:手机、电视、网页播放器对视频格式要求不同。

  • 流媒体播放:转码生成不同码率的视频流,支持自适应码率播放。

  • 视频压缩:降低码率或使用高效编码(如 H.265),缩减文件大小,节省存储空间和带宽。

  • HLS 切片:转码并切分为 HLS 分片,用于 Web 流媒体播放,把一个长视频切成很多小段(HLS/DASH),实现流畅的在线播放。

操作方式

控制台操作方式

  1. 登录KS3控制台。

  2. 点击左侧的【存储空间】页签,进入存储空间列表。

  3. 点击目标存储空间名称,进入存储空间内,点击【数据处理】。

  4. 在数据处理目录下找到对应的页签【视频转码】。

  5. 点击【创建任务】。

  1. 输入相关配置信息:

具体配置描述如下:

模块

配置项

说明

输入输出设置

源文件路径

选择要进行视频转码的源文件。

目标存储桶

转码后投递的目标存储桶。

目标文件Key

转码后的目标文件Key。

设置回调

任务完成后触发回调的地址。

基础参数设置

输出格式

媒体容器类型。取值如下:

  • 音视频容器可选:mp4、mkv、mov、asf、avi、mxf、ts、flv、webm

  • 音频容器可选:mp3、aac、flac、oga、ac3、eac3、opus、amr

有关支持的容器格式与编码格式详情请参见:点击查看。

转码时长

支持可选:源文件时长、自定义时长。

视频参数设置

禁用视频流

默认不禁用。

编码格式

视频codec(编码格式)。取值如下:

  • copy(默认值):直接拷贝源视频流的编码格式,不进行重编码。

  • h264:h264编码格式

  • h265:h265编码格式

  • av1:av1编码格式

  • vp8:vp8编码格式

  • vp9:vp9编码格式

有关支持的容器格式与编码格式详情请参见:点击查看。

音频参数设置

禁用音频流

默认不禁用。

编码格式

音频codec(编码格式)。取值如下:

  • copy(默认值):将需要处理的音频流直接拷贝到输出文件。

  • mp3:mp3编码格式。

  • aac:aac编码格式。

  • flac:flac编码格式。

  • vorbis:vorbis编码格式。

  • ac3:ac3编码格式。

  • opus:opus编码格式。

  • amr:amr编码格式。

有关支持的容器格式与编码格式详情请参见:点击查看。

字幕设置

禁用字幕

默认不禁用。

  1. 点击【确认设置】,之后点击【创建并启动】,即完成任务创建。

API操作方式

操作名称:x-kss-async-process=video/convert

使用该功能的客户必须具有对源桶的ks3:GetObject和ks3:PostProcessTask权限,和目标桶的ks3:PutObject权限。

请求语法
POST /{object-key}?x-kss-async-process HTTP/1.1
Host: {bucket}.{endpoint}
x-kss-storage-class: {StorageClass}
Authorization: KSS {accessKey}:{signature}

x-kss-async-process=video/convert,{params}|sys/saveas,b_{bucket},o_{object}|callback,url_{回调地址}

1. 视频转码仅支持异步处理(需配合 sys/saveas 指定输出路径,且为必填)。

2. callback表示回调,url可传入具体的回调地址(需Base64编码),任务完成后会触发回调通知。该参数非必填,填写后KS3会采用公网推送。

3. sys/saveas支持填写变量,详情请参见:点击查看。

相关参数

分类

参数名称

说明

是否必选

基础参数

ss

起始时间,单位为毫秒。

  • 类型:int

取值如下:

  • 0(默认值):从起始位置开始

  • 大于0:从第ss毫秒开始

否

t

转码时长,单位为毫秒。

  • 类型:Int

取值如下:

  • 0(默认值):持续到视频结束位置

  • 大于0:持续t毫秒

否

视频参数

f

媒体容器类型。

  • 类型:String

取值如下:

  • 音视频容器可选:mp4、mkv、mov、asf、avi、mxf、ts、flv、webm

  • 音频容器可选:mp3、aac、flac、oga、ac3、eac3、opus、amr

有关支持的容器格式与编码格式详情请参见:点击查看。

是

vn

是否禁用视频流。

  • 类型:Int

取值如下:

  • 0(默认值):不禁用

  • 1:禁用,输出文件中将不包含视频流,仅输出音频

设置 vn=1 时,f 参数必须选择音频容器格式(如 mp3/aac/flac),否则会失败。

否

vcodec

视频codec(编码格式)。

  • 类型:String

取值如下:

  • copy(默认值):直接拷贝源视频流的编码格式,不进行重编码。

  • h264:h264编码格式

  • h265:h265编码格式

  • av1:av1编码格式

  • vp8:vp8编码格式

  • vp9:vp9编码格式

有关支持的容器格式与编码格式详情请参见:点击查看。

否

fps

视频帧率。取值范围:0~240。

  • 类型:float

不填写时默认为源视频帧率。

否

fpsopt

视频帧率选项。

  • 类型:Int

取值如下:

  • 0(默认):始终使用目标帧率

  • 1:源视频帧率小于fps时使用源视频帧率

  • 2:源视频帧率小于fps时返回失败

否

pixfmt

像素采样格式,默认与源视频一致。它主要影响色彩精度、色带问题以及 HDR 支持等高级特性。

  • 类型:String

取值如下:

  • yuv420p

  • yuva420p

  • yuv420p10le

  • yuv422p

  • yuv422p10le

  • yuv444p

  • yuv444p10le

否

s

目标分辨率,格式为w x h,即宽 x 高。

  • 类型:String

1. 不填写时默认为原视频宽高。

2. 宽和高的取值应为2的倍数,且取值范围为64~4096。例如:4096x4096、64x64等。

否

sopt

分辨率选项。

  • 类型:Int

取值如下:

  • 0(默认):始终使用目标分辨率

  • 1:源视频分辨率小于s时使用源视频分辨率

  • 2:源视频分辨率小于s时返回失败

否

scaletype

缩放方式。

  • 类型:String

取值如下:

  • stretch(默认值):固定宽高或长短边,强制缩放,拉伸以填满空白部分。拉伸填满,画面可能变形。

  • crop:等比缩放,缩放为延伸出指定宽高或长短边的矩形框外的最小分辨率,然后将超出的部分进行居中裁剪。等比缩放并裁剪,保持画面比例,多余部分裁剪。

  • fill:等比缩放,缩放为指定宽高或长短边的矩形内的最大分辨率,然后使用黑色居中填充空白部分。等比缩放保留黑边,画面完整但可能有黑边。

  • fit:等比缩放,缩放为指定宽高或长短边的矩形内的最大分辨率。等比缩放不保留黑边,画面适配目标尺寸。

否

arotate

长短边自适应。

  • 类型:Int

取值如下:

  • 0(默认值):关闭,不旋转

  • 1:打开,根据旋转元数据自动交换宽高

否

g

关键帧。

  • 类型:Int

  • 取值范围:1~100000

否

vb

视频比特率(码率),单位为比特/秒(bps)。

  • 类型:Int

  • 取值范围:10000~100000000

vb(固定码率模式)和 crf(质量控制因子模式)只能二选一,不能同时设置。

否

vbopt

视频码率选项。

  • 类型:Int

取值如下:

  • 0(默认):始终使用目标视频码率

  • 1:源视频码率小于vb时使用源视频码率

  • 2:源视频码率小于vb时返回失败

否

videoslim

轻码高清模式。

  • 类型:Int

取值如下:

  • 0:默认值,表示关闭

  • 1:表示使用轻码高清模式转码

仅在以下条件同时满足时有效:h264 或 h265 编码 + yuv420p 像素格式 + 8bit 色深,其他组合下设置无效。

否

crf

码率控制因子。

  • 类型:float

  • 取值范围:0~51

crf 与 vb 互斥,不支持同时设置。

否

maxrate

峰值码率,单位为比特/秒(bps)。

  • 取值范围:10000~100000000

  • 类型:Int

此参数需与 crf 同设,单独使用无效。若使用 vb 模式则不需要此参数,此时该参数不生效。

否

bufsize

缓冲区大小,单位为比特(bits)。

  • 取值范围:10000~200000000

  • 类型:Int

bufsize 需与 crf 同时设置。

否

音频参数

an

是否禁用音频流。

  • 类型:Int

取值如下:

  • 0(默认值):不禁用

  • 1:禁用,输出文件中将不包含音频流,仅输出视频

否

acodec

音频codec(编码格式)。

  • 类型:String

取值如下:

  • copy(默认值):将需要处理的音频流直接拷贝到输出文件。

  • mp3:mp3编码格式。

  • aac:aac编码格式。

  • flac:flac编码格式。

  • vorbis:vorbis编码格式。

  • ac3:ac3编码格式。

  • opus:opus编码格式。

  • amr:amr编码格式。

  • eac3:eac3编码格式。

  • ​pcm:​pcm编码格式。

有关支持的容器格式与编码格式详情请参见:点击查看。

否

ar

音频采样率。

  • 类型:Int

取值如下:

  • 8000

  • 11025

  • 12000

  • 16000

  • 22050

  • 24000

  • 32000

  • 44100

  • 48000

  • 88200

  • 96000

否

ac

音频声道数。默认保持源音频的声道数。

  • 取值范围:1~8。

  • 类型:Int

mp3 格式仅支持设置为1或2;ac3 格式最多支持设置为6;amr 格式仅支持设置为1。

否

aq

音频压缩质量。

  • 取值范围:0~100。

  • 类型:Int

aq与ab互斥,两者不支持同时设置。

否

ab

音频比特率(码率),单位为比特/秒(bps)。

  • 取值范围:1000~10000000

ab与aq互斥,两者不支持同时设置。

否

abopt

音频码率选项。

  • 类型:Int

取值如下:

  • 0(默认值):始终使用目标音频码率

  • 1:源音频码率小于ab时使用源音频码率

  • 2:源音频码率小于ab时返回失败

abopt需与ab同时设置才会生效。

否

adepth

音频采样位深。

  • 取值:16、24

  • 类型:Int

该参数仅在acodec为flac时有效。

否

字幕参数

sn

是否禁用字幕。

  • 类型:Int

取值如下:

  • 0(默认值):不禁用

  • 1:禁用,输出文件中将不包含字幕

否

媒体分片参数

segment

媒体切片设置,默认不进行切片。

  • 类型:String

否

f

媒体切片方式(协议类型)。

  • 类型:String

取值如下:

  • hls

  • dash

设置hls或dash时,封装格式f仅支持设置为mp4或ts,设置其他类型将报错。

否

t

每个切片时长,单位为毫秒。

  • 取值范围:0~3600000

  • 类型:Int

设置hls或dash时,封装格式f仅支持设置为mp4或ts,设置其他类型将报错。

否

响应体
{
  "requestId": "a1b2c3d4e5f6****",
  "processId": "MediaConvert-1234567890"
}

响应体内参数描述如下:

字段

类型

说明

requestId

string

请求唯一标识。

processId

string

任务 ID,任务创建成功后,KS3会自动返回该参数,每个任务对应唯一的任务ID,用于查询任务状态。

请求示例
  • 示例1:avi 转 mp4(标准转码)

    将 avi 视频转码为 mp4,视频编码 h265,目标分辨率 1080p,视频帧率 30fps,视频码率 2Mbps,音频编码格式aac,码率100Kbps,禁用字幕:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,f_mp4,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L3NhbXBsZS5tcDQ=

  • 示例2:视频片段剪辑(无损拷贝)

    截取视频第 30 秒并持续60秒的片段,音视频流直接拷贝不重编码:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,ss_30000,t_60000,f_mp4,vcodec_copy,acodec_copy|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L2NsaXAubXA0

  • 示例3:提取音频为 mp3

    从视频中提取音频,输出为 mp3 格式,设置码率128Kbps ,禁用视频流和字幕流:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,f_mp3,acodec_mp3,ab_128000,vn_1,sn_1|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L2F1ZGlvLm1wMw==

  • 示例4:hls 切片转码

    将视频转码为 h264,设置码率1Mbps,输出为 ts 容器的 hls 切片,每片 30 秒,从第 10 秒开始持续 60 秒:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,ss_10000,t_60000,f_ts,vcodec_h264,vb_1000000,acodec_mp3,ab_100000/segment,f_hls,t_30000|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L2hscy9wbGF5bGlzdC5tM3U4

  • 示例5:crf 恒定质量转码

    使用 crf 模式,设置质量因子 28,峰值码率限制 3Mbps,缓冲区 6Mbits:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,f_mp4,vcodec_h264,s_1280x720,crf_28,maxrate_3000000,bufsize_6000000,acodec_aac,ab_128000|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L2NvbXByZXNzZWQubXA0

  • 示例6:轻码高清模式

    启用轻码高清模式(videoslim),在保持视觉质量的前提下降低码率:

POST /objectname?x-kss-async-process HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
x-kss-storage-class: STANDARD
Authorization: authorization string

x-kss-async-process=video/convert,f_mp4,vcodec_h264,vb_1500000,videoslim_1,s_1920x1080,acodec_aac,ab_128000|sys/saveas,b_bXlidWNrZXQ=,o_b3V0cHV0L3NsaW0ubXA0

响应示例
{
  "requestId": "a1b2c3d4e5f6****",
  "processId": "MediaConvert-1234567890"
}

错误码

HTTP状态码

错误码

描述

400 Bad Request

InvalidRequest

  • 请求不合法。

  • 请求体为空。

  • 重复填写某个参数。

400 Bad Request

InvalidArgument

必填的参数没有填写或为空、参数无效、参数值不合法。

403 Forbidden

AccessDenied

没有权限。

404 Not Found

NoSuchBucket

桶不存在。

费用

视频转码当前邀测期间暂不收费,邀测结束后开始根据编码格式和目标分辨率收费。

其他说明

sys/saveas变量说明

sys/saveas支持填写变量,统一采用 {变量名} 格式。

1. 变量不区分大小写。

2. 未定义的变量会原样保留(如 {invalid} 会作为普通字符串处理)。

3. sys/saveas填写的桶名称和文件的Key需要经过URL Safe的Base64编码。

sys/saveas支持以下变量:

变量名

含义

示例值

{filename}

源文件名(不含扩展名)

源文件 course/lesson1.mp4 → lesson1

{format}

输出容器格式(f 参数值)

mp4、ts、m3u8

{width}

输出视频宽度(w 参数值)

1280

{height}

输出视频高度(h 参数值)

720

{vcodec}

输出视频编码

h264、h265

{processId}

任务 ID

MediaConvert-b3b70350-abce-4f46-80f1-db5bdbe9a57d

{bucket}

源存储桶

bucketname

{key}

源对象Key

prefix/1.mp4

格式说明

不同容器格式支持的编码格式如下所示:

容器格式(f)

视频编码格式(Video Codecs)

音频编码格式(Audio Codecs)

mp4

h264, h265, av1, vp9

aac, mp3, ac3, eac3, opus, flac, vorbis, pcm

mkv

h264, h265, av1, vp8, vp9

aac, mp3, ac3, eac3, opus, flac, amr, vorbis, pcm

mov

h264, h265

aac, mp3, ac3, eac3, amr, vorbis, pcm

asf

h264, vp8, vp9, av1

mp3, ac3, eac3, amr, aac, flac, vorbis, pcm

avi

h264, h265, vp8, vp9, av1

mp3, ac3, eac3, pcm, aac, flac, vorbis, amr

mxf

h264

pcm

ts

h264, h265, vp8, vp9, av1

aac, mp3, ac3, eac3, flac, vorbis, opus, amr, pcm

flv

h264, h265, vp9, av1

aac, mp3, flac, ac3, eac3, opus

webm

vp8, vp9, av1

opus, vorbis

mp3

—

mp3

aac

—

aac

flac

—

flac

oga

—

vorbis, opus, flac

ac3

—

ac3

eac3

—

eac3

opus

—

opus, flac, vorbis

amr

—

amr

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈