# 小说剧开放平台 API 接入文档

更新时间：2026-03-16 20:04:40

本文档详细说明了小说剧业务中所有开放接口的调用方式、参数说明及返回结果。

# 1. 整体说明

环境域名: https://open.kuaishou.com (opens new window)

鉴权: 所有接口均需在Query Param 中携带 appId和 AccessToken。

数据格式: POST 请求体默认为 application/json。

目前接口未对外部开放。权限 Scope: scope.ks.novel

CURL中的域名均是内部使用的测试域名，仅供参考。

# 1.1 整体流程

对于外部开发者而言，小说剧的创建和使用逻辑上分为几个阶段。

# 1.2 环境说明

线上域名

https://open.kuaishou.com/

例如图片上传完整路径：https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/img/upload

权限

访问接口需要申请权限scope，需要提供appId 联系运营线下人工添加权限。

授权后，需要刷新access_token。

线上测试数据：所有测试剧集，剧名必须是使用【测试xxx功能（通过/不通过）01】来标记，不然可能不会及时处理。（xxx=功能名；通过/不通过=希望平台操作结果）

# 1.3 token验证

获取 access_token

该授权方式使用 OAuth2 的 client credentials 模式，即向开发者授权非用户资源。

项目	值
Host	https://open.kuaishou.com
Path	/oauth2/access_token
Method	POST
Content-Type	application/x-www-form-urlencoded

Param

参数	是否必须	类型	说明
app_id	是	string	应用ID
app_secret	是	string	应用申请时的密钥
grant_type	是	string	固定值“client_credentials”

请求curl示例：

curl "https://open.kuaishou.com/oauth2/access_token?grant_type=client_credentials&app_secret=your_app_secret&app_id=yourappId"

响应示例

{
  "result": 1,
  "access_token": "xxxxxxx", // 用于获取隐私资源
  "expires_in": 172800,          // 过期时间（秒）
  "token_type" : "bearer"
}

# 2. 资源接口

本文档详细说明了小说剧业务中关于图片和视频上传的开放接口调用方式。

# 2.1 图片上传

将图片上传至快手服务器，用于小说剧封面、备案文件等。

接口地址: /openapi/mp/developer/playlet/novelDrama/img/upload

请求方式: POST

# 请求参数 (Body)

参数名	类型	必填	说明
imgUrl	String	是	图片链接，图片的公网 URL 地址

请求示例：

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/img/upload?app_id=ks123456789012345&access_token=XXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "imgUrl":"https://img.iplaysoft.com/wp-content/uploads/2019/free-images/free_stock_photo.jpg"
}'

# 返回结果

{
  "result": 1,
  "error_msg": "success",
  "data": {
    "imgKey": "xxxxxxxxxxxx"
  }
}

imgKey: 上传成功后的图片标识，后续在创建/编辑小说剧接口中使用此 key 作为封面字段。

# 错误码

10000200: appId 在黑名单中、appId不合法等错误。

# 2.2 视频上传 (URL方式)

注意：小说剧的集视频要求20分钟以内，如果超过请分集后上传

通过提供视频的公网 URL 进行上传。

接口地址: /openapi/mp/developer/playlet/novelDrama/video/url/upload

请求方式: POST

# 请求参数（Body）

参数名	类型	必填	说明
url	String	是	视频的公网 URL 地址
callbackUrl	String	否	上传完成后的回调地址

请求参数说明

url

1.资源链接；目前仅支持MP4和m3u8

2.如果链接带有有效期，请确保链接有效期足够长（建议一周），防止资源挤兑排队时，无法下载重新排队的情况。

3.m3u8视频链接path部分必须带.m3u8后缀，比如xxxx.m3u8?auth_key=xxx.

4.m3u8协议比较复杂，部分情况可能支持不是很完善，建议提前测试，有问题随时反馈。

callbackUrl

回调地址。

会告知处理视频上传结果：（查询接口也会返回视频目前状态）

通知可能重复、可能会丢。

1.消息要做好幂等处理。

2.不要强依赖回调通知，通过查询接口查视频状态。

回调数据格式

{
    "data": {
        "app_id": "ks707065143182458884",
        "current_time": 1718195302042,
        "video_id": "af41cc28dcb81961",
        "status": 2
    },
    "message_id": "0d41e36a-57a3-4244-9d81",
    "event": "MP_VIDEO_EVENT",
    "app_id": "ks707065143182458884",
    "timestamp": 1718195302936
}

视频状态status枚举

1.处理中

2.转码成功

3.转码失败

4.视频拉取失败

开发者接收到消息后返回平台的http状态码应是200，并且返回字段result=1代表成功，其他都是代表失败，失败平台会重试调用。

{
  "result":1,
  "message_id":"0d41e36a-57a3-4244-9d81"
}

webhook接入详细文档：https://open.kuaishou.com/platform/openApi?menu=60

请求示例：

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/video/url/upload?app_id=xxx&access_token=xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url":"https://mv-video.zwlab.cn/f34409ff298442e4b099c30664b608c6/0b84c52f9485411e90b42ff59ff0b376-fa90977c43b8c51.mp4",
    "callbackUrl" : "非必须"
}'

# 返回结果

{
  "result": 1,
  "error_msg": "success",
  "data": {
    "videoId": "xxxxxxxx"
  }
}

videoId: 视频的唯一标识，用于后续查询状态或作为小说剧集内容。

# 2.3 视频文件上传

上传说明：视频上传分为两种，整片上传和分片上传。整片上传把视频资源一次性上传，由于视频文件较大，上传容易失败，整体重试成本又比较高。因此，对于比较大（大于10MB）的视频，建议使用分片上传（每个分片在10MB以内）。1.注意视频上传的域名地址，是申请token时下发的endpoint。2.由于视频需要云平台异步处理，完成上传之后无法立刻使用，需要等待云平台处理完成，可以调用查询接口查询视频状态，或者稍后尝试在创建小说剧时使用视频资源。每一次上传都要申请一个新的token。3.视频上传不要用form-data的形式。一次视频上传流程如下：

