nepiedg
49b709df9f
- Introduced a new API endpoint `POST /api/v1/video/remove_watermark/report_failure` for reporting download failures. - Added a new database table `video_download_failures` to store details about failed downloads, including domain, URL, error message, and reporting metadata. - Updated the video handler to process failure reports and save them to the database. - Enhanced documentation to include details about the new reporting feature and its usage.
124 lines
4.3 KiB
Markdown
124 lines
4.3 KiB
Markdown
# 去水印服务 API 说明
|
||
|
||
所有接口均位于 `/api/v1`，除登录外都需要在 Header 中携带 `Authorization: Bearer <session_key>`，其中 `<session_key>` 来自登录接口的响应。
|
||
|
||
## 1. 登录（复用已有接口）
|
||
|
||
`POST /api/v1/auth/login`
|
||
|
||
登录与认证的公共说明见：`docs/common/auth.md`。
|
||
|
||
## 接口
|
||
|
||
### `POST /api/v1/auth/login`
|
||
|
||
- **说明**：接收小程序端 `wx.login` 返回的 `code`，向微信 `jscode2session` 请求 `openid` / `session_key`。若 `open_id` 不存在则创建用户，存在则更新资料并返回用户信息。
|
||
- **请求体**
|
||
|
||
```json
|
||
{
|
||
"mini_program_id": 1,
|
||
"code": "wx.login返回的code",
|
||
"nickname": "可选",
|
||
"avatar_url": "可选",
|
||
"gender": 1,
|
||
"phone": "110"
|
||
}
|
||
```
|
||
|
||
## 2. 解析短视频去水印
|
||
|
||
`POST /api/v1/video/remove_watermark`
|
||
|
||
| 项目 | 说明 |
|
||
| --- | --- |
|
||
| Header | `Authorization: Bearer <session_key>` |
|
||
| 请求体 | `{"content":"帮我解析 https://v.douyin.com/xxxx/"}` |
|
||
| 必填校验 | `content` 必须包含一个合法的 http/https 链接 |
|
||
| 响应 | `provider` 固定为 `23bt`，`raw` 为第三方原始 JSON，`free_quota_used` 表示是否占用免费额度 |
|
||
|
||
curl 示例：
|
||
|
||
```bash
|
||
curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Authorization: Bearer wx-session-key' \
|
||
-d '{"content":"帮我解析 https://v.douyin.com/xxxx/"}'
|
||
```
|
||
|
||
**成功示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"provider": "23bt",
|
||
"raw": {
|
||
"code": 200,
|
||
"msg": "解析成功",
|
||
"data": { "...第三方原始字段..." }
|
||
},
|
||
"free_quota_used": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误返回**
|
||
|
||
| HTTP 码 | code | message | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| 400 | 400 | `请求参数错误` / `请检查分享链接是否正确` | 请求体非法或内容未包含有效链接 |
|
||
| 401 | 401 | `未登录或登录已过期` | Token 缺失/失效 |
|
||
| 403 | 403 | `今日免费次数已用完，观看广告后今天可无限制使用` | 超过每日免费额度，需要走广告解锁 |
|
||
| 502 | 502 | `解析服务异常，请稍后重试` | 第三方返回异常 |
|
||
| 503 | 503 | `服务暂不可用，请联系管理员` | 未配置 `SHORT_VIDEO_API_KEY` 等关键配置 |
|
||
| 500 | 500 | `去水印失败，请稍后重试` | 其他内部错误 |
|
||
|
||
## 3. 完成广告解锁
|
||
|
||
`POST /api/v1/video/remove_watermark/unlock`
|
||
|
||
| 项目 | 说明 |
|
||
| --- | --- |
|
||
| Header | `Authorization: Bearer <session_key>` |
|
||
| 请求体 | 空 |
|
||
| 响应 | `{"code":200,"message":"success","data":{"unlocked":true}}` |
|
||
|
||
curl 示例：
|
||
|
||
```bash
|
||
curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark/unlock' \
|
||
-H 'Authorization: Bearer wx-session-key'
|
||
```
|
||
|
||
说明：调用该接口表示用户当天已经观看完广告，服务端会写入 `video_parse_unlocks`，当天余下时间不再校验免费额度。
|
||
|
||
## 4. 数据落地
|
||
|
||
- 每次解析调用都会写入 `video_parse_logs`，其中包含 `request_content`、`parsed_url`、第三方响应、调用耗时等字段，便于审计和配额统计。
|
||
- 第三方返回的 JSON 直接保存在 `video_parse_logs.third_party_payload` 字段，可通过 SQL 查询和脱敏。
|
||
- SQL DDL 位于 `docs/sql/remove_watermark.sql`，部署数据库时执行即可。
|
||
|
||
## 5. 下载失败上报
|
||
|
||
`POST /api/v1/video/remove_watermark/report_failure`
|
||
|
||
| 项目 | 说明 |
|
||
| --- | --- |
|
||
| Header | 可为空（供内部服务调用），也可附加 `Content-Type: application/json` |
|
||
| 请求体 | `{ "domain": "example.com", "failedUrl": "https://example.com/video.mp4", "errorMessage": "403 from CDN", "timestamp": 1728034710000, "userAgent": "miniprogram" }` |
|
||
| 响应 | `{"code":200,"message":"success","data":{"reported":true}}` |
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `domain` | string，可选 | 失败 URL 所属域名，若缺失会自动从 `failedUrl` 解析 |
|
||
| `failedUrl` | string，必填 | 下载失败的完整地址 |
|
||
| `errorMessage` | string，可选 | 失败原因描述，建议包含第三方响应 |
|
||
| `timestamp` | number，可选 | 失败发生时间，毫秒级 Unix 时间戳。默认使用服务端接收时间。 |
|
||
| `userAgent` | string，可选 | 报告端的 UA，默认取 HTTP 头 |
|
||
|
||
服务端会额外记录请求来源 IP（`client_ip`），并存入 `video_download_failures` 表，便于后续排查白名单或 CDN 问题。
|