bilibili-API-collect/video/snapshot.md

# 视频快照

快照的截取时间根据视频画面变化程度决定，各视频不相同

截取时间表的时间根据视频画面变化程度决定，各每个视频不相同

截取时间表的时间和快照一一对应，并按照从左到右 从上到下的顺序排布

## 获取视频快照（web端）
> http://api.bilibili.com/x/player/videoshot

*请求方式：GET* 

**url参数：**

| 参数名 | 类型 | 内容               | 必要性       | 备注                                |
| ------ | ---- | ------------------ | ------------ | ----------------------------------- |
| aid    | num  | 稿件avID           | 必要（可选） | avID与bvID任选一个                  |
| bvid   | str  | 稿件bvID           | 必要（可选） | avID与bvID任选一个                  |
| cid    | num  | 分P CID            | 非必要       | 默认为1P                            |
| index  | num  | json数组截取时间表 | 非必要       | 1：需要<br />0：不需要<br />默认为0 |

**json回复：**

根对象：

| 字段    | 类型 | 内容     | 备注                                             |
| ------- | ---- | -------- | ------------------------------------------------ |
| code    | num  | 返回值   | 0：成功 <br />40001：请求错误<br />40003：无视频 |
| message | str  | 错误信息 | 默认为0                                          |
| ttl     | num  | 1        |                                                  |
| data    | obj  | 信息本体 |                                                  |

`data`对象：

| 字段       | 类型  | 内容                   | 备注      |
| ---------- | ----- | ---------------------- | --------- |
| pvdata     | str   | bin格式截取时间表url   |           |
| img_x_len  | num   | 每行图片数             | 一般为10  |
| img_y_len  | num   | 每列图片数             | 一般为10  |
| img_x_size | num   | 每张图片长             | 一般为160 |
| img_y_size | num   | 每张图片宽             | 一般为90  |
| image      | array | 图片拼版               |           |
| index      | array | json数组格式截取时间表 | 无为空    |

`data`中的`image`数组：

| 项   | 类型 | 内容              | 备注                       |
| ---- | ---- | ----------------- | -------------------------- |
| 0    | str  | 图片拼版1 url     |                            |
| n    | str  | 图片拼版(n+1) url | 第一张拼版占满时延续第二张 |
| ……   | str  | ……                | ……                         |

`data`中的`index`数组：

| 项   | 类型 | 内容            | 备注            |
| ---- | ---- | --------------- | --------------- |
| 0    | num  | 恒为0           |                 |
| 1    | num  | 图片1 截取时间  | 视频0秒截取时间 |
| n    | num  | 图片n  截取时间 | 单位为秒        |
| ……   | num  | ……              | 单位为秒        |

**示例：**

获取视频`av26273789`/`BV1os411H7wm`的快照

avID方式：

```shell
curl -G 'http://api.bilibili.com/x/player/videoshot' \
--data-urlencode 'aid=26273789' \
--data-urlencode 'index=1'
```

bvID方式：

```shell
curl -G 'http://api.bilibili.com/x/player/videoshot' \
--data-urlencode 'bvid=BV1os411H7wm' \
--data-urlencode 'index=1'
```

<details>
<summary>查看响应示例：</summary>

