# 视频转码服务

# 服务说明

视频转码服务是新浪云自研的视频转码服务,提供不同码率的视频转码、抽帧、附加logo等操作,服务以异步方式运行。

# 开启服务

创建任意类型的云应用,从“增值服务”中选择“视频转码服务”,开启服务即可使用。

# 服务价格

转码服务按转码的消耗时间计费。成功时计费,实时从账户的云豆余额扣除,失败时不计费。具体的服务单价可以从新浪云服务价格处查询。

# 服务接口

# 添加视频转码任务

# 接口地址

https://g.sinacloud.com/sve/_api/task/transcode_video

# 接口请求方式

POST

# 接口验证

接口需要通过认证后才能调用,认证的账号为应用的accesskeysecretkey,验证的规则说明请参考签名规则章节。

# 接口参数

参数 是否必填 说明
video_src 视频的下载地址
video_codec 支持h264,默认h264
priority 任务的优先级,默认为1,数字越小优先级越高
definition 待转码的视频的清晰度,支持'SD', 'HD', 'FHD', 'BLUE',默认为SD
tag 标识字段,最大32个字符
intro 任务说明,最大128个字符
callback_url 任务的回调地址,如果服务配置了全局回调,当前任务的回调优先级高于全局配置,视频的探测信息完成、任务完成时会分别回调,回调的参数如下文说明
storage_provider 视频转码完成后的存储类别,当前仅支持scs
scs_accesskey 存储类别为scs时必填,云存储服务的accesskey
scs_secretkey 存储类别为scs时必填,云存储服务的secretkey
scs_bucket 存储类别为scs时必填,云存储服务的bucket名称
scs_acl 转码服务上传到云存储的文件的ACL类型,支持'public_read', 'private', 'public-read-write', 'authenticated-read',默认为public_read
logo_name 加水印的图片名称,如果需要打水印,此字段必填
logo_url 水印图片的下载地址,需要能从公网访问,建议使用PNG图片
logo_position 水印图片相对于视频的位置,支持'right-top', 'right-bottom', 'left-top', 'left-bottom',默认为left-top,表示左上角
audio_bitrate 音频的比特率,支持'64k', '128k',默认64k
audio_codec 音频的编码,支持aac,默认aac
audio_sample 音频的采样率,支持44100, 48000, 88200, 96000,默认44100
screenshot_enable 是否开启抽帧,1表示开启,0表示不开启
screenshot_time 抽帧的时间,表示距离视频播放起点的秒数,默认为2

# 接口返回

接口返回一个json字符串,其中固定包含:

  • code 字段,为0时表示请求成功,非0时表示失败,失败时message中会包含错误信息
  • message 字段,包含说明信息

如果code为0时,包含data字段,包含trace_id信息,表示当前转码服务的任务编号,任务编号是一个UUID,成功时返回的JSON示例如下:

{
	"code": 0,
	"message": "success",
	"data": "43a932c6-84c8-46b8-9fac-2de359cabae0"
}

# 查询任务的执行状态

# 接口地址

https://g.sinacloud.com/sve/_api/result/query

# 接口请求方式

POST

# 请求参数

接口参数 是否必填 说明
trace_id 添加任务成功时返回的trace_id

# 返回信息

接口返回JSON字符串,成功时返回的字段中code为0,格式如下:

{
	"code": 0,
	"message": "success",
	"data": {
		"task_info": {
			"priority": "1",
			"tag": "aa",
			"intro": "这是测试说明"
		},
		"media_info": {
			"status": "DONE",
			"message": "",
			"width": "848",
			"height": "478",
			"bitrate": "0",
			"fps": "23",
			"duration": "182234"
		},
		"sub_tasks_info": {
			"SD": {
				"video_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/sd\/output\/43a932c6-84c8-46b8-9fac-2de359cabae0.mp4",
				"cover_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/sd\/cover\/cover.jpg",
				"codec": "h264",
				"status": "DONE",
				"message": "",
				"definition": "SD"
			},
			"HD": {
				"video_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/output\/43a932c6-84c8-46b8-9fac-2de359cabae0.mp4",
				"cover_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/cover\/cover.jpg",
				"codec": "h264",
				"status": "DONE",
				"message": "",
				"definition": "HD"
			}
		}
	}
}

