有奖:语音产品征文挑战赛火热进行中> HOT

简介

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

基本操作

创建任务

功能说明

创建一个媒体处理任务,

方法原型

CosResult CosAPI::CreateDataProcessJobs(const CreateDataProcessJobsReq& req,
CreateDataProcessJobsResp* resp);

参数说明

参数名称
描述
类型
是否必选
req
创建任务操作的请求
CreateDataProcessJobsReq
resp
创建任务操作的响应
CreateDataProcessJobsResp
CreateDataProcessJobsReq 包含如下方法:
void setOperation(JobsOptions operation);
JobsOptions 中结构如下:
struct JobsOptions {
std::string tag; // 任务类型,文件解压缩的任务类型为 FileUncompress ,必传
Input input; // 输入文件参数,任务类型为文件解压缩时必传
JobsOperation operation; // 任务参数,必传
std::string queue_type; // 队列类型,非必传,当 tag 为 Transcode 时,传入 SpeedTranscoding 表示为开启倍速转码
std::string callback_format; // 任务回调格式,JSON 或 XML,默认 XML,优先级高于队列的回调格式,非必传
std::string callback_type; // 任务回调类型,Url 或 TDMQ,默认 Url,优先级高于队列的回调类型,非必传
std::string callback; // 任务回调的地址,优先级高于队列的回调地址,非必传
CallBackkMqConfig callback_mq_config; // 任务回TDMQ配置,非必传
};

struct JobsOperation {
Output output; // 输出配置,非必选
int job_level; // 任务优先级,非必选,级别限制:0 、1 、2 。级别越大任务优先级越高,默认为0
std::string user_data; // 用户透传信息,非必选
std::string template_id; // 模版ID,非必选
std::string template_name; // 模版名称,非必选
Snapshot snapshot; // 截图参数,非必选,Tag 为 Snapshot 时生效
Transcode transcode; // 转码参数,非必选,Tag 为 Transcode 时生效
std::vector<Watermark> watermarks; // 水印参数,非必选,Tag 为 Transocde、Watermark 时生效
std::vector<std::string> watermark_template_id; // 水印模版ID,非必选,Tag 为 Transocde、Watermark 时生效
RemoveWatermark remove_watermark; // 去除水印参数,非必选,Tag 为 Transcode 时生效
Subtitles subtitles; // 字幕参数,非必选,Tag 为 Transcode 时生效,
DigitalWatermark digital_watermark; // 数字水印参数,非必选,Tag 为 Transocde、DigitalWatermark 时生效
ExtractDigitalWatermark extract_digital_watermark;// 提取数字水印参数,非必选,Tag 为 ExtractDigitalWatermark 时生效
MediaResult media_result; // 输出文件基本信息,响应字段,非请求参数
MediaInfo media_info; // 输出文件媒体信息,响应字段,非请求参数
Animation animation; // 动图参数,非必选,Tag 为 Animation 时生效
SmartCover smart_cover; // 智能封面参数,非必选,Tag 为 SmartCover 时生效
Concat concat; // 拼接参数,非必选,Tag 为 Concat 时生效
VideoMontage video_montage; // 精彩锦集参数,非必选,Tag 为 VideoMontage 时生效
VoiceSeparate voice_separate; // 人声分离参数,非必选,Tag 为 VoiceSeparate 时生效
Segment segment; // 转封装参数,非必选,Tag 为 Segment 时生效
};

struct Output {
std::string region; // 存储桶的地域,必选
std::string bucket; // 存储结果的存储桶,必选
std::string object; // 输出文件路径,当 Tag 不为 VoiceSeparate 、 Snapshot 时必选
std::string sprite_object; //雪碧图输出,非必选,当 Tag 为 Snapshot 时生效
std::string au_object; // 人声结果文件,非必选,当 Tag 为 VoiceSeparate 时生效
std::string bass_object; // Bass声结果文件,非必选,当 tag 为 VoiceSeparate 时生效
std::string drum_object; // 鼓声结果文件,非必选,当 tag 为 VoiceSeparate 时生效
};

