面向最终用户的完整接口说明

DramaBox 短剧 API

专业的 DramaBox 短剧 API，提供多语言搜索、榜单推荐、短剧详情、完整剧集、加密 MP4 解析以及 UID 查询 Token。

API 基址当前站点

接口版本/api/v1

鉴权方式无需鉴权，公开调用

数据格式application/json; charset=utf-8

直接可用：GET 接口使用查询参数，不把资源 ID 写进路径。例如 /api/v1/dramas/episodes?book_id=41000101035&raw=false。剧集默认返回全部真实画质，冷缓存并发加载，后续请求直接命中缓存。

01 · 开始使用

一分钟完成第一次调用

所有业务接口均直接对外开放。将参数放在 URL 的 ? 后即可调用；不要附加 API Key、登录 Cookie 或签名。

GET当前站点/api/v1/dramas/search?name=%E6%80%BB%E8%A3%81&kind=drama&lang=id打开 ↗

curl "{{API_BASE}}/api/v1/dramas/search?name=%E6%80%BB%E8%A3%81&kind=drama&lang=id"

const response = await fetch("{{API_BASE}}/api/v1/dramas/search?name=%E6%80%BB%E8%A3%81&kind=drama&lang=id");
const result = await response.json();

<?php
$json = file_get_contents('{{API_BASE}}/api/v1/dramas/search?name='.rawurlencode('总裁').'&kind=drama&lang=id');
$result = json_decode($json, true, 512, JSON_THROW_ON_ERROR);

import requests
result = requests.get("{{API_BASE}}/api/v1/dramas/search", params={"name": "总裁", "kind": "drama", "lang": "id"}, timeout=30).json()

resp, err := http.Get("{{API_BASE}}/api/v1/dramas/search?name=" + url.QueryEscape("总裁") + "&kind=drama&lang=id")
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

02 · 多语言

搜索与内容语言代码

lang 只用于搜索接口，默认值为 id（印度尼西亚语）。其他接口没有语言参数。

en英语

ja日语

ko韩语

es西班牙语

id / in印度尼西亚语（默认）

fr法语

pt葡萄牙语

th泰语

ar阿拉伯语

de德语

pl波兰语

vi越南语

it意大利语

tr土耳其语

zh / zh_tw繁体中文

zhHans / zh_cn简体中文

注意：zh 按需求代表繁体中文；简体中文请明确传 zhHans 或 zh_cn。

03 · 通用规范

统一 JSON 响应

除视频流接口外，成功和失败都返回 UTF-8 JSON。请先判断 HTTP 状态码或 code，再读取 data。

成功

{
  "code": "OK",
  "message": "success",
  "data": [],
  "request_id": "4d6f...",
  "meta": { "cache": "miss" }
}

失败

{
  "code": "VALIDATION_ERROR",
  "message": "请求参数不正确",
  "error": { "field": "lang", "reason": "不支持的语言" },
  "request_id": "4d6f..."
}

字段	类型	说明
code	string	`OK` 表示成功；其他值均为可编程处理的错误码。
message	string	适合直接阅读的中文结果说明。
data	array / object	业务数据；失败时通常不存在。
request_id	string	请求追踪编号，报障时请一并提供。
meta.cache	string	`hit`、`miss` 或 `stale`；Token/状态接口没有该字段。

错误参考

HTTP 状态与错误码

HTTP	错误码	含义	处理建议
400	VALIDATION_ERROR	查询参数或字段格式不正确	根据 `error.field` 和 `error.reason` 修正。
400	INVALID_JSON	POST 请求体不是有效 JSON	使用对象、UTF-8 和 `Content-Type: application/json`。
400	VIDEO_URL_INVALID	域名不允许、URL 无效或媒体不可访问	使用剧集结果中仍有效的 DramaBox MP4 URL。
401	TOKEN_INVALID	Token 无效或不属于当前 Token 池	检查是否完整复制，或重新按 UID 查询。
404	TOKEN_NOT_FOUND	Token 池没有该 UID	可调用 bootstrap 获取由 DramaBox 分配的新 UID。
404	VIDEO_NOT_FOUND	没有找到指定分集	检查 video_id 是否属于当前 book_id。
404	ROUTE_NOT_FOUND	路径或请求方法不正确	对照本文档检查路径、方法和查询参数。
416	RANGE_NOT_SATISFIABLE	视频字节范围格式错误或越界	只发送单段 `Range: bytes=start-end`。
502	DRAMABOX_ERROR / SERVICE_ERROR	DramaBox 上游或视频处理失败	稍后重试，并记录 `request_id`。
504	DRAMABOX_TIMEOUT / REQUEST_TIMEOUT	上游或整个请求超时	整剧集可适当延长客户端超时，避免立即并发重试。
500	INTERNAL_ERROR	服务端未预期错误	将 `request_id` 提交给管理员。

上线前必读

调用、视频与反向代理须知

搜索和三个排行榜没有 page 参数；for-you、random 和 dubbed 的 page 会真实传给数据源。
完整剧集会按 5 集一批拉取并处理付费章节，通常比列表接口慢；客户端建议设置 90–180 秒超时。
PHP 视频流使用磁盘缓存分块下载与就地解密；相同 URL 通过文件锁合并并发处理，并支持 Range/206 播放和拖动进度。
UID → Token 只查询当前内置 Token 池；不存在记录时返回 TOKEN_NOT_FOUND，不会返回伪造 Token。
生产环境建议使用 systemd 启动 Go 服务，再由 Nginx/宝塔反向代理；应保留 Host、X-Forwarded-For、X-Forwarded-Proto 和请求超时设置。
文档和在线调试会自动识别当前访问地址及二级目录；只有加密视频才返回 proxy_url 和 tips，普通视频直接使用 video_url。