字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
page_size	int	是	每一页的条数（最多 20 条/页）
page_number	int	是	当前的页码（从 0 开始）
business_status	int	否	审核状态（98 审核中，99 未审核，，传为审核和未审核均查询）
video_name	string	否	短剧的名称	cat.mp4

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/get_video_list' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxxxxx' \
--data '{
    "page_size":10,
    "page_number":0,
    "env_id":"1",
    "business_status" : "99",
    "video_name" : ""
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	否	日志 id,用户 oncall 排查问题
total_num	string	是	查询的总数
data	list<OpenVideoModel>	否	具体的每一页的数据

名称	类型	是否必填	描述	示例值
video_name	string	是	视频的名称
vid	string	是	视频的唯一 id
size	int	是	视频大小单位为 b
upload_time	int	是	上传的时间
business_status	int	是	审核状态
trans_code_status	int	否	转码的状态	1：未转码 2：转码中 3：转码失败 4：转码成功
source_type	int	否	视频的来源	1：控制台上传 2：抖音云 openApi 上传 3：行业侧同步
video_open_id	string	否	行业侧视频 id

响应示例

正常示例

{
    "data": [
        {
            "video_name": "xxxxx",
            "business_status": 99,
            "size": 16186186,
            "upload_time": 1700299345,
            "vid": "v02ecxxxxxxxx"
        }
    ],
    "err_msg": "success",
    "err_no": 0,
    "log_id": "xxxxxxxx",
    "total_num": 60
}

异常示例

{
    "err_msg": "video not exist",
    "err_no": 401003,
    "log_id": "20230822193748224DE2120360F701CA0A",
    "total_num": 0,
    "data": null
}

错误码

HTTP 状态码	错误码	描述	排查建议
400	41050	no user authority error	操作的用户需在通讯录权限范围中。
400	40001	param error	参数错误。

删除媒资列表

API 说明

小程序开通抖音云，且开通短剧解决方案，可通过该 openApi 分页删除上传过的媒资信息。

使用限制

•

只有开通抖音云的短剧方案的小程序才能使用该接口。

接口说明

