贡献指南

欢迎来到 Mikufans-API-collect 项目！本文档旨在为希望参与贡献的开发者提供清晰的指引。请在参与前仔细阅读。

概述

Mikufans-API-collect（简称 MAC）是一个专注于收集和整理 Mikufans（后哔哩哔哩）公开接口的开源文档项目。项目遵循 CC-BY-NC-SA 4.0 协议，纯粹用于学习、研究和社区交流。

文档使用 Markdown 编写，按业务和功能分类存放。我们欢迎通过 Issue、Pull Request 或 Discussion 来提交新的接口或修正现有内容。

收集的接口类型包括但不限于：REST API、gRPC、WebSocket。文档中统一优先使用安全协议（如 https）。

问题与讨论

Issue

若发现文档内容存在错误、缺失，或对内容有疑问，建议通过 Issue 提交。请遵循以下规范：

  1. 标题：明确说明意图，如 [新增] 新增 xx 接口、[修复] xx 接口地址已失效。避免使用“补充”、“修复”等模糊词语。
  2. 内容：请按提供的 Issue 模板填写。需注明接口来源（Web/Android/iOS/TV 等）、类型及地址。
  3. 详情：清晰描述接口的使用场景、请求/响应字段。若为更新，请指出原文档不符之处，并附上相关依据（如抓包记录）。

示例：

  • 好标题：[更新请求] video/view 接口的 aid参数已改为bvid``
  • 差标题：文档有错、补充内容

Discussion

适用于提出问题、分享用例或进行技术探讨。

  1. 标题：简明扼要，如 如何通过 xx 接口获取 yy、关于 xx 字段含义的讨论。
  2. 正文：详细描述问题或观点，提供上下文信息。
  3. 提问时，请体现 提问的智慧，并尽量别像弱智一样提问。

示例：

  • 好标题：关于获取用户投稿视频列表的接口调用问题
  • 差标题：求个投稿接口、怎么抓包

重要

出于某些考量，项目目前不提供公开的社群渠道（如 QQ 群、微信群、Telegram 群），所有交流请在 GitHub Issue 进行。

禁止内容

严禁在 Issue 或讨论中涉及以下内容：

  • 破解、解除风控
  • 爬虫采集、漏洞利用
  • 账号/代码交易
  • 任何形式的黑产行为

文档结构

目录

项目目录通过 README.md 中的 Markdown 无序列表定义，使用缩进表示层级关系。请使用复选框 [ ] 或 [x] 标记文档完成状态。

示例：

- [ ] 视频
  - [x] 基本信息
  - [x] 快照
  - [x] 视频推荐
  - [ ] TAG
  - [ ] 弹幕
    - [x] 发送与获取
    - [ ] 高级弹幕

路径与文件

  • 路径：存放于 /docs 下，使用英文小写命名（如 video, danmaku），避免特殊字符。
  • 文件：每个接口集保存为 .md 文件，同样使用英文小写命名（如 info.md）。

示例结构：

/docs
├── video/
│   ├── README.md      # （可选）视频分类的概述
│   ├── info.md        # 视频基本信息接口
│   └── action.md      # 视频操作接口（点赞、投币等）
└── user/
    ├── info.md        # 用户信息接口
    └── relation.md    # 用户关系接口

文档编写规范

文档基于 VuePress 生成，支持其 Markdown 扩展语法。

文档头部

  • 首行为一级标题（# 标题）。
  • 无需手动编写目录，VuePress 会自动生成。

示例：

# 视频基本信息

接口说明

每个接口应包含以下部分，依次排列：

  1. 标题：使用二级或以下标题。
  2. 地址：使用 > 块引用语法，仅保留路径。
  3. 请求方法：使用 斜体 标注，如 *GET*。
  4. 认证与说明：注明所需的认证方式（如 Cookie、APP）及其他注意事项。
  5. 请求参数：使用表格列出，表头为：参数名、类型、内容、必要性、备注。
  6. 响应正文：注明格式（如 JSON 回复），同样使用表格描述数据结构。
  7. 示例：包含请求示例（如 cURL）和响应示例（折叠展示）。敏感信息需脱敏。