JobsOptions 中字段具体介绍如下:
节点名称(关键字)
父节点
描述
类型
必选
Tag
Request
创建任务的 Tag:
1. Animation 动图任务
2. Snapshot 截图任务
3. Transcode 转码任务
4. SmartCover 智能封面任务
5. Segment 转封装任务
6. VoiceSeparate 人声分离
7. DigitalWatermark 添加数字水印任务
8. ExtractDigitalWatermark 提取数字水印任务
9. VideoMontage 精彩锦集任务
10. Concat 音视频拼接任务
11. Watermark 明水印任务
String
Input
Request
待操作的媒体信息
Container
Operation
Request
操作规则
Container
CallBack
Request
任务回调地址,优先级高于队列的回调地址。设置为 no 时,表示队列的回调地址不产生回调
String
QueueType
Request
任务所在的队列类型,限制为 SpeedTranscoding, 表示为开启倍速转码
String
CallBackFormat
Request
任务回调格式,JSON 或 XML,默认 XML,优先级高于队列的回调格式
String
CallBackType
Request
任务回调类型,Url 或 TDMQ,默认 Url,优先级高于队列的回调类型
String
CallBackMqConfig
Request
任务回调TDMQ配置,当 CallBackType 为 TDMQ 时必填。详情见 CallBackMqConfig
Container
Container 类型 Input 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Object
Request.Input
文件路径
String
Container 类型 Operation 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
TemplateId
Request.Operation
指定的模板 ID,模版ID参数优先级高于对应任务的参数
String
WatermarkTemplateId
Request.Operation
水印模板 ID,可以传多个水印模板 ID ,最多传3个
String Array
Animation
Request.Operation
指定该任务的参数,同创建动图模板 CreateMediaTemplate 接口中的 Request.Animation
Container
Snapshot
Request.Operation
指定该任务的参数,同创建截图模板 CreateMediaTemplate 接口中的 Request.Snapshot
Container
Transcode
Request.Operation
指定该任务的参数,同创建转码模板 CreateMediaTemplate 接口中的 Request.Transcode
Container
Watermark
Request.Operation
指定该任务的参数,同创建水印模板 CreateMediaTemplate 接口中的 Request.Watermark,最多传3个
Container Array
SmartCover
Request.Operation
指定该任务的参数,同创建智能封面模板 CreateMediaTemplate 接口中的Request.SmartCover
Container
VideoMontage
Request.Operation
指定该任务的参数,同创建精彩集锦模板 CreateMediaTemplate 接口中的Request.VideoMontage
Container
VoiceSeparate
Request.Operation
指定该任务的参数,同创建人身分离模板 CreateMediaTemplate 接口中的Request.VoiceSeparate
Container
Segment
Request.Operation
指定该任务的参数,同创建转封装任务 CreateMediaJob 接口中的Request.Operation.Segment
Container
DigitalWatermark
Request.Operation
指定该任务的参数,同创建数字水印任务 CreateMediaJob 接口中的Request.Operation.DigitalWatermark
Container
ExtractDigitalWatermark
Request.Operation
指定该任务的参数,同创建提取数字水印任务 CreateMediaJob 接口中的Request.Operation.ExtractDigitalWatermark
Container
RemoveWatermark
Request.Operation
指定该任务的参数,同创建音视频转码任务 CreateMediaJob 接口中的Request.Operation.RemoveWatermark
Container
Output
Request.Operation
结果输出地址
Container
Container 类型 Output 的具体数据描述如下:
节点名称(关键字)
父节点
描述
类型
必选
Region
Request.Operation.Output
存储桶的地域
String
Bucket
Request.Operation.Output
存储结果的存储桶
String
Object
Request.Operation.Output
结果文件的名字
String
SpriteObject
Request.Operation.Output
雪碧图的名字。当有多个输出文件时必须包含 ${number} 通配符。仅支持 jpg 格式,当任务类型为 SnapShot 时生效
String
AuObject
Request.Operation.Output
背景音结果文件的名字,当任务类型为 VoiceSeparate 时生效
String
BassObject
Request.Operation.Output
贝斯声音轨结果文件的名字,当任务类型为 VoiceSeparate 时生效
String
DrumObject
Request.Operation.Output
鼓声音轨结果文件的名字,当任务类型为 VoiceSeparate 时生效
String
CreateDataProcessJobsResp 包含如下方法:
JobsDetails GetJobsDetail() const
JobsDetail结构体如下:
struct JobsDetails {
std::string code; // 错误码,只有 State 为 Failed 时有意义
std::string message; // 错误描述,只有 State 为 Failed 时有意义
std::string job_id; // 新创建任务的 ID
std::string tag; // 新创建任务的 Tag:DocProcess
std::string state; // 任务的状态,为
// Submitted、Running、Success、Failed、Pause、Cancel 其中一个
std::string create_time; // 任务的创建时间
std::string end_time; //
std::string queue_id; // 任务所属的队列 ID
std::string queue_type; // 队列类型
Input input; // 该任务的输入文件路径
JobsOperation operation; // 任务operation,同 CreateDataProcessJobsReq 中的 JobsOperation
};