失败时,code字段非0,错误信息会在message中体现,格式如下:

{
	"code": 3,
	"message": "任务不存在"
}

# 返回的字段说明

返回的信息格式:

字段 是否一定存在 类型 说明
code int 0表示成功,非0表示失败,失败时message字段表示错误原因
message string 表示额外的说明信息
data Data code非0时不存在,为0时一定存在,格式如下

Data类型格式:

字段 是否一定存在 类型 说明
task_info TaskInfo 表示任务的元信息
media_info MediaInfo 当前视频的元信息
sub_tasks_info SubTaskInfo数组 key表示转码的清晰度类别,值为SubTaskInfo

TaskInfo类型格式:

字段 是否一定存在 类型 说明
priority string 任务的优先级,和创建任务时的优先级一致
tag string 任务的tag,和创建任务时传入的tag一致
intro string 任务的说明,和创建任务时传入的一致

MediaInfo类型的格式如下:

字段 是否一定存在 类型 说明
status string 当前视频原信息探测的进度,支持PENDING,ERROR,DONE,分别表示等待中,探测出错,已完成
message string 如果任务为ERROR状态时,此字段表示出错的具体出错原因
width int 视频的宽度
height int 视频的高度
bitrate int 视频的比特率
fps int 视频的帧率
duration int 视频的时间长度,单位毫秒

SubTaskInfo类型的格式如下:

字段 是否一定存在 类型 说明
video_object string 视频转码成后存储的路径
cover_object string 抽帧完成后的存储路径
codec string 视频编码类型,当前返回h264等
status string 当前子任务的转码状态,为PENDING、ERROR、DONE分别表示等待中、出错、完成
message string 当子任务的状态为ERROR时描述出错的具体原因
definition string 当前子任务的转码清晰度,例如SD

# 服务回调

除通过接口提交trace_id查询任务的执行状态外,转码服务在以下事件完成时会主动回调配置的回调接口。

  • 视频探测信息完成
  • 转码任务拆分的子任务完成时,例如同时提交SD、HD两种类别的转码任务时,SD、HD会分别触发回调

# 服务回调的最大超时时间

回调接口应该在5秒内应答,在5秒内未应答,转码服务任务回调失败,会重新触发回调。

# 回调成功标识

当配置的回调接口返回的状态码为200时,转码服务认为回调已经触达,非200时会触发重机制。

# 回调机制

当回调接口返回非200状态码时,系统会每间隔1分钟最多回调10次,超出10次时不再回调。

# 回调的参数格式

# 视频元信息回调格式

转码任务添加后,会自动添加一个视频元信息探测任务,用于获取视频的长宽信息、码率、时长等信息,信息探测完成后,在配置了回调时,会向回调接口主动POST一个JSON数据,数据格式如下:

{
	"callback_type": "media_info",
	"trace_id": "43a932c6-84c8-46b8-9fac-2de359cabae0",
	"status": "DONE",
	"message": "",
	"media_info": {
		"width": "848",
		"height": "478",
		"bitrate": "0",
		"fps": "23",
		"duration": "182234"
	}
}

如何接收参数

以PHP为例,可以通过file_get_contents('php://input')获取POST的JSON数据。

参数的说明如下:

字段 是否一定存在 类型 说明
callback_type string 此处固定为media_info,表示视频元信息回调
trace_id string 任务的trace_id
status string 为ERROR或者DONE,分别表示出错或者已完成
message string 如果status为ERROR时,此字段表示具体的出错原因
media_info MediaInfo 视频的元信息

MediaInfo类型的格式如下:

字段 是否一定存在 类型 说明
width int 视频的宽度
height int 视频的高度
bitrate int 视频的比特率
fps int 视频的帧率
duration int 视频的时间长度,单位毫秒

# 转码任务回调格式

