API 参考

目标：说明 danmu_api 常用接口怎么调用、参数怎么填、返回字段怎么看。

如果只是给 Emby、UZ、FongMi 填地址，先看播放器接入。这里用于查询接口路径、请求参数和返回结构。

基础地址和 TOKEN

API 基础地址只写到域名这一层：

https://你的域名

如果自定义了 TOKEN，基础地址写成：

https://你的域名/你的TOKEN

下面每个接口都只写相对路径。使用时，把接口路径接到基础地址后面。

本地、Docker、Termux 部署时，把 https://你的域名 换成自己的服务地址，例如：

http://服务器IP:9321
http://服务器IP:9321/你的TOKEN

FongMi 影视比较特殊，要在基础地址后面加 /danmaku：

https://你的域名/danmaku
https://你的域名/你的TOKEN/danmaku

管理员入口是：

https://你的域名/你的ADMIN_TOKEN

如果要直接访问后台接口，再在后面接 /api/config、/api/reqrecords 这类路径。

公开部署时不要继续使用默认 TOKEN，也不要把 ADMIN_TOKEN、Cookie、平台 Token 写进公开截图或 Issue。

快速检查 4 个接口

1. 看服务是否正常

GET /api/config

正常会返回项目版本、配置预览和仓库地址。敏感值会被脱敏。

{
  "message": "Welcome to the LogVar Danmu API server",
  "version": "1.19.4",
  "hasAdminToken": true,
  "repository": "https://github.com/huangxd-/danmu_api.git",
  "envs": {
    "TOKEN": "********",
    "ADMIN_TOKEN": "****************",
    "SOURCE_ORDER": ["360", "vod", "renren", "hanjutv"]
  }
}

2. 搜作品

GET /api/v2/search/anime?keyword=凡人修仙传

3. 看作品分集

先从搜索结果里拿 animeId，再请求：

GET /api/v2/bangumi/236216

4. 拉某一集弹幕

从作品详情的 episodes[].episodeId 拿弹幕 ID：

GET /api/v2/comment/10177?format=json&duration=true

搜索作品

搜索结果、弹幕数量、来源顺序会受 SOURCE_ORDER、源站可用性和缓存影响。
返回示例里的作品、集数、弹幕数量只是示例，实际结果以自己的服务返回为准。

GET /api/v2/search/anime?keyword={关键词}

参数：

keyword：必填。作品名，也可以传部分支持平台的视频链接。

返回示例：

{
  "errorCode": 0,
  "success": true,
  "errorMessage": "",
  "animes": [
    {
      "animeId": 236216,
      "bangumiId": "236216",
      "animeTitle": "凡人修仙传(2025)【电视剧】from 360",
      "type": "电视剧",
      "typeDescription": "电视剧",
      "imageUrl": "https://p.ssl.qhimg.com/d/dy_b5720ea4086d830ae11acb97bf6fff98.jpg",
      "startDate": "2025-01-01T00:00:00Z",
      "episodeCount": 30,
      "rating": 0,
      "isFavorited": true,
      "source": "360"
    }
  ]
}

说明：

animes 是候选作品列表，不保证只有一个。
animeId 用来请求 /api/v2/bangumi/{animeId}。
source 表示这个候选来自哪个来源，例如 360、vod、renren、hanjutv。
空关键词会返回成功，但 animes 是空数组。

空关键词返回：

{
  "errorCode": 0,
  "success": true,
  "errorMessage": "",
  "animes": []
}

搜索作品分集

GET /api/v2/search/episodes?anime={作品名}
GET /api/v2/search/episodes?anime={作品名}&episode={集数}

参数：

anime：必填，作品名。
episode：选填。
不填：返回匹配作品的全部分集。
纯数字：只返回对应集数，例如 episode=1。
movie：只保留电影 / 剧场版结果。

返回示例：

{
  "errorCode": 0,
  "success": true,
  "errorMessage": "",
  "animes": [
    {
      "animeId": 236216,
      "animeTitle": "凡人修仙传(2025)【电视剧】from 360",
      "type": "电视剧",
      "typeDescription": "电视剧",
      "episodes": [
        {
          "episodeId": 10177,
          "episodeTitle": "【youku】 第1集"
        }
      ]
    }
  ]
}

缺少 anime 时返回：

{
  "errorCode": 400,
  "success": false,
  "errorMessage": "Missing anime parameter"
}

自动匹配文件名

POST /api/v2/match
Content-Type: application/json

{
  "fileName": "凡人修仙传 S01E01 1080p"
}

请求体：