# 2.3.1 申请上传Token

该接口用于直接上传视频文件流的场景，第一步：申请上传 Token。

每次视频上传都要申请一个新的upload_token

接口地址: /openapi/mp/developer/playlet/novelDrama/video/upload/apply

请求方式: POST

请求参数

无参数，加鉴权参数即可

示例:

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/video/upload/apply?app_id=ks707065143182458884&access_token=XXX' \

返回结果

{
  "result": 1,
  "data": {
    "upload_token": "xxxxxxxx",
    "endpoint": "xxx.kuaishou.com/..."
  },
  "error_msg": "success"
}

upload_token: 上传凭证。

endpoint: 上传服务器地址。

注意: 获取 Token 后，需自行按照快手媒体云上传协议，将视频文件推送到 endpoint，并携带 upload_token。

# 2.3.2 视频上传--整片上传

注意不要用form-data传文件，这样传输的数据会包含这种数据，导致转码失败。

Content-Disposition: form-data; name="file"; filename="cbb9369fe26ce37585a6defbfc003b8a.mp4"
Content-Type: video/mp4

POST：http://{endpoint}/api/upload

字段名	类型	是否必填	说明
upload_token	String	是	前面申请的视频上传token，拼接到param中
视频文件	二进制文件	是	视频文件通过二进制文件形式上传

请求curl示例

curl --location --request POST 'http://{endpoint}/api/upload?upload_token=XXXX' \
--header 'Content-Type: video/mp4' \ç
--data-binary 'xxxx.mp4'

相应示例：

{
    "result": 1
}

# 2.3.3 视频上传--分片上传

POST：http://{endpoint}/api/upload/fragment

请求参数

字段名	类型	是否必填	说明
upload_token	String	是	前面申请的视频上传token，拼接到param中
fragment_id	Integer	是	分片ID；分片id从0开始，依次递增。
视频文件	二进制文件	是	视频文件通过二进制文件形式上传

注意不要用form-data传文件，这样接收到的文件数据会包含下面这种信息，导致转码失败。

Content-Disposition: form-data; name="file"; filename="cbb9369fe26ce37585a6defbfc003b8a.mp4"
Content-Type: video/mp4

分片上次是把原视频按照二进制的格式切割成多个片段，不是把多个视频合并成一个视频。

java代码可以参考这个链接：https://mp.kuaishou.com/docs/develop/IndustrySolutions/highLightUploadInterface.html (opens new window)

正确示例：

curl --location --request POST 'http://{endpoint}/api/upload/fragment?upload_token=XXXX&fragment_id=0' \
--data-binary '@/Users/xxx/xxx/xxx'

响应示例

{
    "result": 1
}

# 2.3.4 视频上传-分片上传-提交分片数量信息

当分片上传完成之后，提交视频分片。

POST：http://{endpoint}/api/upload/complete

字段名	类型	是否必填	说明
upload_token	String	是	前面申请的视频上传token，拼接到param中
fragment_count	Integer	是	分片的数量，拼接到param中

请求示例

curl --location --request POST 'http://{endpoint}/api/upload/complete?upload_token=XXXX&fragment_count=3'

响应示例：

{
    "result": 1
}

# 2.4 视频上传 (发布视频)

用于直接上传视频文件流的场景，第二步：文件上传完成后，调用此接口发布视频。

接口地址: /openapi/mp/developer/playlet/novelDrama/video/upload/publish

请求方式: POST

# 请求参数（Query）

参数名	类型	必填	说明
upload_token	String	是	第一步申请到的上传凭证

请求示例:

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/video/upload/apply?app_id=ks707065143182458884&access_token=XXX&upload_token=xxxxxx' \

# 返回结果

{
  "result": 1,
  "data": {
    "videoId": "xxxxxxxx"
  },
  "error_msg": "success"
}

videoId: 视频的唯一标识。

# 2.5 查询视频状态

查询视频的处理状态（如转码中、成功、失败）。

接口地址: /openapi/mp/developer/playlet/novelDrama/video/info

请求方式: POST

# 请求参数（Body）

参数名	类型	必填	说明
videoId	String	是	视频 ID

示例：

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/playlet/novelDrama/video/info?app_id=xxx&access_token=xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "videoId":"xxxxx"
}'

# 返回结果

{
  "result": 1,
  "data": {
    "status": 1
  },
  "error_msg": "success"
}

status:视频状态码

具体枚举值

1.处理中

2.转码成功

3.转码失败

4.视频拉取失败

# 错误码

10000510: 视频不存在。

# 3.小说剧相关接口

# 3.1 创建小说剧

创建一部新的小说剧。

接口地址: /openapi/mp/developer/playlet/novelDrama/create

请求方式: POST

# 请求参数（Body）

参数名

类型

必填

说明

albumInfo

Object

是

剧集基础信息

episodeInfoList

List<EpisodeInfo>

是

剧集列表,至少传3集，一次最多上传100集

（小说剧审核时要求看正片信息）

EpisodeInfo结构见下文

albumInfo 结构:

参数名类型必填说明

title String 是剧集名称，大于1个字小于30个字

themeInfo

Object

是

题材信息

"themeInfo": {
      "themeType": 3,
      "themeList": [301,302]
    }

themeType 题材类型

必填1个

类型

Integer

说明

1：重大革命和历史题材

2：特殊题材

3：一般题材