转码任务添加后,会自动根据待转码的清晰度拆分为多个转码子任务,子任务完成后,在配置了回调时,会向回调接口主动POST一个JSON数据,数据格式如下:

{
	"callback_type": "sub_task",
	"trace_id": "43a932c6-84c8-46b8-9fac-2de359cabae0",
	"status": "DONE",
	"message": "",
	"sub_task": {
		"definition": "HD",
		"video_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/output\/43a932c6-84c8-46b8-9fac-2de359cabae0.mp4",
		"cover_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/cover\/cover.jpg",
		"codec": "h264"
	}
}

回调的参数格式如下:

字段 是否一定存在 类型 说明
callback_type string 此处固定为media_info,表示视频元信息回调
trace_id string 任务的trace_id
status string 为ERROR或者DONE,分别表示出错或者已完成
message string 如果status为ERROR时,此字段表示具体的出错原因
sub_task SubTask 子任务的详细信息

SubTask的格式如下:

字段 是否一定存在 类型 说明
video_object string 视频转码成后存储的路径
cover_object string 抽帧完成后的存储路径
codec string 视频编码类型,当前返回h264等
definition string 当前子任务的转码清晰度,例如SD

# 示例

# PHP添加转码任务示例

<?php
require('gapi.php');
use sinacloud\sae\Gapi;
$i = new Gapi(SAE_ACCESSKEY, SAE_SECRETKEY);

$post_data = array();
$post_data['callback_url'] = 'http://gequ.sinaapp.com/callback.php';
$post_data['intro'] = '这是测试说明';
$post_data['tag'] = 'aa';
$post_data['video_src'] = 'http://sinacloud.net/opensource/zhihu2018_sd.mp4';
$post_data['definition'] = 'SD,HD';
// storage
$post_data['storage_provider'] = 'scs';
$post_data['scs_accesskey'] = '云存储的accesskey';
$post_data['scs_secretkey'] = '云存储的secretkey';
$post_data['scs_bucket'] = '云存储的bucket';
// logo
$post_data['logo_name'] = 'haha';
$post_data['logo_url'] = 'https://www.sinacloud.com/static/common/image/sinacloud_logo.png';
// 抽帧
$post_data['screenshot_enable'] = 1;
$post_data['screenshot_time'] = 1;
var_dump($post_data);

$ret = $i->post('/sve/_api/task/transcode_video', $post_data);
echo($ret);

返回的信息如下:

{
	"code": 0,
	"message": "success",
	"data": "43a932c6-84c8-46b8-9fac-2de359cabae0"
}

示例代码下载:点击下载

# PHP查询任务状态示例

<?php
require('gapi.php');
use sinacloud\sae\Gapi;
$i = new Gapi(SAE_ACCESSKEY, SAE_SECRETKEY);

$post_data = array();
$post_data['trace_id'] = '43a932c6-84c8-46b8-9fac-2de359cabae1';
var_dump($post_data);

$ret = $i->post('/sve/_api/result/query', $post_data);
echo($ret);

查询后输入信息如下:

{
	"code": 0,
	"message": "success",
	"data": {
		"task_info": {
			"priority": "1",
			"tag": "aa",
			"intro": "这是测试说明"
		},
		"media_info": {
			"status": "DONE",
			"message": "",
			"width": "848",
			"height": "478",
			"bitrate": "0",
			"fps": "23",
			"duration": "182234"
		},
		"sub_tasks_info": {
			"SD": {
				"video_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/sd\/output\/43a932c6-84c8-46b8-9fac-2de359cabae0.mp4",
				"cover_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/sd\/cover\/cover.jpg",
				"codec": "h264",
				"status": "DONE",
				"message": "",
				"definition": "SD"
			},
			"HD": {
				"video_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/output\/43a932c6-84c8-46b8-9fac-2de359cabae0.mp4",
				"cover_object": "\/43a932c6-84c8-46b8-9fac-2de359cabae0\/h264\/hd\/cover\/cover.jpg",
				"codec": "h264",
				"status": "DONE",
				"message": "",
				"definition": "HD"
			}
		}
	}
}

示例代码下载:点击下载