fileName：必填。文件名、标题、网盘资源名都可以。服务会尝试解析标题、季、集、年份和平台偏好。
支持在文件名里用 @平台 指定优先平台，例如 凡人修仙传 S01E01 @youku。

返回示例：

{
  "errorCode": 0,
  "success": true,
  "errorMessage": "",
  "isMatched": true,
  "matches": [
    {
      "episodeId": 10177,
      "animeId": 236216,
      "animeTitle": "凡人修仙传(2025)【电视剧】from 360",
      "episodeTitle": "【youku】 第1集",
      "type": "电视剧",
      "typeDescription": "电视剧",
      "shift": 0,
      "imageUrl": "https://p.ssl.qhimg.com/d/dy_b5720ea4086d830ae11acb97bf6fff98.jpg"
    }
  ]
}

常见错误：

{
  "errorCode": 400,
  "success": false,
  "errorMessage": "Missing fileName parameter"
}

获取作品详情

GET /api/v2/bangumi/{animeId}

路径参数：

animeId：从搜索结果 animes[].animeId 获取。

返回示例：

{
  "errorCode": 0,
  "success": true,
  "errorMessage": "",
  "bangumi": {
    "animeId": 236216,
    "bangumiId": "236216",
    "animeTitle": "凡人修仙传(2025)【电视剧】from 360",
    "imageUrl": "https://p.ssl.qhimg.com/d/dy_b5720ea4086d830ae11acb97bf6fff98.jpg",
    "isOnAir": true,
    "airDay": 1,
    "isFavorited": true,
    "rating": 0,
    "type": "电视剧",
    "typeDescription": "电视剧",
    "seasons": [
      {
        "id": "season-236216",
        "airDate": "2025-01-01T00:00:00Z",
        "name": "Season 1",
        "episodeCount": 30
      }
    ],
    "episodes": [
      {
        "seasonId": "season-236216",
        "episodeId": 10177,
        "episodeTitle": "【youku】 第1集",
        "episodeNumber": "1",
        "airDate": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

找不到这个 animeId 时返回：

{
  "errorCode": 404,
  "success": false,
  "errorMessage": "Anime not found",
  "bangumi": null
}

获取弹幕

通过 episodeId 获取弹幕

GET /api/v2/comment/{episodeId}
GET /api/v2/comment/{episodeId}?format=json&duration=true
GET /api/v2/comment/{episodeId}?format=xml

路径参数：

episodeId：从 /api/v2/bangumi/{animeId} 的 bangumi.episodes[].episodeId 获取。

查询参数：

format：选填，json 或 xml。不填时使用环境变量 DANMU_OUTPUT_FORMAT，默认 json。
duration：选填，true / 1 时 JSON 返回体会额外带 videoDuration。
segmentflag：选填，true / 1 时请求源站分片信息。这个能力依赖具体来源，普通用户一般不用。

JSON 返回结构：

{
  "videoDuration": 3058,
  "count": 17377,
  "comments": [
    {
      "cid": 1,
      "p": "0.00,1,16777215,[youku]",
      "m": "弹幕大军在哪里 x 2",
      "t": 0,
      "like": 1
    },
    {
      "cid": 2,
      "p": "0.00,1,15448691,[youku]",
      "m": "我睡了",
      "t": 0,
      "like": 0
    }
  ]
}

字段说明：

count：返回弹幕条数。
comments[].p：弹幕属性，JSON 格式里常见为 时间,类型,颜色,[来源]。
comments[].m：弹幕正文。
comments[].t：弹幕秒数。
comments[].like：来源提供的点赞数或处理后的点赞参考值，可能为 0 或不存在。
videoDuration：只有请求 duration=true 且返回 JSON 时才会带；拿不到时可能是 0。

XML 返回结构：

<?xml version="1.0" ?>
<i>
    <d p="0.0,1,25,16777215,1751533608,0,0,03089103421">弹幕大军在哪里 x 2</d>
    <d p="0.0,1,25,15448691,1751533608,0,0,03089103528">我睡了</d>
</i>

XML 的 p 会转成 Bilibili 常见 8 字段格式：

时间,类型,字体大小,颜色,时间戳,弹幕池,用户Hash,弹幕ID

找不到 episodeId 时返回：

{
  "count": 0,
  "comments": []
}

通过视频 URL 获取弹幕

GET /api/v2/comment?url={视频URL}&format=json
GET /api/v2/extcomment?url={视频URL}&format=json

参数：

url：必填，视频链接。
format：选填，json 或 xml。
segmentflag：选填，是否按分片模式请求。
duration：选填，是否在 JSON 里附带 videoDuration。

缺少 url 时返回：

{
  "errorCode": 400,
  "success": false,
  "errorMessage": "Missing commentId or url parameter"
}

分片弹幕接口

POST /api/v2/segmentcomment?format=json
Content-Type: application/json

{
  "type": "qq",
  "segment_start": 0,
  "segment_end": 30000,
  "url": "https://..."
}

请求体来自支持分片的来源返回结果。常见字段：

type：来源类型，例如 qq、bahamut、hanjutv。
segment_start：分片开始时间。
segment_end：分片结束时间。
url：该分片的真实请求地址或来源 ID。
data、_m_h5_tk、_m_h5_tk_enc：部分来源需要的附加字段。

这个接口主要给客户端或调试使用，普通接入优先用 /api/v2/comment/{episodeId}。

FongMi 影视接口

FongMi 影视一般只需要填写短地址：

https://你的域名/danmaku

自定义 TOKEN 时填写：

https://你的域名/你的TOKEN/danmaku

接口支持 GET 和 POST。

GET 写法

GET /danmaku?name={片名}&episode={集数}
GET /api/v2/fongmi/danmaku?name={片名}&episode={集数}

POST JSON 写法

POST /danmaku
Content-Type: application/json

{
  "name": "凡人修仙传",
  "episode": "第1集"
}

也兼容表单提交：

POST /danmaku
Content-Type: application/x-www-form-urlencoded

name=凡人修仙传&episode=第1集

参数：

name：必填，片名。
episode：选填，集数、集标题或文件名里的集数片段。

返回示例是数组，最多返回 12 个候选：

[
  {
    "name": "凡人修仙传(2025)【电视剧】from 360 - 【youku】 第1集",
    "url": "https://你的域名/api/v2/comment/10177?format=xml"
  },
  {
    "name": "凡人修仙传(2020)【动漫】from 360 - 【bilibili1】 第1集",
    "url": "https://你的域名/api/v2/comment/10002?format=xml"
  }
]

说明：

url 默认指向 XML 弹幕接口，适合 FongMi 继续拉取。
如果请求路径带了自定义 TOKEN，返回的 url 也会保留这个 TOKEN 前缀。
没传 name 或没有搜索到候选时，返回空数组 []。
兼容一些客户端把短地址和完整路径重复拼接成 /danmaku/api/v2/fongmi/danmaku 的情况，服务端会折叠回 /danmaku 处理。

系统和后台接口

这些接口主要给项目自带后台使用。公开部署时建议使用 ADMIN_TOKEN 路径前缀访问。

配置预览

GET /api/config
GET /你的ADMIN_TOKEN/api/config

返回结构很大，核心字段如下：

{
  "message": "Welcome to the LogVar Danmu API server",
  "version": "1.19.4",
  "envs": {
    "TOKEN": "********",
    "ADMIN_TOKEN": "****************"
  },
  "categorizedEnvVars": {
    "api": [],
    "source": [],
    "match": [],
    "danmu": [],
    "cache": [],
    "system": []
  },
  "envVarConfig": {},
  "originalEnvVars": {},
  "hasAdminToken": true,
  "repository": "https://github.com/huangxd-/danmu_api.git"
}

请求记录

GET /api/reqrecords
GET /你的ADMIN_TOKEN/api/reqrecords

返回最近的 API 请求记录，IP 会按权限脱敏：

{
  "records": [
    {
      "interface": "/api/v2/search/anime?keyword=凡人修仙传",
      "params": null,
      "timestamp": "2026-05-12T16:24:27.791Z",
      "method": "GET",
      "clientIp": "***.*.*.*"
    }
  ],
  "todayReqNum": 10
}

日志

GET /api/logs
POST /api/logs/clear

GET /api/logs 返回纯文本日志：

[2026-05-13T00:21:36.113+08:00] info: request url: "http://127.0.0.1:19321/api/config"
[2026-05-13T00:21:36.115+08:00] info: request path: /api/config
[2026-05-13T00:21:36.115+08:00] info: client ip: ***.*.*.*

POST /api/logs/clear 返回：

{
  "success": true,
  "message": "Logs cleared"
}

清理缓存

POST /api/cache/clear

返回：

{
  "success": true,
  "message": "Cache cleared successfully",
  "clearedItems": {
    "animes": 0,
    "episodeIds": 0,
    "episodeNum": 10001,
    "lastSelectMap": 0,
    "searchCache": 0,
    "commentCache": 0,
    "requestHistory": 0,
    "reqRecords": 0,
    "todayReqNum": 0
  }
}

触发重新部署

POST /api/deploy

本地 Node / Docker 部署通常不需要重新部署，返回类似：

{
  "success": true,
  "message": "Node/Docker deployment - configuration changes take effect automatically"
}

云平台会按 DEPLOY_PLATFROM_* 变量调用对应平台重新部署。

环境变量写入接口

这些接口是后台 系统配置 保存变量时用的。普通用户建议走网页后台，不要手写请求。

设置变量

POST /api/env/set
Content-Type: application/json

{
  "key": "TOKEN",
  "value": "新的TOKEN"
}

成功返回：

{
  "success": true,
  "message": "环境变量 TOKEN 设置成功"
}

添加变量

POST /api/env/add
Content-Type: application/json

{
  "key": "SOURCE_ORDER",
  "value": "360,vod,renren,hanjutv"
}

删除变量

POST /api/env/del
Content-Type: application/json

{
  "key": "DEBUG"
}

缺少 key 时会返回：

{
  "success": false,
  "message": "缺少环境变量名称"
}

这些接口用于后台管理 Bilibili Cookie。

查看 Cookie 状态

GET /api/cookie/status

未配置 Cookie 时返回：

{
  "success": true,
  "data": {
    "isValid": false,
    "checked": "saved",
    "error": "未配置Cookie"
  }
}

生成登录二维码

POST /api/cookie/qr/generate

返回二维码登录需要的 oauthKey、二维码链接等字段，具体字段会随 Bilibili 接口返回变化。

检查扫码状态

POST /api/cookie/qr/check
Content-Type: application/json

{
  "oauthKey": "二维码接口返回的 oauthKey"
}

验证 Cookie

POST /api/cookie/verify
Content-Type: application/json

{
  "cookie": "SESSDATA=...; bili_jct=..."
}

保存 Cookie

POST /api/cookie/save
Content-Type: application/json

{
  "cookie": "SESSDATA=...; bili_jct=..."
}

不要把真实 Cookie 写进公开文档、截图或日志。

AI 连通性测试接口

POST /api/ai/verify
Content-Type: application/json

{
  "aiBaseUrl": "https://api.openai.com/v1",
  "aiModel": "gpt-4o",
  "aiApiKey": "sk-..."
}

没有传 aiApiKey，并且服务端也没有配置 AI_API_KEY 时返回：

{
  "success": false,
  "ok": false,
  "message": "AI_API_KEY 未配置"
}

连通成功时返回：

{
  "success": true,
  "ok": true,
  "message": "AI 服务连通性测试成功"
}

连通失败但请求本身处理成功时，可能返回 HTTP 200，正文里 success=false、ok=false，并带失败原因。

路径兼容规则

正常对接请使用标准路径：

/api/v2/search/anime
/api/v2/match
/api/v2/search/episodes
/api/v2/bangumi/{animeId}
/api/v2/comment/{episodeId}
/danmaku

服务端也会兼容部分缺前缀或重复前缀的写法，例如：

/search/anime 会补成 /api/v2/search/anime
/v2/search/anime 会补成 /api/v2/search/anime
/api/search/anime 会补成 /api/v2/search/anime
/api/v2/api/v2/search/anime 会清理成 /api/v2/search/anime

文档和播放器配置里不要依赖这些兼容写法，统一写标准路径更稳。

常见状态码

200：请求成功。业务失败也可能用 200 返回，例如 AI 连通失败会看正文 ok=false。
204：空响应，常见于 favicon.ico、robots.txt、OPTIONS。
400：请求参数或 JSON 请求体不对。
401：TOKEN 缺失或错误。自定义 TOKEN 后最常见原因是忘了把 TOKEN 放进路径第一段。
403：命中 IP 黑名单。
404：接口不存在，或指定的作品 / 弹幕 ID 当前缓存里找不到。
429：同 IP 弹幕请求触发限流。
500：服务端处理异常，先看 /api/logs 或部署平台日志。

API 参考

基础地址和 TOKEN

快速检查 4 个接口

1. 看服务是否正常

2. 搜作品

3. 看作品分集

4. 拉某一集弹幕

搜索作品

搜索作品分集

自动匹配文件名

获取作品详情

获取弹幕

通过 episodeId 获取弹幕

通过视频 URL 获取弹幕

分片弹幕接口

FongMi 影视接口

GET 写法

POST JSON 写法

系统和后台接口

配置预览

请求记录

日志

清理缓存

触发重新部署

环境变量写入接口

设置变量

添加变量

删除变量

Cookie 管理接口

查看 Cookie 状态

生成登录二维码

检查扫码状态

验证 Cookie

保存 Cookie

AI 连通性测试接口

路径兼容规则

常见状态码