themeList 主题列表重大革命和历史题材可没有，其他题材至少1个最多5个
类型	List<Integer>
特殊题材	`201 政治 202 军事 203 外交 204 国家安全 205 统战 206 民族 207 宗教 208 司法 209 反腐 210 公安 211 革命 212 其他`
一般题材	`301 都市 302 农村 303 青少 304 科幻 305 传记 306 传奇 307 武打 308 宫廷 309 国际传播 310 其他`

totalEpisodeNumber

Integer

是

总集数

大于等于3，小于等于10000；

appPath String 是小程序内跳转路径

cover

String

是

封面图，传2.1图片上传接口返回的imgKey

jpg，jpeg，png格式，单张不超过2M，限1张

introduce

String

是

简介与剧集相关的完整通顺的介绍

字数在100～300字之间

actorInfoList

List<Object>

是

演员列表，字段包含 name, gender, role

列表大小最多100个

演员姓名（非必填）：如果不涉及实际演员，姓名可以为空，姓名不能全是外文，最多20个字

角色名（必填）：最多20个字

性别（必填） 0:男 1:女

"actorInfoList": [
      {
        "name": "张三",
        "gender": 0,
        "role": "男主角"
      },
      {
        "name": "李四",
        "gender": 1,
        "role": "女主角"
      }
    ]

producerList

List<Object>

是

制作人列表，元素包含 name, gender

列表大小最多5个，

姓名（必填）：姓名不能全是外文，最多20个字

性别（必填） 0:男 1:女


    "producerList": [
      {
        "name": "王五",
        "gender": 0
      }
    ]

directorList

List<Object>

是

导演列表，元素包含 name, gender

列表大小最多5个，

姓名（必填）：姓名不能全是外文，最多20个字

性别（必填） 0:男 1:女


    "directorList": [
      {
        "name": "王五",
        "gender": 0
      }
    ]

screenwriterList

List<Object>

是

编剧列表，元素包含 name

列表大小最多5个，

姓名（必填）：姓名不能全是外文，最多20个字


    "screenwriterList": [
      {
        "name": "孙七"
      }
    ]

cost

Integer

是

制作成本（万元）

最小为0，

productionInfo

String

是

制作机构名称

企业名称或达人昵称

限制50个字符

episodeAverageDurationMinutes

Integer

是

单集平均时长（分钟）

注意：小说剧的集视频要求20分钟以内

productionMode Integer 是制作形式：1-横屏，2-竖屏

productionYear Integer 是出品年份

filingInfo

Object

否

制作成本、题材、备案之间的关系

如果是需要平台备案的，那么备案信息这里不填

备案信息

字段

类型

filingType

int

备案类型：

1.重点备案号

2.普通备案号

filingNumber

String

备案号

tips：需要中文括号

"filingInfo": {
        "filingType":1,
        "filingNumber":"（粤）网微剧审字（2024）第002号"
}

filingFileIds

List<String>

否

备案文件图片 ID 列表，传2.1图片上传接口返回的imgKey

如果上传了普通备案编号或重点备案编号，必填；

格式为图片，最少1张，最多10张

"filingFileIds": [
  "img1","img2"
]

notifyUrl

String

否

开发者自定义的回调通知接口 URL

小说剧审核，回调通知（审核通过或者驳回都会通知）。

注意：

平台同时提供了查询和推送接口，开发者不应把webhook定义为唯一审核结果接收通道，应该配合查询接口结合一起使用。

请在回调方法入口打印请求日志，排查是否收到回调通知应该以日志为准。

webhook接口接收到到的body参数：

// 平台发送的事件格式
{
    "data": {
        "novel_drama_id": "kmp5221923770612530966",
            "version": 1,
        "current_time": 1715245586063,
        "status": 2    // 2 审核通过，3 审核驳回
    },
    "message_id": "68e5e3d9-cc16-4711-839c-bca9ea32ae41",
    "event": "PLAYLET_NOTIFY",
    "app_id": "ks707065143182458884",
    "timestamp": 1715245586065
}

开发者接收到消息后返回平台的http状态码应是200，并且返回字段result=1代表成功，其他都是代表失败，失败平台会重试调用。

应返回的数据结果


{"result":1,"message_id":"99443c09-ddf6-4d30-a84d-f92c52e25339"}

webhook接入详细文档：https://open.kuaishou.com/platform/openApi?menu=60

EpisodeInfo 结构:

参数名	类型	必填	说明
episodeNumber	Integer	是	第几集
videoId	String	是	视频 ID (上传视频后获得) 注意：小说剧的集视频要求20分钟以内，如果超过请分集后上传
title	String	是	单集标题
path	String	是	单集页面路径
cover	String	是	单集封面
chargeOrNot	Boolean	是	是否付费

请求Body示例