```json
{
	"code": 0,
	"message": "0",
	"ttl": 1,
	"data": {
		"pvdata": "//i0.hdslb.com/bfs/videoshot/49075258.bin",
		"img_x_len": 10,
		"img_y_len": 10,
		"img_x_size": 160,
		"img_y_size": 90,
		"image": ["//i0.hdslb.com/bfs/videoshot/49075258.jpg", "//i0.hdslb.com/bfs/videoshot/49075258-1.jpg"],
		"index": [0, 0, 8, 14, 19, 25, 34, 40, 46, 56, 63, 70, 80, 87, 93, 100, 109, 117, 124, 133, 142, 148, 156, 164, 171, 179, 184, 192, 198, 206, 214, 223, 232, 239, 246, 254, 261, 269, 275, 283, 289, 299, 305, 310, 315, 322, 330, 339, 348, 358, 364, 371, 376, 382, 391, 404, 413, 421, 426, 434, 441, 452, 458, 463, 473, 479, 491, 497, 504, 514, 521, 528, 533, 540, 546, 552, 558, 567, 575, 586, 591, 602, 609, 615, 623, 629, 639, 647, 653, 658, 664, 670, 675, 684, 691, 698, 713, 724, 729, 737, 743, 754, 762, 772, 779, 784, 797, 803, 810, 817, 825, 834, 845, 851, 857, 867, 878, 888, 896, 903, 909, 914, 919, 928, 935, 944, 958, 970, 977, 988, 996, 1004, 1011, 1018, 1026, 1035, 1041, 1048, 1055, 1063, 1073, 1079, 1086, 1095, 1106, 1111, 1124, 1135, 1147, 1153, 1159, 1165, 1171, 1184, 1198, 1209, 1215, 1221, 1228, 1236, 1242, 1253, 1258, 1269, 1276, 1284, 1289, 1300, 1306, 1315, 1321, 1328, 1340, 1347, 1354, 1361, 1366, 1371, 1383, 1390, 1396, 1403, 1415]
	}
}
```

</details>

## 获取视频快照（APP端）

> http://app.bilibili.com/x/v2/view/video/shot 

*请求方式：GET*

鉴权方式：appkey

**url参数：**

| 参数名 | 类型 | 内容       | 必要性      | 备注 |
| ------ | ---- | ---------- | ----------- | ---- |
| appkey | str  | APP密钥    | APP方式必要 |      |
| aid    | num  | 稿件avID   | 必要        |      |
| cid    | num  | 分P CID    | 必要        |      |
| ts     | num  | 当前时间戳 | APP方式必要 |      |
| sign   | str  | APP签名    | APP方式必要 |      |

**json回复：**

根对象：

| 字段    | 类型 | 内容     | 备注                                                         |
| ------- | ---- | -------- | ------------------------------------------------------------ |
| code    | num  | 返回值   | 0：成功 <br />-3：API校验密匙错误<br />-400：请求错误<br />10008：稿件的缩略图不存在 |
| message | str  | 错误信息 | 默认为0                                                      |
| ttl     | num  | 1        |                                                              |
| data    | obj  | 信息本体 |                                                              |

`data`对象：

| 字段       | 类型  | 内容                 | 备注      |
| ---------- | ----- | -------------------- | --------- |
| pvdata     | str   | bin格式截取时间表url |           |
| img_x_len  | num   | 每行图片数           | 一般为10  |
| img_y_len  | num   | 每列图片数           | 一般为10  |
| img_x_size | num   | 每张图片长           | 一般为160 |
| img_y_size | num   | 每张图片宽           | 一般为90  |
| image      | array | 图片拼版             |           |

`data`中的`image`数组：

| 项   | 类型 | 内容              | 备注                       |
| ---- | ---- | ----------------- | -------------------------- |
| 0    | str  | 图片拼版1 url     |                            |
| n    | str  | 图片拼版(n+1) url | 第一张拼版占满时延续第二张 |
| ……   | str  | ……                | ……                         |

示例：

获取视频`av26273789`（`CID=49075258`）的快照

```shell
curl -G 'http://app.bilibili.com/x/v2/view/video/shot' \
--data-urlencode 'appkey=1d8b6e7d45233436' \
--data-urlencode 'aid=26273789' \
--data-urlencode 'cid=49075258' \
--data-urlencode 'ts=0' \
--data-urlencode 'sign=06c0a4f2ede21984313552bd9439db18'
```

<details>
<summary>查看响应示例：</summary>

```json
{
    "code": 0,
    "message": "0",
    "ttl": 1,
    "data": {
        "pvdata": "http://i0.hdslb.com/bfs/videoshot/49075258.bin",
        "img_x_len": 10,
        "img_y_len": 10,
        "img_x_size": 160,
        "img_y_size": 90,
        "image": [
            "http://i0.hdslb.com/bfs/videoshot/49075258.jpg",
            "http://i0.hdslb.com/bfs/videoshot/49075258-1.jpg"
        ]
    }
}
```

