更新时间:2025-09-04 GMT+08:00

查询转码任务

功能介绍

查询转码任务状态。

调用方法

请参见如何调用API

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

主索引定制参数。

表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

输出最大码率

单位: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,编码快速档位

  • 2:VIDEO_PRESET_NORMAL,编码普通档位,不推荐使用2。

  • 3:VIDEO_PRESET_HIGHQUALITY,编码高质量档位

默认值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

选择的流名称

状态码:400

表21 响应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

查询转码任务失败。

错误码

请参见错误码