{
  "albumInfo": {
    "title": "test2",
    "appPath": "page/finisAutoApi/index",
    "themeInfo": {
      "themeType": 3,
      "themeList": [301]
    },
    "totalEpisodeNumber": 10,
    "cover": 
      "088082b301108de5f49204"
    ,
    "introduce": "这是一个示例小说剧的介绍内容，描述了剧集的主要情节和特色，其他都是凑字数凑字数凑字数凑字数述了剧集的主要情节和特色，其他都是凑字数凑字数凑字数凑字数述了剧集的主要情节和特色，其他都是凑字数凑字数凑字数凑字数述了剧集的主要情节和特色，其他都是凑字数凑字数凑字数凑字数。",
    "actorInfoList": [
      {
        "name": "张三",
        "gender": 0,
        "role": "男主角"
      },
      {
        "name": "李四",
        "gender": 1,
        "role": "女主角"
      }
    ],
    "producerList": [
      {
        "name": "王五",
        "gender": ""
      }
    ],
    "directorList": [
      {
        "name": "赵六",
        "gender": 1
      }
    ],
    "screenwriterList": [
      {
        "name": "孙七"
      }
    ],
    "cost": 10,
    "productionInfo": "示例制作机构",
    "episodeAverageDurationMinutes": 1,
    "productionMode": 2,
    "productionYear": 2024,
    "filingInfo": {
                "filingType":1,
                "filingNumber":"(琼)网微剧审字(2025)第116号"
        },
    "filingFileIds": [
              "img1","img2"
        ],
    "notifyUrl": "https://example.com/notify"
  },
  "episodeInfoList": [
    {
      "episodeNumber": 1,
      "videoId": "de50d5751385e361",
      "title": "第一集：初遇",
      "path": "page/finisAutoApi/index",
      "cover": "088082b301108de5f49204",
      "chargeOrNot": false
    },
    {
      "episodeNumber": 2,
      "videoId": "2fbcdc00b78e71e2",
      "title": "第2集：误会",
      "path": "page/finisAutoApi/index",
      "cover": "088082b301108de5f49204",
      "chargeOrNot": false
    },
    {
      "episodeNumber": 3,
      "videoId": "2fbcdc00b78e71e2",
      "title": "第3集：真相",
      "path": "page/finisAutoApi/index",
      "cover": "088082b301108de5f49204",
      "chargeOrNot": false
    }
  ]
}

# 返回结果

字段名	类型	是否必填	描述
novelDramaId	string	是	小说剧id 这个需要持有，作为剧的唯一标识
episodeIdMapping	map	是	第几集和剧集id的映射关系这个mapping信息要持有，播放器需要用到
version	int	是	版本

返回结果示例：

参数version：

第一次创建时，版本=1。
未提审前，进行编辑、追加操作时，版本不会变化。
当上一版审核结果（通过/拒绝）出来后，再次修改信息时版本会+1。
开发者可不感知版本概念。

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
     "episodeIdMapping": {
            "1": "kmnxxxxx",
            "2": "kmnxxxxx",
            "3": "kmnxxxxx"
        }
    "version": 1
  },
  "error_msg": "success"
}

# 3.2 编辑小说剧基础信息

更新已存在小说剧的基础信息（如标题、简介、演职员表等）。

只要基础信息审核通过后，就不可再修改基础信息。

接口地址: /openapi/mp/developer/playlet/novelDrama/album/edit

请求方式: POST

# 请求参数（Body）

参数名	类型	必填	说明
novelDramaId	String	是	小说剧 ID
albumInfo	Object	是	要更新的剧集基础信息，必须写完整的信息 (结构同3.1创建接口)

# 返回结果

参数version：当上一版审核结果（通过/拒绝）出来后，再次修改信息时版本会+1，开发者可不感知版本概念。

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
    "version": 1
  },
  "error_msg": "success"
}

# 3.3 编辑剧集信息

指定要更改的集，更新已存在小说剧的集信息。

接口地址: /openapi/mp/developer/playlet/novelDrama/episode/edit

请求方式: POST

# 请求参数（Body）

参数名

类型

必填

说明

novelDramaId

String

是

小说剧 ID

episodeInfoList

List<EpisodeInfo>

是

需要更新的剧集列表信息，

一次最多修改100集

EpisodeInfo结构同3.1创建接口

# 返回结果

例如更改了 2、4、6集：

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
     "episodeIdMapping": {
            "2": "kmnxxxxx",
            "4": "kmnxxxxx",
            "6": "kmnxxxxx"
        }
    "version": 1
  },
  "error_msg": "success"
}

# 3.4 追加集数

向已存在的小说剧追加新的集数，总集数不可超过1万集

接口地址: /openapi/mp/developer/playlet/novelDrama/episode/append

请求方式: POST

# 请求参数（Body）

参数名

类型

必填

说明

novelDramaId

String

是

小说剧 ID

episodeInfoList

List<EpisodeInfo>

是

追加的剧集列表信息

追加时集数必须连续。

一次最多追加100集，总集数不可超过1万集。

EpisodeInfo结构同3.1创建接口

# 返回结果

例如追加了11-13集：

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
     "episodeIdMapping": {
            "11": "kmnxxxxx",
            "12": "kmnxxxxx",
            "13": "kmnxxxxx"
        }
    "version": 1
  },
  "error_msg": "success"
}

# 3.5 提交审核

将当前编辑/追加后的版本提交审核。

接口地址: /openapi/mp/developer/playlet/novelDrama/submit

请求方式: POST

接口说明：提审的集数越多，审核的时间越久。建议第一次审核时，尽量将集数控制在100集以内，后面再进行追加

# 请求参数（Body）

参数名	类型	必填	说明
novelDramaId	String	是	小说剧 ID

# 返回结果

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
    "version": 1
  },
  "error_msg": "success"
}

# 3.6 上架

将审核通过的版本发布上线。

接口地址: /openapi/mp/developer/playlet/novelDrama/online

请求方式: POST

接口说明：若已存在线上版本，会进行替换（下架之前版本并上架当前版本，谨慎操作）

# 请求参数（Body）

参数名	类型	必填	说明
novelDramaId	String	是	小说剧 ID
version	Integer	否	指定上线的版本号，不传则默认上线最近一次审核通过版本

# 返回结果

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
    "version": 4//上线的版本
  },
  "error_msg": "success"
}

# 3.7 下架

将已上线的版本下线。

接口地址: /openapi/mp/developer/playlet/novelDrama/offline

请求方式: POST

# 请求参数（Body）

参数名	类型	必填	说明
novelDramaId	String	是	小说剧 ID
version	Integer	否	指定下架的版本号，不传默认下架当前的线上版本

# 返回结果

{
  "result": 1,
  "data": {
    "novelDramaId": "kmnxxxxxxxx",
    "version": 4//下线的版本
  },
  "error_msg": "success"
}