</details>

## 获取视频快照（web端）（用于封面预览）

> http://api.bilibili.com/pvideo

*请求方式：GET*

内容与「获取视频快照1」加参数index=1相同，但url带有转义，仅限第1P

**url参数：**

| 参数名 | 类型 | 内容     | 必要性 | 备注 |
| ------ | ---- | -------- | ------ | ---- |
| aid    | num  | 稿件avID | 必要   |      |

**json回复：**

根对象：

| 字段    | 类型 | 内容     | 备注                                           |
| ------- | ---- | -------- | ---------------------------------------------- |
| code    | num  | 返回值   | 0：成功<br />40001：请求错误<br />-404：无视频 |
| message | str  | 错误信息 | 默认为0                                        |
| ttl     | num  | 1        |                                                |
| data    | obj  | 信息本体 |                                                |

`data`对象：

| 字段       | 类型  | 内容                   | 备注      |
| ---------- | ----- | ---------------------- | --------- |
| pvdata     | str   | bin格式截取时间表url   |           |
| img_x_len  | num   | 每行图片数             | 一般为10  |
| img_y_len  | num   | 每列图片数             | 一般为10  |
| img_x_size | num   | 每张图片长             | 一般为160 |
| img_y_size | num   | 每张图片宽             | 一般为90  |
| image      | array | 图片拼版               |           |
| index      | array | json数组格式截取时间表 | 无为空    |

`data`中的`image`数组：

| 项   | 类型 | 内容              | 备注                       |
| ---- | ---- | ----------------- | -------------------------- |
| 0    | str  | 图片拼版1 url     |                            |
| n    | str  | 图片拼版(n+1) url | 第一张拼版占满时延续第二张 |
| ……   | str  | ……                | ……                         |

`data`中的`index`数组：

| 项   | 类型 | 内容            | 备注            |
| ---- | ---- | --------------- | --------------- |
| 0    | num  | 恒为0           |                 |
| 1    | num  | 图片1 截取时间  | 视频0秒截取时间 |
| n    | num  | 图片n  截取时间 | 单位为秒        |
| ……   | num  | ……              | 单位为秒        |

**示例：**

获取视频`av26273789`的快照

```shell
curl -G 'http://api.bilibili.com/pvideo' \
--data-urlencode 'aid=26273789'
```

<details>
<summary>查看响应示例：</summary>

```json
{
	"code": 0,
	"message": "0",
	"ttl": 1,
	"data": {
		"pvdata": "\/\/i0.hdslb.com\/bfs\/videoshot\/49075258.bin",
		"img_x_len": 10,
		"img_y_len": 10,
		"img_x_size": 160,
		"img_y_size": 90,
		"image": ["\/\/i0.hdslb.com\/bfs\/videoshot\/49075258.jpg", "\/\/i0.hdslb.com\/bfs\/videoshot\/49075258-1.jpg"],
		"index": [0, 0, 8, 14, 19, 25, 34, 40, 46, 56, 63, 70, 80, 87, 93, 100, 109, 117, 124, 133, 142, 148, 156, 164, 171, 179, 184, 192, 198, 206, 214, 223, 232, 239, 246, 254, 261, 269, 275, 283, 289, 299, 305, 310, 315, 322, 330, 339, 348, 358, 364, 371, 376, 382, 391, 404, 413, 421, 426, 434, 441, 452, 458, 463, 473, 479, 491, 497, 504, 514, 521, 528, 533, 540, 546, 552, 558, 567, 575, 586, 591, 602, 609, 615, 623, 629, 639, 647, 653, 658, 664, 670, 675, 684, 691, 698, 713, 724, 729, 737, 743, 754, 762, 772, 779, 784, 797, 803, 810, 817, 825, 834, 845, 851, 857, 867, 878, 888, 896, 903, 909, 914, 919, 928, 935, 944, 958, 970, 977, 988, 996, 1004, 1011, 1018, 1026, 1035, 1041, 1048, 1055, 1063, 1073, 1079, 1086, 1095, 1106, 1111, 1124, 1135, 1147, 1153, 1159, 1165, 1171, 1184, 1198, 1209, 1215, 1221, 1228, 1236, 1242, 1253, 1258, 1269, 1276, 1284, 1289, 1300, 1306, 1315, 1321, 1328, 1340, 1347, 1354, 1361, 1366, 1371, 1383, 1390, 1396, 1403, 1415]
	}
}
```

