# 查询转码任务 - ListTranscodingTask #### 功能介绍 查询转码任务状态。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-mpc/mpc_04_0047.html)。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-mpc/mpc_04_0002.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | mpc:transcodeTask:view | Read | - | - | - | - | #### URI GET /v1/{project_id}/transcodings 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | 项目ID。获取方法请参考[获取项目ID](https://support.huaweicloud.com/api-mpc/mpc_04_0064.html)。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | task_id | 否 | Array of longs | 转码服务接受任务后产生的任务ID。一次最多10个 | | status | 否 | String | 任务执行状态。查询指定"task_id"时，该参数无效。 取值如下： - 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 | 查询结果的数量。 | 表5QueryTranscodingsTaskResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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信息 | 表6TranscodeDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | multitask_info | Array of [MultiTaskInfo] objects | 一进多出情况下部分转码失败的情况。 | | input_file | [SourceInfo] object | 原始片源信息。 | | replace_sub_index | Array of strings | 被替换的子索引文件 | 表7MultiTaskInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | template_id | Integer | 转码模板ID。 | | error | [ErrorResponse] object | 错误信息 | | output_file | [SourceInfo] object | 输出信息 | 表8ErrorResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | 错误码。 | | error_msg | String | 错误描述。 | 表9SourceInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 音频信息 | 表10VideoInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 视频拍摄时的选择角度，单位：度。 说明： 仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通 | 表11AudioInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | codec | String | 音频编码格式 | | sample | Integer | 音频采样率 | | channels | Integer | 音频信道 | | bitrate | Integer | 音频码率。 单位: kbit/s | | bitrate_bps | Long | 音频码率。 单位: bit/s | | duration | String | 音频流时长，单位：秒 说明： 仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通 | | duration_ms | String | 音频流时长，单位：毫秒 说明： 仅转码和解析接口会返回当前字段，且解析接口默认不开放，需通过工单申请开通 | 表12ThumbnailsInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | pic_info | Array of [PicInfo] objects | 截图文件信息。 | | output | [ObsObjInfo] object | 输出文件信息 | | output_name | String | 截图压缩包名。 | 表13PicInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | pic_name | String | 截图文件名。 | 表14ImageSpriteInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 输出文件信息 | 表15AvParameters | 参数 | 参数类型 | 描述 | |:---|:---|:---| | video | [VideoParameters] object | 视频参数 | | audio | [Audio] object | 音频参数 | | common | [Common] object | 公共参数 | | output | [ObsObjInfo] object | 输出路径，不填写时与外层转码输出在一起 说明： hls多路输出时，每路输出路径不同时，index.m3u8将不可用，音视频分离不可用。 | | output_filename | String | 输出文件名 | 表16VideoParameters | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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的倍数 说明：如果视频的宽和高仅有一个设置为0，默认非0值作为视频的短边，按照原始视频的宽高比进行等比缩放。 | | height | Integer | 视频高度（单位：像素） - H264：范围\[32,2880\]，必须为2的倍数 - H265：范围\[240,2880\] ，必须是2的倍数 说明：如果视频的宽和高仅有一个设置为0，默认非0值作为视频的短边，按照原始视频的宽高比进行等比缩放。 | | stream_name | String | 流名称 | 表17Audio | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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声道。 | 表18Common | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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编码。 | 表19ObsObjInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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，否则会导致播放失败。 | 表20AdditionalManifests | 参数 | 参数类型 | 描述 | |:---|:---|:---| | manifest_name_modifier | String | 定制的索引后缀名 | | selected_outputs | Array of strings | 选择的流名称 | 表21FileMetaData | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 查询转码任务失败。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-mpc/ErrorCode.html)。