返回结果说明

成功:API 返回 CosResult 结构,获取对应 Response 结构中的数据。
失败:API 返回 CosResult 结构,失败可以通过 CosResult 获取详细信息。详情请参见 异常处理

请求示例

以提交转码任务为例子
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "test-xxx";
CreateDataProcessJobsReq req(bucket_name);
CreateDataProcessJobsResp resp;

JobsOptions opt;
opt.input.bucket = bucket_name;
opt.input.region = "ap-chongqing";
opt.input.object = "test.mp4";
opt.tag = "Transcode";
// 使用转码模版ID提交任务
// opt.operation.template_id = "t1460606b9752148c4ab182f55163ba7cd";

// 使用转码参数提交任务
opt.operation.transcode.container.format = "mp4";
opt.operation.transcode.video.codec = "H.264";
opt.operation.transcode.video.profile = "high";
opt.operation.transcode.video.bit_rate = "1000";
opt.operation.transcode.video.width = "1280";
opt.operation.transcode.video.fps = "30";
opt.operation.transcode.video.preset = "medium";
opt.operation.transcode.audio.codec = "aac";
opt.operation.transcode.audio.sample_format = "fltp";
opt.operation.transcode.audio.bit_rate = "128";
opt.operation.transcode.audio.channels = "4";
opt.operation.transcode.trans_config.adj_dar_method = "scale";
opt.operation.transcode.trans_config.is_check_audio_bit_rate = "false";
opt.operation.transcode.trans_config.reso_adj_method = "1";
opt.operation.transcode.time_interval.start = "0";
opt.operation.transcode.time_interval.duration = "10";

// 混音参数
AudioMix audio_mix_1 = AudioMix();
audio_mix_1.audio_source = "https://test-xxx.cos.ap-chongqing.myqcloud.com/mix1.mp3";
audio_mix_1.mix_mode = "Once";
audio_mix_1.replace = "true";
audio_mix_1.effect_config.enable_start_fade_in = "true";
audio_mix_1.effect_config.start_fade_in_time = "3";
audio_mix_1.effect_config.enable_end_fade_out = "false";
audio_mix_1.effect_config.end_fade_out_time = "0";
audio_mix_1.effect_config.enable_bgm_fade = "true";
audio_mix_1.effect_config.bgm_fade_time = "1.7";
opt.operation.transcode.audio_mix_array.push_back(audio_mix_1);

AudioMix audio_mix_2 = AudioMix();
audio_mix_2.audio_source = "https://test-xxx.cos.ap-chongqing.myqcloud.com/mix2.mp3";
audio_mix_2.mix_mode = "Once";
audio_mix_2.replace = "true";
audio_mix_2.effect_config.enable_start_fade_in = "true";
audio_mix_2.effect_config.start_fade_in_time = "3";
audio_mix_2.effect_config.enable_end_fade_out = "false";
audio_mix_2.effect_config.end_fade_out_time = "0";
audio_mix_2.effect_config.enable_bgm_fade = "true";
audio_mix_2.effect_config.bgm_fade_time = "1.7";
opt.operation.transcode.audio_mix_array.push_back(audio_mix_2);

// 去除水印参数
opt.operation.remove_watermark.dx = "150";
opt.operation.remove_watermark.dy = "150";
opt.operation.remove_watermark.width = "75";
opt.operation.remove_watermark.height = "75";

// 数字水印参数
opt.operation.digital_watermark.type = "Text";
opt.operation.digital_watermark.message = "12345";
opt.operation.digital_watermark.version = "V1";
opt.operation.digital_watermark.ignore_error = "false";

