文档首页/媒体处理 MPC/API参考/媒资转码接口/查询转码任务 - ListTranscodingTask

更新时间：2026-01-06 GMT+08:00

查询转码任务 - ListTranscodingTask

功能介绍

查询转码任务状态。

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

如果使用角色与策略授权，具体权限要求请参见权限和授权项。
如果使用身份策略授权，需具备如下身份策略权限。
授权项
访问级别
资源类型（*为必须）
条件键
别名
依赖的授权项
mpc:transcodeTask:view
Read
-
-
-
-

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
mpc:transcodeTask:view	Read	-	-	-	-

URI

GET /v1/{project_id}/transcodings

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。获取方法请参考获取项目ID。

表2 Query参数
参数	是否必选	参数类型	描述
task_id	否	Array of longs	转码服务接受任务后产生的任务ID。一次最多10个
status	否	String	任务执行状态。取值如下： WAITING：等待启动 TRANSCODING：转码中 SUCCEEDED：转码成功 FAILED：转码失败 CANCELED：已删除 NEED_TO_BE_AUDIT：片源待审核
start_time	否	String	起始时间格式为yyyymmddhhmmss。必须是与时区无关的UTC时间，指定task_id时该参数无效
end_time	否	String	结束时间格式为yyyymmddhhmmss。必须是与时区无关的UTC时间，指定task_id时该参数无效
page	否	Integer	分页编号。查询指定“task_id”时，该参数无效。默认值：0。
size	否	Integer	每页记录数。查询指定“task_id”时，该参数无效。取值范围：[1,100]。默认值：10。

请求参数

表3 请求Header参数
参数	是否必选	参数类型	描述
x-language	否	String	客户端语言
X-Auth-Token	否	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
Authorization	否	String	使用AK/SK方式认证时必选，携带的鉴权信息。
X-Project_Id	否	String	使用AK/SK方式认证时必选，携带项目ID信息, 与路径参数中的项目ID相同。
X-Sdk-Date	否	String	使用AK/SK方式认证时必选，请求的发生时间。

响应参数

状态码：200

表4 响应Body参数
参数	参数类型	描述
task_array	Array of QueryTranscodingsTaskResponse objects	返回的任务组详情
is_truncated	Integer	查询结果是否被截取。 1：表示被截取，即还有结果未被返回，可以通过设置page和size参数继续查询。 0：表示未被截取，即所有结果已被返回。
total	Integer	查询结果的数量。

表5 QueryTranscodingsTaskResponse
参数	参数类型	描述
task_id	String	任务ID。
status	String	任务执行状态。取值如下： NO_TASK：没有任务 WAITING：等待启动 TRANSCODING：转码中 SUCCEEDED：转码成功 FAILED：转码失败 CANCELED：已删除 NEED_TO_BE_AUDIT：片源待审核
progress	Integer	任务执行进度百分比, 取值范围：[0, 100]。如果用户未申请加入白名单，默认返回“0”；如果用户已加入白名单，则返回有效值。如需加入白名单，请联系技术支持。
create_time	String	转码任务启动时间
end_time	String	转码任务结束时间
trans_template_id	Array of integers	转码任务对应的转码模板ID
input	ObsObjInfo object	转码任务对应的源文件信息，包括location、桶名、源文件。
output	ObsObjInfo object	转码任务的输出信息，包含location、桶名、路径。
output_file_name	Array of strings	转码生成的文件名，数组类型，可能包含多个，包含截图文件名。
user_data	String	用户自定义数据。
error_code	String	转码任务的返回码。
description	String	转码任务描述，当转码出现异常时，此字段为异常的原因。
tips	String	转码成功，但音频采样率过低时的提示。
transcode_detail	TranscodeDetail object	转码任务的额外信息。
thumbnail_output	ObsObjInfo object	截图的输出信息，包含location、桶名、路径。
thumbnail_outputname	String	截图压缩包名。
pic_info	Array of PicInfo objects	截图文件信息。
thumbnails_info	Array of ThumbnailsInfo objects	截图文件信息。
image_sprite_info	Array of ImageSpriteInfo objects	雪碧图信息，数组，最多支持20个成员。
av_parameters	Array of AvParameters objects	转码参数。若同时设置“trans_template_id”和此参数，则优先使用此参数进行转码。
additional_manifests	Array of AdditionalManifests objects	主索引定制参数。
metadata	Array of FileMetaData objects	输出文件的metadata信息

表6 TranscodeDetail
参数	参数类型	描述
multitask_info	Array of MultiTaskInfo objects	一进多出情况下部分转码失败的情况。
input_file	SourceInfo object	原始片源信息。
replace_sub_index	Array of strings	被替换的子索引文件

