简介
本文档提供关于数据万象媒体处理任务的相关 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 。级别越大任务优先级越高,默认为0std::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 | 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 | Container | 否 | |
Snapshot | Request.Operation | Container | 否 | |
Transcode | Request.Operation | Container | 否 | |
Watermark | Request.Operation | Container Array | 否 | |
SmartCover | Request.Operation | Container | 否 | |
VideoMontage | Request.Operation | Container | 否 | |
VoiceSeparate | Request.Operation | Container | 否 | |
Segment | Request.Operation | Container | 否 | |
DigitalWatermark | Request.Operation | Container | 否 | |
ExtractDigitalWatermark | Request.Operation | Container | 否 | |
RemoveWatermark | Request.Operation | 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; // 新创建任务的 IDstd::string tag; // 新创建任务的 Tag:DocProcessstd::string state; // 任务的状态,为// Submitted、Running、Success、Failed、Pause、Cancel 其中一个std::string create_time; // 任务的创建时间std::string end_time; //std::string queue_id; // 任务所属的队列 IDstd::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;// 任务IDreq.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;// 任务IDreq.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;}