// 水印参数
// 使用水印模版ID
// opt.operation.watermark_template_id.push_back("t1318c5f428d474afba1797f84091cbe22");
// opt.operation.watermark_template_id.push_back("t1318c5f428d474afba1797f84091cbe23");
// opt.operation.watermark_template_id.push_back("t1318c5f428d474afba1797f84091cbe24");
// 使用水印参数
Watermark watermark_1 = Watermark();
watermark_1.type = "Text";
watermark_1.loc_mode = "Absolute";
watermark_1.dx = "128";
watermark_1.dy = "128";
watermark_1.pos = "TopRight";
watermark_1.start_time = "0";
watermark_1.end_time = "100.5";
watermark_1.text.text = "水印内容";
watermark_1.text.font_size = "30";
watermark_1.text.font_color = "0xRRGGBB";
watermark_1.text.transparency = "30";
opt.operation.watermarks.push_back(watermark_1);

Watermark watermark_2 = Watermark();
watermark_2.type = "Image";
watermark_2.loc_mode = "Absolute";
watermark_2.dx = "128";
watermark_2.dy = "128";
watermark_2.pos = "TopRight";
watermark_2.start_time = "0";
watermark_2.end_time = "100.5";
watermark_2.image.url = "http://test-1234567890.ci.ap-chongqing.myqcloud.com/shuiyin_2.png";
watermark_2.image.mode = "Proportion";
watermark_2.image.width = "10";
watermark_2.image.height = "10";
watermark_2.image.transparency = "30";
opt.operation.watermarks.push_back(watermark_2);

opt.operation.output.bucket = bucket_name;
opt.operation.output.region = "ap-chongqing";
opt.operation.output.object = "output/test.mp4";
req.setOperation(opt);

CosResult result = cos.CreateDataProcessJobs(req, &resp);
if (result.IsSucc()) {
std::cout << "CreateDataProcessJobs Succ." << std::endl;
} else {
std::cout << "CreateDataProcessJobs Fail, ErrorMsg: "
<< result.GetErrorMsg() << std::endl;
}

查询任务

功能说明

根据任务 id 查询任务详情。

方法原型

CosResult CosAPI::DescribeDataProcessJob(const DescribeDataProcessJobReq& req,
DescribeDataProcessJobResp* resp);

参数说明

参数名称
描述
类型
是否必选
req
查询异步任务操作的请求
DescribeDataProcessJobReq
resp
查询异步任务操作的响应
DescribeDataProcessJobResp
req包含如下方法:
void SetJobId(const std::string& job_id); // 查询的任务ID,必传
resp包含如下方法:
JobsDetails GetJobsDetail() const
JobsDetails 结构体同提交任务中的 JobsDetails 结构。

返回结果说明

成功:API 返回 CosResult 结构,获取对应 Response 结构中的数据。
失败:API 返回 CosResult 结构,失败可以通过 CosResult 获取详细信息。详情请参见 异常处理

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

DescribeDataProcessJobReq req(bucket_name);
DescribeDataProcessJobResp resp;

// 任务ID
req.SetJobId("XXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

CosResult result = cos.DescribeDataProcessJob(req, &resp);
if (result.IsSucc()) {
// 调用成功,调用 resp 的成员函数获取返回内容
} else {
// 调用失败,调用 result 的成员函数获取错误信息
}

取消任务

功能说明

取消一个未在处理中的任务。

方法原型

CosResult CosAPI::CancelDataProcessJob(const CancelDataProcessJobReq& req,
CancelDataProcessJobResp* resp);

参数说明

参数说明

参数名称
描述
类型
是否必选
req
查询异步任务操作的请求
DescribeDataProcessJobReq
resp
查询异步任务操作的响应
DescribeDataProcessJobResp
req包含如下方法:
void SetJobId(const std::string& job_id); // 查询的任务ID,必传

返回结果说明

成功:API 返回 CosResult 结构,获取对应 Response 结构中的数据。
失败:API 返回 CosResult 结构,失败可以通过 CosResult 获取详细信息。详情请参见 异常处理

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
CancelDataProcessJobReq req(bucket_name);
CancelDataProcessJobResp resp;

// 任务ID
req.SetJobId("XXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

CosResult result = cos.CancelDataProcessJob(req, &resp);
if (result.IsSucc()) {
std::cout << "CancelDataProcessJob Succ." << std::endl;
} else {
std::cout << "CancelDataProcessJob Fail, ErrorMsg: "
<< result.GetErrorMsg() << std::endl;
}