表7 MultiTaskInfo
参数	参数类型	描述
template_id	Integer	转码模板ID。
error	ErrorResponse object	错误信息
output_file	SourceInfo object	输出信息

表8 ErrorResponse
参数	参数类型	描述
error_code	String	错误码。
error_msg	String	错误描述。

表9 SourceInfo
参数	参数类型	描述
duration	Integer	片源时长。单位：秒
duration_ms	Long	片源时长。单位：毫秒
format	String	片源格式
size	Long	片源大小
manifest_name	String	独立mpd索引文件名
md5	String	视频的 md5 值。说明：仅转码和解析接口会返回当前字段，且默认不开放，需通过工单申请开通
video_info	VideoInfo object	视频信息
audio_info	Array of AudioInfo objects	音频信息

**表10** VideoInfo
参数	参数类型	描述
width	Integer	视频宽度
height	Integer	视频高度
bitrate	Integer	视频码率。单位: kbit/s 说明：视频解析接口2024年8月7日做了如下变更：变更前：视频解析任务，如果为同步解析，即sync参数配置为1时，解析响应VideoInfo中的参数bitrate单位实际为bit/s。变更后：视频解析任务同步解析响应VideoInfo中的参数bitrate单位变更为kbit/s。上述更新，可能会影响历史用户的转码业务判断，请关注并及时调整业务。
bitrate_bps	Long	视频码率。单位: bit/s
frame_rate	Integer	帧率。取值范围：0或[5,60]，0表示自适应。单位：帧每秒。说明：若设置的帧率不在取值范围内，则自动调整为0，若设置的帧率高于片源帧率，则自动调整为片源帧率。
codec	String	视频编码格式
duration	String	视频流时长，单位：秒说明：仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通
duration_ms	String	视频流时长，单位：毫秒说明：仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通
rotate	Float	视频拍摄时的选择角度，单位：度。说明：仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通

**表11** AudioInfo
参数	参数类型	描述
codec	String	音频编码格式
sample	Integer	音频采样率
channels	Integer	音频信道
bitrate	Integer	音频码率。单位: kbit/s
bitrate_bps	Long	音频码率。单位: bit/s
duration	String	音频流时长，单位：秒说明：仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通
duration_ms	String	音频流时长，单位：毫秒说明：仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通

**表12** ThumbnailsInfo
参数	参数类型	描述
pic_info	Array of PicInfo objects	截图文件信息。
output	ObsObjInfo object	输出文件信息
output_name	String	截图压缩包名。

**表13** PicInfo
参数	参数类型	描述
pic_name	String	截图文件名。

**表14** ImageSpriteInfo
参数	参数类型	描述
row_count	Integer	雪碧图中小图的行数。
column_count	Integer	雪碧图中小图的列数。
total_count	Integer	雪碧图中小图数量。
width	Integer	雪碧图小图宽度
height	Integer	雪碧图小图高度
output_image_name	Array of strings	每一张雪碧图大图的路径。
output_webvtt_name	String	雪碧图子图位置与时间关系的 WebVtt 文件路径。WebVtt 文件表明了各个雪碧图小图对应的时间点，以及在雪碧大图里的坐标位置，一般被播放器用于实现预览。
output	ObsObjInfo object	输出文件信息

**表15** AvParameters
参数	参数类型	描述
video	VideoParameters object	视频参数
audio	Audio object	音频参数
common	Common object	公共参数
output	ObsObjInfo object	输出路径，不填写时与外层转码输出在一起说明： hls多路输出时，每路输出路径不同时，index.m3u8将不可用，音视频分离不可用。
output_filename	String	输出文件名