完整示例：

## 获取视频详细信息_web端

> https://api.bilibili.com/x/web-interface/view

*请求方法：GET*

认证方式：Cookie (SESSDATA)

限制游客访问的视频需要登录

**请求参数：**

URL 参数 (application/x-www-form-urlencoded)：

| 参数名 | 类型 | 内容      | 必要性      | 备注              |
| ------ | ---- | --------- | ----------- | ----------------- |
| aid    | num  | 稿件 avid | 必要 (可选) | avid 与 bvid 任选 |
| bvid   | str  | 稿件 bvid | 必要 (可选) | avid 与 bvid 任选 |

**响应正文：**

`JSON` 回复：

`data` 对象：

| 字段     | 类型 | 内容        | 备注         |
| -------- | ---- | ----------- | ------------ |
| bvid     | str  | 稿件 bvid   |              |
| aid      | num  | 稿件 avid   |              |
| videos   | num  | 稿件分P总数 | 默认为 1     |
| tid      | num  | 分区 tid    |              |
| no_cache | bool | （？）      | 作用尚不明确 |

`data` 中的 `pages` 数组：

| 项   | 类型 | 内容            | 备注          |
| ---- | ---- | --------------- | ------------- |
| 0    | obj  | 1P 视频内容     | 无分P仅有此项 |
| n    | obj  | (n+1)P 视频内容 |               |
| ……   | obj  | ……              | ……            |

**示例：**

获取视频 `av412935552` 的基本信息

```shell
curl -G 'https://api.bilibili.com/x/web-interface/view' \
  --data-urlencode 'aid=412935552' \
  -H 'Cookie: SESSDATA=xxx'
查看响应示例：
{
  "code": 0,
  "message": "0",
  "ttl": 1,
  "data": {
    "bvid": "BV1FV411d7u7",
    "aid": 412935552,
    "videos": 3,
    "tid": 21,
    "tname": "日常",
    "copyright": 1,
    // ... 其他字段已省略
  }
}
```

枚举值与位字段

若接口涉及枚举或二进制位字段，应单独用表格说明，表头为：值/位、含义、备注。

示例：

**视频清晰度 `qn` 枚举值：**

| 值   | 含义          | 备注                                                         |
| ---- | ------------- | ------------------------------------------------------------ |
| 6    | 240P 极速     | 仅 MP4 格式支持<br />仅 `platform=html5` 时有效              |
| 16   | 360P 流畅     |                                                              |
| 32   | 480P 清晰     |                                                              |
| 64   | 720P 高清     | WEB 端默认值                                                 |
| 80   | 1080P 高清    | 需要登录认证                                                 |

Proto 文件规范

Protocol Buffers 定义文件存放于 /grpc_api，按包名组织路径。文件内使用单行注释说明字段含义。

示例：

/grpc_api/bilibili/app/view/v1/view.proto
// 视频视图信息
message ViewReply {
  // 稿件基本信息
  Arc arc = 1;
  // 分P列表
  repeated Page pages = 2;
}

// 稿件信息
message Arc {
  int64 aid = 1; // 稿件 avid
  string bvid = 2; // 稿件 bvid
  string title = 3; // 视频标题
}

提交流程

本地操作

  1. Fork 本仓库。
  2. 在您的 Fork 上进行修改。
  3. 提交时，请遵循 约定式提交规范。

提交示例：

  • feat(video): 新增视频快照接口
  • fix(user): 更正用户信息接口的响应字段
  • docs: 更新贡献指南

发起 Pull Request

  1. 向 master 分支发起 PR，标题需清晰描述变更内容。
  2. 若修改未完成，可创建 Draft PR。
  3. PR 描述中请使用列表说明具体更改，并可关联关闭的 Issue（如 close #123）。

PR 描述示例：

## 变更内容
- [x] 新增 `/video/snapshot` 接口文档
- [x] 修复 `/user/info` 接口中 `mid` 字段类型的错误描述
- [ ] （待办）补充 `/video/tag` 接口示例

关联问题：close #456

感谢您的贡献！