视频转码服务

服务说明

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

开启服务

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

服务价格

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

服务接口

添加视频转码任务

接口地址

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

接口请求方式

POST

接口验证

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

接口参数

参数	是否必填	说明
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"
			}
		}
	}
}

示例代码下载：点击下载