**表16** VideoParameters
参数	参数类型	描述
output_policy	String	输出策略: 当视频参数中的“output_policy”为“discard”，且音频参数中的“output_policy”为“transcode”时，表示只输出音频。当视频参数中的“output_policy”为“transcode”，且音频参数中的“output_policy”为“discard”时，表示只输出视频。当视频参数中的“output_policy”为“copy”，表示直接拷贝原始的视频，不做编解码。当音频参数中的“output_policy”为“copy”，表示直接拷贝原始的音频，不做编解码。同时为“discard”不合法。同时为“transcode”时，表示输出音视频。取值如下： discard transcode copy
codec	Integer	视频编码格式。取值如下： 1：VIDEO_CODEC_H264 2：VIDEO_CODEC_H265
crf	Object	视频恒定码率控制因子。取值范围为[0, 51]
max_bitrate	Integer	输出最大码率取值范围：0或[40,800000]之间的整数。单位：kbit/s 带crf时使用，参考原片的平均码率进行设置（一般为1.5倍）
bitrate	Integer	输出平均码率。取值范围：0或[40,50000]之间的整数。单位：kbit/s 若设置为0，则输出平均码率为自适应值。
profile	Integer	编码档次取值如下： 1：VIDEO_PROFILE_H264_BASE 2：VIDEO_PROFILE_H264_MAIN 3：VIDEO_PROFILE_H264_HIGH 4：VIDEO_PROFILE_H265_MAIN
level	Integer	编码级别取值如下： 0：AUTO 1：VIDEO_LEVEL_1_0 2：VIDEO_LEVEL_1_1 3：VIDEO_LEVEL_1_2 4：VIDEO_LEVEL_1_3 5：VIDEO_LEVEL_2_0 6：VIDEO_LEVEL_2_1 7：VIDEO_LEVEL_2_2 8：VIDEO_LEVEL_3_0 9：VIDEO_LEVEL_3_1 10：VIDEO_LEVEL_3_2 11：VIDEO_LEVEL_4_0 12：VIDEO_LEVEL_4_1 13：VIDEO_LEVEL_4_2 14：VIDEO_LEVEL_5_0 15：VIDEO_LEVEL_5_1
preset	Integer	编码质量等级。取值如下： 1：VIDEO_PRESET_SPEED，编码快速档位 3：VIDEO_PRESET_HIGHQUALITY，编码高质量档位 4：VIDEO_PRESET_QUALITY，编码质量档位 5：VIDEO_PRESET_BALANCE，编码平衡档位默认值1。
max_iframes_interval	Integer	I帧最大间隔取值范围：[2，10]。默认值：5。单位：秒。
bframes_count	Integer	最大B帧间隔。取值范围： H264：[0，8]，默认值为4。 H265：[0，7]，默认值为7。单位：帧。
frame_rate	Integer	帧率。取值范围：0或[5,60]，0表示自适应。单位：帧每秒。说明：若设置的帧率不在取值范围内，则自动调整为0，若设置的帧率高于片源帧率，则自动调整为片源帧率。
width	Integer	视频宽度（单位：像素） H264：范围[32,4096]，必须为2的倍数 H265：范围[320,4096]，必须是2的倍数
height	Integer	视频高度（单位：像素） H264：范围[32,2880]，必须为2的倍数 H265：范围[240,2880] ，必须是2的倍数
black_cut	Integer	黑边剪裁类型 0：不开启黑边剪裁 1：开启黑边剪裁，低复杂度算法，针对长视频（>5分钟） 2：开启黑边剪裁，高复杂度算法，针对短视频（<=5分钟）
stream_name	String	流名称

**表17** Audio
参数	参数类型	描述
output_policy	String	输出策略: 当视频参数中的“output_policy”为“discard”，且音频参数中的“output_policy”为“transcode”时，表示只输出音频。当视频参数中的“output_policy”为“transcode”，且音频参数中的“output_policy”为“discard”时，表示只输出视频。当视频参数中的“output_policy”为“copy”，表示直接拷贝原始的视频，不做编解码。当音频参数中的“output_policy”为“copy”，表示直接拷贝原始的音频，不做编解码。同时为“discard”不合法。同时为“transcode”时，表示输出音视频。取值如下： discard transcode copy
codec	Integer	音频编码格式。取值如下： 1：AAC格式。 2：HEAAC1格式。 3：HEAAC2格式。 4：MP3格式。
sample_rate	Integer	音频采样率。取值如下： 1：AUDIO_SAMPLE_AUTO 2：AUDIO_SAMPLE_22050（22050Hz） 3：AUDIO_SAMPLE_32000（32000Hz） 4：AUDIO_SAMPLE_44100（44100Hz） 5：AUDIO_SAMPLE_48000（48000Hz） 6：AUDIO_SAMPLE_96000（96000Hz）说明：当编码格式为MP3时，音频采样率取值不为6
bitrate	Integer	音频码率。取值范围：0或[8,1000]。单位：kbit/s。
channels	Integer	声道数。取值如下： 1：AUDIO_CHANNELS_1，单声道 2：AUDIO_CHANNELS_2，双声道 6：AUDIO_CHANNELS_5_1，5.1声道当媒体的封装格式是音频格式（MP3）时，声道数不支持设为5.1声道。