# 3.8 分页查询版本列表

查询小说剧的历史版本列表。

接口地址: /openapi/mp/developer/playlet/novelDrama/version

请求方式: GET

# 请求参数（Query）

参数名	类型	必填	默认值	说明
novelDramaId	String	是	-	小说剧 ID
pageNum	Integer	否	1	页码
pageSize	Integer	否	10	每页数量，最大100

# 返回结果

字段名	类型	是否必填	描述
version	Integer	是	版本信息
auditStatus	Integer	是	审核状态 0: 待提审 1.已提审 2.审核通过 3.审核拒绝 4.审核中
auditStatusDesc	String	是	审核状态描述
onlineStatus	Integer	是	在线状态 1：已经上线 2.未上线
onlineStatusDesc	String	是	上线状态描述

{
    "result": 1,
    "error_msg": "success",
    "data": {
        "list": [
            {
                "version": 2,
                "auditStatus": 2,
                "auditStatusDesc": "审核通过",
                "onlineStatus": 2,
                "onlineStatusDesc": "未上线"
            },
            {
                "version": 1,
                "auditStatus": 3,
                "auditStatusDesc": "审核拒绝",
                "onlineStatus": 2,
                "onlineStatusDesc": "未上线"
            }
        ],
        "total": 2
    }
}

# 3.9 分页查询剧集详情

查询指定版本小说剧的详细信息（含分集列表）。

接口地址: /openapi/mp/developer/playlet/novelDrama/detail

请求方式: GET

# 请求参数（Query）

参数名	类型	必填	默认值	说明
novelDramaId	String	是	-	小说剧 ID
version	Integer	是	-	版本号
pageNum	Integer	否	1	分集列表页码
pageSize	Integer	否	10	分集列表每页数量，最大100

# 返回结果

返回结果中包含剧和集两个部分的审核结果：

字段名	描述
albumInfo	剧的基础信息，参考3.1节 auditStatus字段状态 0: 待提审 1.已提审 2.审核通过 3.审核拒绝 4.审核中 auditReason 审核原因审核通过时：返回的是小说剧类型审核失败时：返回的是错误原因
episodeInfoList	集信息字段，参考3.1节 auditStatus字段状态 0: 待提审 1.已提审 2.审核通过 3.审核拒绝 4.审核中 auditReason 审核原因审核通过时：空审核失败时：返回的是错误原因
episodeInfoList
versionInfo	整部剧整体的审核状态信息

返回值示例：

{
    "result": 1,
    "error_msg": "success",
    "data": {
        "albumInfo": {
            "title": "test2",
            "themeInfo": {
                "themeType": 3,
                "themeList": [
                    301
                ]
            },
            "totalEpisodeNumber": 10,
            "appPath": "page/finisAutoApi/index",
            "cover": "088082b301108de5f49204",
            "introduce": "这是一个示例小说剧的介绍内容",
            "actorInfoList": [
                {
                    "name": "张三",
                    "gender": 0,
                    "role": "男主角"
                },
                {
                    "name": "李四",
                    "gender": 1,
                    "role": "女主角"
                }
            ],
            "producerList": [
                {
                    "name": "王五",
                    "gender": 1
                }
            ],
            "directorList": [
                {
                    "name": "赵六",
                    "gender": 1
                }
            ],
            "screenwriterList": [
                {
                    "name": "孙七"
                }
            ],
            "cost": 10,
            "productionInfo": "示例制作机构",
            "episodeAverageDurationMinutes": 1,
            "productionMode": 2,
            "productionYear": 2024,
            "filingInfo": {
                "filingType": 3,
                "filingNumber": "（快手）网微剧备字（2026）第46号"
            },
            "filingFileIds": null,
            "notifyUrl": "https://example.com/notify",
            "auditStatus": 2,
            "auditReason": "如果通过，会返回剧类型：表情包微小说剧\n",
            "novelDramaId": "kmn5221923895583911067"
        },
        "episodeInfoList": [
            {
                "episodeNumber": 1,
                "videoId": "de50d5751385e361",
                "title": "第一集：初遇 通过后再编辑",
                "path": "page/finisAutoApi/index",
                "cover": "088082b301108de5f49204",
                "chargeOrNot": false,
                "novelDramaId": "kmn5243315993453338027",
                "auditStatus": 2,
                "auditReason": ""
            },
            {
                "episodeNumber": 2,
                "videoId": "2fbcdc00b78e71e2",
                "title": "第2集：误会",
                "path": "page/finisAutoApi/index",
                "cover": "088082b301108de5f49204",
                "chargeOrNot": false,
                "novelDramaId": "kmn5195183771802700061",
                "auditStatus": 2,
                "auditReason": ""
            },
            {
                "episodeNumber": 3,
                "videoId": "2fbcdc00b78e71e2",
                "title": "第3集：真相",
                "path": "page/finisAutoApi/index",
                "cover": "088082b301108de5f49204",
                "chargeOrNot": false,
                "novelDramaId": "kmn5216857345727517967",
                "auditStatus": 2,
                "auditReason": ""
            }
        ],
        "total": 3,
        "versionInfo": {
            "version": 3,
            "auditStatus": 2,
            "auditStatusDesc": "审核通过",
            "onlineStatus": 1,
            "onlineStatusDesc": "已上线"
        }
    }
}

# 3.10 小说剧授权接口

接口说明：开发者可将本小程序的小说剧授权给其他小程序。被授权小程序可在播放器使用对应小说剧，但不可调用openapi接口查看、编辑小说剧

接口地址: /openapi/mp/developer/playlet/novelDrama/grant

请求方式: POST

Content-Type:application/json

# 请求参数（Body）

参数名

类型

必填

描述

novelDramaId

String