</details>

## 图片拼版

以160x90像素为一张，横向10张，纵向10张，从左到右从上到下进行裁剪

图1为0s，图2为8s，图3为14s，以此类推……

示例拼版图片url：http://i0.hdslb.com/bfs/videoshot/49075258.jpg

![](http://i0.hdslb.com/bfs/videoshot/49075258.jpg)

## bin格式截取时间表

bin的内容为uint16数组（2Byte对齐），与json数组一一对应

0第项恒为0，从第1项开始作为截取图片的时间（秒）

示例bin格式截取时间表：http://i0.hdslb.com/bfs/videoshot/49075258.bin

hex内容如下：

```
00000000  00 00 00 00 00 08 00 0e  00 13 00 19 00 22 00 28  |.............".(|
00000010  00 2e 00 38 00 3f 00 46  00 50 00 57 00 5d 00 64  |...8.?.F.P.W.].d|
00000020  00 6d 00 75 00 7c 00 85  00 8e 00 94 00 9c 00 a4  |.m.u.|..........|
00000030  00 ab 00 b3 00 b8 00 c0  00 c6 00 ce 00 d6 00 df  |................|
00000040  00 e8 00 ef 00 f6 00 fe  01 05 01 0d 01 13 01 1b  |................|
00000050  01 21 01 2b 01 31 01 36  01 3b 01 42 01 4a 01 53  |.!.+.1.6.;.B.J.S|
00000060  01 5c 01 66 01 6c 01 73  01 78 01 7e 01 87 01 94  |.\.f.l.s.x.~....|
00000070  01 9d 01 a5 01 aa 01 b2  01 b9 01 c4 01 ca 01 cf  |................|
00000080  01 d9 01 df 01 eb 01 f1  01 f8 02 02 02 09 02 10  |................|
00000090  02 15 02 1c 02 22 02 28  02 2e 02 37 02 3f 02 4a  |.....".(...7.?.J|
000000a0  02 4f 02 5a 02 61 02 67  02 6f 02 75 02 7f 02 87  |.O.Z.a.g.o.u....|
000000b0  02 8d 02 92 02 98 02 9e  02 a3 02 ac 02 b3 02 ba  |................|
000000c0  02 c9 02 d4 02 d9 02 e1  02 e7 02 f2 02 fa 03 04  |................|
000000d0  03 0b 03 10 03 1d 03 23  03 2a 03 31 03 39 03 42  |.......#.*.1.9.B|
000000e0  03 4d 03 53 03 59 03 63  03 6e 03 78 03 80 03 87  |.M.S.Y.c.n.x....|
000000f0  03 8d 03 92 03 97 03 a0  03 a7 03 b0 03 be 03 ca  |................|
00000100  03 d1 03 dc 03 e4 03 ec  03 f3 03 fa 04 02 04 0b  |................|
00000110  04 11 04 18 04 1f 04 27  04 31 04 37 04 3e 04 47  |.......'.1.7.>.G|
00000120  04 52 04 57 04 64 04 6f  04 7b 04 81 04 87 04 8d  |.R.W.d.o.{......|
00000130  04 93 04 a0 04 ae 04 b9  04 bf 04 c5 04 cc 04 d4  |................|
00000140  04 da 04 e5 04 ea 04 f5  04 fc 05 04 05 09 05 14  |................|
00000150  05 1a 05 23 05 29 05 30  05 3c 05 43 05 4a 05 51  |...#.).0.<.C.J.Q|
00000160  05 56 05 5b 05 67 05 6e  05 74 05 7b 05 87        |.V.[.g.n.t.{..|
```