**表18** Common
参数	参数类型	描述
PVC	Boolean	是否开启高清低码功能。取值如下： false：关闭。（当前默认关闭） true：开启。 (数字0表示关闭,其余正整数,负数都表示true)
hls_interval	Integer	HLS分片间隔，仅封装格式“pack_type”取值为1或3时，该参数生效。取值范围：[2，10]。单位：秒。
dash_interval	Integer	DASH间隔，仅封装格式“pack_type”取值为2或3时，该参数生效。取值范围：[2，10]。单位：秒。
pack_type	Integer	封装格式。取值如下： 1：HLS 2：DASH 3：HLS+DASH 4：MP4 5：MP3 6：ADTS 8: MOV 9：FLV 10：AVI 说明： pack_type设置为5和6时不能设置视频参数,设置为9时不支持多音频，设置为10时不支持H265编码。

**表19** ObsObjInfo
参数	参数类型	描述
bucket	String	OBS的bucket名称。
location	String	OBS桶所在的区域，且必须与使用的MPC区域保持一致。
object	String	OBS对象路径，遵守OSS Object定义。当用于指示input时，需要指定到具体对象。当用于指示output时，只需指定到转码结果期望存放的路径。在字幕场景下，字幕文件名称中禁止携带特殊符号，否则会导致转码任务失败，如：[ 正确示例: demo.srt 错误示例: [demo.srt
file_name	String	文件名，文件名长度不能超过180个字符。当指定了此参数时，输出的对象名为object/file_name。当不指定此参数时，输出的对象名为object/xxx，其中xxx由MPC指定。在作为输出文件名时：在转封装场景有效，需要指定输出文件名称在转码场景下，如果需要指定输出的文件名称，请使用output_filenames参数在解析场景有效，解析场景如果指定文件名，则将解析参数写入指定文件名，通过查询接口响应json数据获取文件元数据信息在截图场景无效在转动图场景无效输出文件为HLS格式时，文件名称不能命名为index，示例：index.m3u8，否则会导致播放失败。

**表20** AdditionalManifests
参数	参数类型	描述
manifest_name_modifier	String	定制的索引后缀名
selected_outputs	Array of strings	选择的流名称

**表21** FileMetaData
参数	参数类型	描述
name	String	metadata名称
value	String	metadata值

状态码：400

**表22** 响应Body参数
参数	参数类型	描述
error_code	String	错误码。
error_msg	String	错误描述。

请求示例

GET https://{endpoint}/v1/{project_id}/transcodings?task_id=22123973

响应示例

状态码：200

查询转码任务成功。

{
  "is_truncated" : 0,
  "total" : 1,
  "task_array" : [ {
    "task_id" : 22123973,
    "status" : "SUCCEEDED",
    "create_time" : 20200310031605,
    "end_time" : 20200310031623,
    "trans_template_id" : [ 4 ],
    "input" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-input.mp4"
    },
    "output" : {
      "bucket" : "example-bucket",
      "location" : "region01",
      "object" : "example-output.mp4"
    },
    "output_file_name" : [ "example_480X270.m3u8" ],
    "transcode_detail" : {
      "multitask_info" : [ {
        "template_id" : 4,
        "output_file" : {
          "duration" : 59,
          "duration_ms" : 0,
          "format" : "HLS",
          "size" : 2180,
          "video_info" : {
            "width" : 480,
            "height" : 270,
            "bitrate" : 231,
            "bitrate_bps" : 0,
            "frame_rate" : 25000,
            "codec" : "H264"
          },
          "audio_info" : [ {
            "codec" : "HEAAC",
            "sample" : 44100,
            "channels" : 2,
            "bitrate" : 64,
            "bitrate_bps" : 0
          } ]
        }
      } ],
      "input_file" : {
        "duration" : 59,
        "duration_ms" : 0,
        "format" : "MOV",
        "size" : 2494653,
        "video_info" : {
          "width" : 480,
          "height" : 270,
          "bitrate" : 199,
          "bitrate_bps" : 0,
          "frame_rate" : 25000,
          "codec" : "HEVC"
        },
        "audio_info" : [ {
          "codec" : "AAC",
          "sample" : 48000,
          "channels" : 2,
          "bitrate" : 128,
          "bitrate_bps" : 0
        } ]
      }
    }
  } ]
}

状态码：400

查询转码任务失败。

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter"
}

状态码

状态码	描述
200	查询转码任务成功。
400	查询转码任务失败。

错误码

请参见错误码。

父主题：媒资转码接口

上一篇：取消转码任务 - DeleteTranscodingTask

下一篇：删除转码任务记录 - DeleteTranscodingTaskByConsole

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

云宝助手提问云社区提问