是

小说剧ID

appIdList

Array

是

被授权的小程序appId列表。

最多200个（不管是一次还是总数，都是最多200个）

请求示例

{
    "novelDramaId": "kmn_1234567890",
    "appIdList": [
        "ks1234567890",
        "ks0987654321"
    ]
}

返回示例

{
    "result": 1,
    "message": "success"
}

# 3.11 小说剧取消授权接口

接口说明：开发者可取消其他小程序的该小说剧使用权限。

接口地址: /openapi/mp/developer/playlet/novelDrama/ungrant

请求方式: POST

Content-Type:application/json

# 请求参数（Body）

参数名	类型	必填	描述
novelDramaId	String	是	小说剧ID
appIdList	Array	是	被取消授权的小程序appId列表

请求示例

{
    "novelDramaId": "kmn_1234567890",
    "appIdList": [
        "ks1234567890",
        "ks0987654321"
    ]
}

返回示例

{
    "result": 1,
    "message": "success"
}

# 3.12 查询小说剧授权列表接口

接口说明：查询某个小说剧已经授权的小程序列表。

接口地址: /openapi/mp/developer/playlet/novelDrama/grantedInfo

请求方式: GET

# 请求参数（Query）

参数名	类型	必填	描述
novelDramaId	String	是	小说剧ID

请求示例

GET /openapi/mp/developer/novelDrama/grantedInfo?novelDramaId=kmn_1234567890

返回示例

{
    "result": 1,
    "message": "success"
}

# 4 错误码

# 4.1 通用错误码

错误码	错误码名称	描述
1	SUCCESS	成功
10000200	INVALID_REQUEST	无效请求，参数校验失败 10000200是一个大类，通常表示请求参数有问题，具体说明见下文
10000500	SERVER_ERROR	服务器内部错误，遇到这个错误时，请联系我们

# 4.2 10000200--INVALID_REQUEST

# 剧基础信息校验

error_msg	说明
剧集信息不能为空	albumInfo 为空
剧集名称不能为空	title 为空
剧集名称不能超过N个字符	title 超长（默认30字符）
剧集数量不能为空	totalEpisodeNumber 为空
剧集数量不能小于N	totalEpisodeNumber < 3
剧集数量不能大于N	totalEpisodeNumber > 10000
题材信息是必填项	themeInfo 为空
一级题材是必填项	themeType 为空
一级题材类型不合法	themeType 不在 [1,2,3] 范围
二级题材至少选择N个	themeList 数量不足
二级题材最多选择N个	themeList 数量超限（默认5个）
剧集封面不能为空	cover 为空
剧集简介不能为空	introduce 为空
剧集简介需要在100-300个字符	introduce 长度不在范围内
制作成本不能为空	cost 为空
制作成本不能为空, 且必须大于等于0	cost < 0
制作机构不能为空	productionInfo 为空
制作机构不能超过N个字符	productionInfo 超长（默认50字符）
单集平均时长不能为空	episodeAverageDurationMinutes 为空
制作形式不能为空	productionMode 为空
制作形式不合法	productionMode 值无效
出品年份不能为空	productionYear 为空
出品年份必须是正整数	productionYear <= 0
出品年份不能超过当前年份	productionYear > 当前年份
小说剧的appPath不能为空	appPath 为空
剧appPath不合法	appPath 格式无效

# 人员信息校验

error_msg	说明
演员信息是必填项	actorInfoList 为空
演员信息至少需要N个	actorInfoList.size < 2
演员信息不能超过N个	actorInfoList.size > 10
演员角色名不能是空	actor.role 为空
角色不能超过N个字符	actor.role 超长（默认20字符）
演员性别不能是空, 必须是0/1（对应男和女）	actor.gender 无效
演员姓名不能超过N个字符	actor.name 超长
演员姓名不能全是外文	actor.name 无中文字符
导演信息是必填项	directorList 为空
导演信息不能超过N个	directorList.size > 5
导演姓名不能是空	director.name 为空
导演姓名不能超过N个字符	director.name 超长
导演姓名不能全是外文	director.name 无中文字符
导演性别不能是空, 必须是0/1（对应男和女）	director.gender 无效
编剧信息是必填项	screenwriterList 为空
编剧信息不能超过N个	screenwriterList.size > 5
编剧姓名不能是空	screenwriter.name 为空
编剧姓名不能超过N个字符	screenwriter.name 超长
编剧姓名不能全是外文	screenwriter.name 无中文字符
制片人信息是必填项	producerList 为空
制片人信息不能超过N个	producerList.size > 5
制片人姓名不能是空	producer.name 为空
制片人姓名不能超过N个字符	producer.name 超长
制片人姓名不能全是外文	producer.name 无中文字符
制片人性别不能是空, 必须是0/1（对应男和女）	producer.gender 无效

# 集信息校验

error_msg	说明
集数不能为空	episodeNumber 为空
集数必须大于0	episodeNumber <= 0
第N集正片名称不能为空	episode.title 为空
第N集正片名称不能超过N个字	episode.title 超长（默认30字）
第N集正片封面不能为空	episode.cover 为空
第N集是否收费不能为空	episode.chargeOrNot 为空
第N集appPath不能为空	episode.path 为空
第N集appPath不合法	episode.path 格式无效
集数不连续	集数编号不连续
集数超过总集数	episodeNumber > totalEpisodeNumber
剧集信息不能重复	存在重复的 episodeNumber
视频ID不能是空	videoId 为空
图片信息不能是空	imgId 为空

# 视频时长校验

error_msg	说明
平均时长不能为空	episodeAverageDurationMinutes 为空
平均时长不得超过N分钟	episodeAverageDurationMinutes > 20
视频时长超过N分钟	单个视频时长 > 20分钟
平均时长须不低于最短正片时长N分钟且不高于最长正片时长N分钟	平均时长不在实际时长范围内
一次最多传N集	单次上传集数 > 100