注意需要评估删除链接的影响。

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/delete_video
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/delete_video
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
vid	string	是	媒资的 id
env_id	string	是	抖音云 prod 环境的 id，需要登录抖音云控制台，查看

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/delete_video' \
--header 'Content-Type: application/json' \
--header 'access-token: cltxxxx' \
--data '{
     "env_id":"env-xxxx",
    "vid":"v0dxxxx"
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题

响应示例

正常示例

{
    "err_msg": "success",
    "err_no": 0,
    "log_id": "202308221926108152CB83794BE101C43B"
}

异常示例

{
    "err_msg": "space not exist",
    "err_no": 401002,
    "log_id": "202308221926108152CB83794BE101C43B"
}

根据 Vid 获取可播放链接

API 说明

小程序开通抖音云，且开通短剧解决方案，可通过该 openApi 分页获取 video 的播放链接。

视频转码之后。

使用限制

•

只有开通抖音云的短剧方案的小程序才能使用该接口。

•

需要完成短剧域名绑定的小程序才能使用该接口。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/get_video_by_vid
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例： clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
vid	string	是	视频资源的唯一 id
domain	string	否	可以指定媒资管理已有域名，生成播放链接，未指定如设置默认域名，则按指定域名生成未设置默认域名，则随机选择域名生成。
expire_time	int	否	可以指定播放链接的过期时间（秒），取值范围[3600- 14243600] 。默认是 3600

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/get_video_by_vid' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxxx' \
--data '{
     "vid":"v0dbxxxxxxx"
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	否	日志 id,用户 oncall 排查问题
data	list<OpenVideoModel>	否	具体的每一页的数据

名称	类型	是否必填	描述	示例值
format	string	是	视频格式
main_play_url	string	是	主播放地址
back_up_play_url	string	是	备用播放地址
main_url_expire	string	是	主播放地址过期时间
back_url_expire	string	是	备用播放地址过期时间
definition	string	是	视频分辨率
bitrate	int	是	码率
codec	string	是	编码类型
size	double	是	文件大小
is_demote	boolean	否	是否降级返回当该字段为 true 则只有 main_play_url 和 main_url_expire 字段可置信
is_original	boolean	否	是否上传的原片

响应示例

正常示例

{
    "log_id": "20230822202428CF29B88B2521D206CB62",
    "data": [
        {
            "format": "mp4",
            "main_play_url": "http://ttbf51c9ec2037ea53xxxxx",
            "size": 940666,
            "back_up_play_url": "http://ttbfxxxxxxx",
            "bitrate": 336462,
            "codec": "h264",
            "definition": "360p",
            "back_url_expire": "1692710700",
            "main_url_expire": "1692710700",
            "is_demote":false
        }
    ],
    "err_msg": "success",
    "err_no": 0
}

异常示例

{
    "err_msg": "video not exist",
    "err_no": 401003,
    "log_id": "20231118173045BB550CD590C4897C20D2",
    "data": null
}

通过 Url 批量上传视频

API 说明

此接口用于通过源文件 URL，拉取媒体文件并上传到抖音云媒资管理，支持批量操作。

提交成功后，将会生成异步执行的任务，进行排队执行。您可以通过查询上传任务状态接口查询上传状态。

使用限制

一次最多上传 20 个视频链接的 Url。

URL 必须是源文件 URL，不是包含视频文件的页面 URL 等；支持 HTTP/HTTPS。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/upload_video_by_urls
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
url_sets	list<UrlSet>	是	源视频的 urlSet 列表，一次最多传入 20 条

UrlSet。

名称	类型	是否必填	描述	示例值
source_url	string	是	原视频的 url 链接
file_name	string	是	视频名称（不包含扩展名）

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/upload_video_by_urls' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.7a440b1712f8276371c49578c9f48aab0ZXW09TMOr2NhkGBj1ydkmJeT1b0' \
--data '{
    "url_sets":[
        {
            "source_url":"https://xxxxxxxx.mp4",
            "file_name":"剧集名称"
        }
    ]
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	bool	否	日志 id
data	UploadVideoByUrlsData	否	每个视频 url 的任务列表

UploadVideoByUrlsData。

{
    "log_id": "2023082220011391316DF97979F404F7FB",
    "data": {
        "url_jobs": [
            {
                "job_id": "eeb5739b8876468e8156c0726d6bacd5",
                "source_url": "https://xxxxxxxx.com/test/xxxxxxx.mp4"
            }
        ]
    },
    "err_msg": "",
    "err_no": 0
}

名称	类型	是否必填	描述	示例值
url_jobs	list<UrlJob>	否	每个视频 url 的任务列表

UrlJob

名称	类型	是否必填	描述	示例值
source_url	string	是	源视频 url
job_id	string	是	源视频上传的任务 id

响应示例

正常示例

{
    "log_id": "2023082220011391316DF97979F404F7FB",
    "data": {
        "url_jobs": [
            {
                "job_id": "eeb5739b8876468e8156c0726d6bacd5",
                "source_url": "https://xxxxxxxx.com/test/xxxxxxx.mp4"
            }
        ]
    },
    "err_msg": "",
    "err_no": 0
}

异常示例

{
    "err_msg": "input params is invalid",
    "err_no": 401001,
    "log_id": "2023082220015780B7FC82554E6E055343"
}

查询 URL 批量上传任务状态

API 说明

此接口用于查询 URL 批量上传任务状态。您可以通过 URL 批量拉取上传接口返回的 JobId 查询对应 URL 上传状态，上传成功将返回 Vid，以及媒资基础信息。

使用限制

一次最多查询20 个任务的任务状态。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/get_upload_job_info
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
job_ids	list<string>	是	上传任务的 jobid 列表，一次最多传入 20 条

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/get_upload_job_info' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxxx' \
--data '{
   "job_ids":["xxxxxxxxxx"]
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	bool	否	日志 id
data	GetUploadJobInfoData	否	上传任务详情

GetUploadJobInfoData。

名称	类型	是否必填	描述	示例值
md5	string	否	文件的 md5 值
file_type	list<string>	否	文件类型。取值如下： •video：音频 •audio：视频
height	int32	否	视频高度，单位为 px
width	int32	否	视频宽度，单位为 px
format	string	否	文件格式
duration	double	否	视频时长，单位为 s
size	int64	否	文件大小，单位为字节
bitrate	int32	否	码率，单位为 Kbps

名称	类型	是否必填	描述	示例值
md5	string	否	文件的 md5 值
file_type	list<string>	否	文件类型。取值如下： •video：音频 •audio：视频
height	int32	否	视频高度，单位为 px
width	int32	否	视频宽度，单位为 px
format	string	否	文件格式
duration	double	否	视频时长，单位为 s
size	int64	否	文件大小，单位为字节
bitrate	int32	否	码率，单位为 Kbps

名称	类型	是否必填	描述	示例值
video_infos	list<VideoUrlSet>	否	存在的任务 ID 对应的视频详情
not_exist_job_ids	list<string>	否	不存在的任务 ID 列表

VideoUrlSet。

名称	类型	是否必填	描述	示例值
request_id	string	是	请求 id
job_id	string	是	任务 id
source_url	string	是	源视频 url
state	string	是	上传任务状态	init，process，success，fail
vid	string	否	视频上传成功后返回 vid
source_info	SourceInfo	否	视频上传成功后视频详情

SourceInfo。

名称	类型	是否必填	描述	示例值
md5	string	否	文件的 md5 值
file_type	list<string>	否	文件类型。取值如下： •video：音频 •audio：视频
height	int32	否	视频高度，单位为 px
width	int32	否	视频宽度，单位为 px
format	string	否	文件格式
duration	double	否	视频时长，单位为 s
size	int64	否	文件大小，单位为字节
bitrate	int32	否	码率，单位为 Kbps

响应示例

正常示例

{
    "data": {
        "not_exist_job_ids": [
            "123123123"
        ],
        "video_infos": [
            {
                "state": "success",
                "vid": "v03b1eg10003cji7g39s1v0qxxxxxxxx",
                "job_id": "eeb5739b8876468e8156c0726d6bacd5",
                "request_id": "20230822165537DF4EC0FEAD1E0A76268B",
                "source_info": {
                    "file_type": "video",
                    "format": "MP4",
                    "size": 16186186,
                    "store_uri": "tos-vod-cn-v-5d5f45656175f86d/xxxxxxxxxx/7im8/test.mp4",
                    "width": 1080,
                    "bitrate": 1316083,
                    "duration": 98.39,
                    "file_path": "xxxxxxxxxx/7im8/test.mp4",
                    "height": 1920,
                    "md5": "ac773c40adcd591f84a313d8fa7cef83"
                },
                "source_url": "https://xxxxxxxx.com/test/xxxxxxx.mp4"
            }
        ]
    },
    "err_msg": "",
    "err_no": 0,
    "log_id": "202308221656372DAD6B0943B91E9EB2A0"
}

异常示例

{
    "err_msg": "input params is invalid",
    "err_no": 401001,
    "log_id": "2023082220015780B7FC82554E6E055343"
}

媒资转码

API 说明

在抖音云-媒资管理下的视频，可通过该 openApi进行视频的转码，抖音云官方推出适合短剧的转码模板。

使用限制

•

只有开通抖音云的短剧方案的小程序才能使用该接口。

•

进行转码的视频需要和开通媒资管理的小程序是匹配的。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/start_work_flow
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

限流情况

单小程序。

。

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
run_id	string	string	转码任务的 id，可用于查询转码的状态

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
run_id	string	string	转码任务的 id，可用于查询转码的状态

20 次/s。

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
vid	string	是	媒资的 id
trans_code_type	string	否	3：MP4720PH264 4：MP4720PH265 5：HLS720PH264

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/start_work_flow' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxxxx' \
--data '{
     "vid":"v0db1eg10003cji9s0hs1v0ndbhjbn90"
     "trans_code_type":"3"
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
run_id	string	string	转码任务的 id，可用于查询转码的状态

响应示例

正常示例

{
    "err_msg": "success",
    "err_no": 0,
    "log_id": "202308221926108152CB83794BE101C43B",
    "run_id": "dyc_text"
}

异常示例

{
    "err_msg": "space not exist",
    "err_no": 401002,
    "log_id": "202308221926108152CB83794BE101C43B"
}

查询转码的状态

API 说明

查询视频转码任务的状态。

使用限制

•

run_id 需要是有效的。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/get_work_flow_exection
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例：：clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
run_id	string	string	转码任务的 id，可用于查询转码的状态

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/get_work_flow_exection' \
--header 'Content-Type: application/json' \
--header 'access-token: cltxxxx' \
--data '{
     "run_id":"xxxxx"
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
run_status	int	是	转码任务运行状态（1:未转码 2:转码中 9:转码失败 10:转码成功）
run_status_msg	string	是	转码任务运行的状态中文

响应示例

正常示例

{
    "err_msg": "success",
    "err_no": 0,
    "log_id": "202308221926108152CB83794BE101C43B"
}

异常示例

{
    "err_msg": "space not exist",
    "err_no": 401002,
    "log_id": "202308221926108152CB83794BE101C43B"
}

查询播放 Top100 的视频

API 说明

查询播放次数 top100 的视频。

使用限制

•

限流 20 qps。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/describe_vod_played_top_data
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例： clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
env_id	string	是	抖音云 prod 环境的 id，需要登录抖音云控制台查看
order_type	int	是	5：按播放次数降序 6：按流量降序
start_time	int	是	时间戳：起始时间 start_time 只能查询最近 30 天	1715591732
end_time	int	是	时间戳：结束时间 end_time ＞ start_time	1715591732

请求示例

curl --location https://open.douyin.com/api/dyc_voc/describe_vod_played_top_data 
--header 'Content-Type: application/json' 
--header 'access-token: cltxxxx' \
--data '{
    "env_id":"env-5O3BlaleIR",
    "start_time" : "1713196800",
    "end_time":"1715616000",
    "order_type":"5"
}

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
play_static_infos	PlayStatInfo	是

PlayStatInfo

名称	类型	是否必填	描述	示例值
vid	string	是	视频 id
app_id	string	是	小程序 id
name	string	是	视频名称
size	int	是	视频大小，单位为字节
duration	double	是	视频长度，单位为秒
create_time	string	是	视频创建时间
play_count	int	是	播放次数
traffic	int	是	流量，单位为字节

响应示例

正常示例

{
    "err_msg": "success",
    "err_no": 0,
    "log_id": "20240531xxxxxxxx",
    "play_static_infos": [
        {
            "duration": 0,
            "name": "-",
            "play_count": 109,
            "size": 0,
            "traffic": 358694,
            "vid": "vxxxxxxx",
            "app_id": "",
            "create_time": "-"
        }
    ]
}

异常示例

{
    "err_msg": "space not exist",
    "err_no": 401002,
    "log_id": "xxxxxxx"
}

查询指定视频播放流量

API 说明

支持查询指定视频的播放流量，支持按照小程序维度拆分流量分析。

使用限制

限流 20qps。

接口说明

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/dyc_voc/describe_vod_played_static_data
HTTP Method	POST
Scope	cloud.playlet
权限要求	默认授权

请求头

字段名	类型	位置	是否必填	字段说明
Content-Type	string	Header	是	固定值：application/json
access-token	string	Header	是	调用/oauth/client_token/生成的 token，此 token 不需要用户授权。示例： clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
env_id	string	是	抖音云 prod 环境的 id，需要登录抖音云控制台查看
vid_list	list<string>	是	用于流量分析的抖音云视频 id（最多 100 个）
app_id_list	list<string>	否	传入此参数后，会返回 vid 在各个小程序 appid 下的播放数据（最多 20 个）
order_type	int	是	1：播放次数升序 2：播放次数降序 3：流量升序 4:按流量降序
start_time	int	是	时间戳：起始时间 start_time 只能查询最近 30 天	1715591732
end_time	int	是	时间戳：结束时间 end_time ＞ start_time	1715591732

请求示例

curl --location 'https://open.douyin.com/api/dyc_voc/describe_vod_played_static_data' \
--header 'Content-Type: application/json' \
--header 'access-token: cltxxxx' \
--data '{
    "env_id":"env-5O3BlaleIR",
     "start_time" : "1713196800",
    "end_time":"1715616000",
    "order_type":"1",
    "vid_list": [
        "v03b12g10003coln878fcpip5beoml1g"
    ],
    "app_id_list":[""]
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	string	是	错误码
err_msg	int	是	错误详情
log_id	string	是	日志 id,用户 oncall 排查问题
play_static_infos	PlayStatInfo	是

PlayStatInfo

名称	类型	是否必填	描述	示例值
vid	string	是	视频 id
app_id	string	是	小程序 id（入参中 app_id_list 未指定小程序，则返回 vid 播放数据不区分小程序，此时 app_id 为空。）
name	string	是	视频名称
size	int	是	视频大小，单位为字节
duration	double	是	视频长度，单位为秒
create_time	string	是	视频创建时间
play_count	int	是	播放次数
traffic	int	是	流量，单位为字节

响应示例

正常示例

{
    "err_no": 0,
    "log_id": "",
    "play_static_infos": [
        {
            "vid": "xxxx",
            "app_id": "",
            "create_time": "2024-04-26 xx:30:34",
            "duration": 81.48,
            "name": "xxx.mov",
            "play_count": 0,
            "size": 80482492,
            "traffic": 0
        }
    ],
    "err_msg": "success"
}

异常示例

{
    "err_msg": "space not exist",
    "err_no": 401002,
    "log_id": "202308221926108152CB83794BE101C43B"
}

媒资管理OpenApi收藏我的收藏

分页获取媒资列表

API 说明

使用限制

接口说明

基本信息

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

错误码

删除媒资列表

API 说明

使用限制

接口说明

基本信息

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

根据 Vid 获取可播放链接

API 说明

使用限制

接口说明

基本信息

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

通过 Url 批量上传视频

API 说明

使用限制

接口说明

基本信息

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

查询 URL 批量上传任务状态

API 说明

使用限制

接口说明

基本信息

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

媒资转码

API 说明

使用限制

接口说明

基本信息

限流情况

请求头

请求参数

请求示例

响应参数

响应示例

正常示例

异常示例

查询转码的状态

API 说明

使用限制

接口说明

基本信息

媒资管理OpenApi
收藏
我的收藏