Files

T

nepiedg 49b709df9f Add video download failure reporting feature

- 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.

2026-01-03 23:50:30 +00:00

4.3 KiB

Raw Blame History

去水印服务 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 不存在则创建用户，存在则更新资料并返回用户信息。
请求体

{
  "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 示例：

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/"}'

成功示例

{
  "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 示例：

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 问题。

4.3 KiB Raw Blame History Unescape Escape