# 备案校验

error_msg	说明
备案号信息缺失	filingInfo 不完整
重大革命和历史题材，特殊题材的制作成本必须大于N万元	非一般题材 cost < 30万
根据制作成本和题材要求，需要填写特殊/普通备案号	需要备案但未填写
备案文件不能为空，至少上传1个	filingFileIds 为空
备案文件不能超过N个	filingFileIds.size > 10

# 追加集数校验

error_msg	说明
追加集数不能为空	episodeInfoList 为空
最大集数不能超过N	追加后 maxNumber > 10000
请从N集开始追加	追加集数不连续
追加后当前集数大于总集数	追加后超过 totalEpisodeNumber
追加后集数不连续	追加的集数不连续
版本数量已达上限	版本数超限

# 上下线校验

error_msg	说明
novelDramaId不能为空	novelDramaId 为空
version必须是数字	version 非数字
剧集ID不能为空	novelDramaId 为空
上架无效版本	version 无效
无效版本号	version 无效
非法版本号	version 无效
未找到该版本的审核记录	版本记录不存在
非法操作	appId 不匹配
该版本未审核通过，无法上架	审核状态非 APPROVED
未找到在线版本	无在线版本可下线
该版本未上线	onlineStatus 非 ONLINE
该小程序非创建小程序，无法下线	appId 非创建者
未找到该版本的剧集信息	剧集信息不存在

# 图片上传校验

error_msg	说明
appId in black list	appId 在黑名单中
上传失败	图片上传失败

# 4.3 小说剧内容错误码

错误码	错误码名称	描述
10000424	INDUSTRY_CONTENT_NOT_EXIST	小说剧不存在
10000427	PLAYLET_NOT_ONLINE	小说剧已下线
10000428	PLAYLET_EPISODE_NOT_EXIST	小说剧分集不存在
10000429	PLAYLET_PLAYURL_FAILED	视频播放链接获取失败
10000430	PLAYLET_MODIFY_ERROR	并发修改冲突，请勿多次修改
10000431	PLAYLET_MODIFY_FORBIDDEN	存在处理中的记录
10000432	PLAYLET_BAN	小说剧被封禁
10000434	INDUSTRY_CONTENT_NOT_ONLINE	资源非在线状态
10000440	RESOURCE_NOT_EXIST	资源不存在
10000450	RESOURCE_APPROVAL_IN_AUDIT	存在审核中资源
10000451	RESOURCE_NOT_EXIST_IN_MODIFICATION	不存在修改中的资源，无法提交
10000452	PLAYLET_VERSION_NOT_APPROVAL	小说剧版本审核未通过，无法上架
10000453	PLAYLET_VERSION_ALREADY_ONLINE	小说剧版本已上架，无法再次上架
10000454	PLAYLET_VERSION_CANCEL_ERROR	小说剧版本已进入审核，无法撤销
10000456	PLAYLET_GRANT_NOT_VALID	非小说剧小程序，无法授权
10000460	PLAYLET_IMG_NOT_EXISTED	小说剧图片不存在

# 4.4 视频相关错误码

错误码	错误码名称	描述
10000457	INDUSTRY_VIDEO_NOT_EXIST	视频不存在
10000458	INDUSTRY_VIDEO_IN_PROCESS	视频转码中
10000459	INDUSTRY_VIDEO_FAILED	视频转码失败
10000504	VIDEO_UPLOAD_TOKEN_NOT_EXIST	视频上传Token不存在
10000505	VIDEO_UPLOAD_URL_EXIST	URL视频上传已处理过
10000506	VIDEO_UPLOAD_LIMIT	达到视频上传限制
10000510	VIDEO_ID_NOT_EXIST	视频ID不存在

# 5 FAQ（持续更新）

自查tips：

所有接口需要 AccessToken 认证，需要有scope 为 novel_drama，获得scope后要重新生成AccessToken
result = 1 表示成功，其他值表示失败
错误码 10000200 (INVALID_REQUEST) 是最常见的参数校验错误，需根据 error_msg 定位具体问题
并发操作会返回 10000430 (PLAYLET_MODIFY_ERROR)，建议业务侧做好并发控制

# 1. 上传 m3u8 视频失败/无法播放：之前还能用，现在突然不行了？

现象

m3u8 格式视频上传/回调/拉取失败，前一天正常、当天开始异常。
多个 m3u8 链接均失败（非个别文件）。

说明

当前点播侧对 m3u8 支持不稳定/已不支持，可能导致统一失败。
在上传量较大时，转码与回调耗时会显著增加，甚至出现回调失败。

处理建议

建议 将视频转为 mp4 后再上传。
若出现回调超时/拉取失败，建议稍后重试，并优先检查源文件是否可公网稳定访问。

# 2. 上传返回了 videoId，但审批不通过/提示不可用，为什么？

现象

已拿到 videoId，但后续使用时报错或审批不通过。
出现“空视频/黑屏/无内容”等异常，导致失败。

常见原因

videoId 对应资源 并未上传成功 或 源视频内容异常（空视频），导致该 videoId 不可用。

处理建议

确认源视频文件可正常播放、时长/码率正常、内容非空。
重新上传生成新的 videoId 后再提审/绑定使用。

# 3. 审核周期一般多久？最近为什么变慢？

问题

开发者咨询“审批/审核要多久”。

口径说明

近期审核量增加，审核周期较以往拉长。
当前审核周期一般为 24~48 小时（以实际审核量为准）。

建议

如需查看具体失败原因，优先使用“版本/详情查询接口”自查（见第 9 条）。

# 4. 审核为什么显示“通过/不通过”不一致？是不是审错了？

现象

剧信息看起来已通过，但集信息仍显示未通过/未审核，开发者认为“审错”。

说明（审核流程）

审核通常分为两步：

剧基本信息审核（先审剧）
分集信息审核（剧通过后再审集）

因此可能出现“剧通过了，但集还在审核/未开始审核”的情况。

处理建议

请确认剧基本信息已通过，并等待分集审核完成。

# 5. 分页查询时，请求多次为什么每次都返回第一条/第一集数据？

现象

短剧有多集，按分页每次取 1 条，连续请求多次，但返回始终是第一集。

常见原因

分页参数使用错误（例如传了 page，但实际接口要求 pageNum）。

处理建议

将分页参数 page 改为 pageNum 后重试。
同时确认 pageSize 是否按预期传入。

# 6. 接口报错：episodeIdList 传了但不生效/提示找不到，怎么排查？

现象

请求参数里传了 episodeIdList，但接口报错或返回异常。

常见原因

episodeIdList 传入的 ID 类型不匹配：需要使用集对应的 指定格式 ID（如 kmn 开头的 id）。

处理建议

将 episodeIdList 替换为 集对应的 kmn 开头 id 后重试。

# 7. 接入播放器后，为什么播放期间接口会一直轮询请求？以前用 video 标签没有这个接口

现象

接入播放器后，播放过程中出现持续请求某接口的情况。

说明

该接口属于 视频链接/视频内容获取 类型。播放器在播放期间可能持续获取最新可用的视频内容或分片信息，因此会出现轮询。

建议

属于正常机制，重点关注：

返回是否稳定
链接是否可访问
是否存在频繁失败导致重试风暴（如有可提供请求日志进一步排查）

# 8. 剧目ID、剧集ID、playId 分别是什么？怎么对应？

参数定义

剧目ID：使用小说剧的 DramaId
剧集ID：每一集也有自己的 DramaId（集维度）
playId：对应 集的 dramaId

建议

涉及“某一集”的操作时，优先使用集维度 DramaId / playId。

# 9. version 接口是做什么的？怎么查审核原因？

用途

version 相关接口用于：

查看小说剧 版本信息
查看每个版本的 审核状态

如何查看每集的审核原因：

查详情接口

推荐联动查询--包含剧的审核拒绝原因和每一集的审核拒绝原因

分页查询剧集详情/指定版本小说剧详细信息（含集列表）：

GET /openapi/mp/developer/playlet/novelDrama/detail

# 10.创建小说剧接口反馈：最短时长和最长时长都是 1 分钟？

现象

开发者认为“最短时长 = 最长时长 = 1 分钟”不合理

说明

视频时长是按照向下取整的。

125秒 / 60 = 2分钟
59秒 / 60 = 0分钟
因此如果小说剧都是1分xx秒，那么实际上每集时长会算作1分钟。

关于单集时长：

单集平均时长必须大于0，且必须是整数，所以单集平均时长实际上>=1
要求：单集平均时长须 >= 最短时长且须 <= 最长时长
所以单集时长如果不满足该要求，会提示单集平均时长须 >= 最短时长且须 <= 最长时长

# 小说剧开放平台 API 接入文档

# 1. 整体说明

# 1.1 整体流程

# 1.2 环境说明

线上域名

权限

线上测试数据：所有测试剧集，剧名必须是使用【测试xxx功能 （通过/不通过）01】来标记，不然可能不会及时处理。（xxx=功能名；通过/不通过=希望平台操作结果）

# 1.3 token验证

# 2. 资源接口

# 2.1 图片上传

# 请求参数 (Body)

# 返回结果

# 错误码

# 2.2 视频上传 (URL方式)

# 请求参数（Body）

# 返回结果

# 2.3 视频文件上传

# 2.3.1 申请上传Token

请求参数

返回结果

# 2.3.2 视频上传--整片上传

# 2.3.3 视频上传--分片上传

# 2.3.4 视频上传-分片上传-提交分片数量信息

# 2.4 视频上传 (发布视频)

# 请求参数（Query）

# 返回结果

# 2.5 查询视频状态

# 请求参数（Body）

# 返回结果

# 错误码

# 3.小说剧相关接口

# 3.1 创建小说剧

# 请求参数（Body）

albumInfo 结构:

EpisodeInfo 结构:

# 返回结果

# 3.2 编辑小说剧基础信息

# 请求参数（Body）

# 返回结果

# 3.3 编辑剧集信息

# 请求参数（Body）

# 返回结果

# 3.4 追加集数

# 请求参数（Body）

# 返回结果

# 3.5 提交审核

# 请求参数（Body）

# 返回结果

# 3.6 上架

# 请求参数（Body）

# 返回结果

# 3.7 下架

# 请求参数（Body）

# 返回结果

# 3.8 分页查询版本列表

# 请求参数（Query）

# 返回结果

# 3.9 分页查询剧集详情

# 请求参数（Query）

# 返回结果

# 3.10 小说剧授权接口

# 请求参数（Body）

# 3.11 小说剧取消授权接口

# 请求参数（Body）

# 3.12 查询小说剧授权列表接口

# 请求参数（Query）

# 4 错误码

# 4.1 通用错误码

# 4.2 10000200--INVALID_REQUEST

# 剧基础信息校验

# 人员信息校验

# 集信息校验

# 视频时长校验

# 备案校验

# 追加集数校验

# 上下线校验

# 图片上传校验

# 4.3 小说剧内容错误码

# 4.4 视频相关错误码

# 5 FAQ（持续更新）

线上测试数据：所有测试剧集，剧名必须是使用【测试xxx功能（通过/不通过）01】来标记，不然可能不会及时处理。（xxx=功能名；通过/不通过=希望平台操作结果）