社区共享 API 草案

本文档描述当前公共服务接口。

查询片段

GET /v1/videos/{videoId}/segments

响应：

{
  "videoId": "7669344658548047311",
  "segments": [
    {
      "id": "seg_01...",
      "start": 18.5,
      "end": 31.2,
      "category": "sponsor",
      "status": "trusted",
      "score": 0.92,
      "clusterSize": 2
    }
  ]
}

扩展正常播放查询使用隐私版本：

GET /v1/videos/by-hash/{sha256(videoId)}/segments
X-Client-ID: 匿名贡献者 UUID（已启用社区时）

带合法匿名贡献者 ID 时，每个结果额外返回 ownedByMe，供客户端隐藏对自己投稿的投票和举报入口；服务端不会返回提交者哈希。原始作品 ID 查询仅保留用于旧客户端兼容和迁移。

同一作品、同一分类中时间高度重叠或起止边界接近的投稿会聚合为一个代表片段；clusterSize 大于 1 时表示该结果包含多条相近投稿。

提交片段

POST /v1/segments
Content-Type: application/json

{
  "videoId": "7669344658548047311",
  "start": 18.5,
  "end": 31.2,
  "category": "sponsor",
  "duration": 585.0,
  "clientRequestId": "随机 UUID"
}

服务端必须校验数值范围、片段长度、视频时长、重复请求和提交速率。clientRequestId 与提交者哈希组成唯一键；相同请求重试返回原片段，不会重复创建。

我的社区片段

GET /v1/me/segments
X-Client-ID: 匿名贡献者 UUID

返回该匿名贡献者已提交的片段，以及 submittedCount 和 contributedSeconds。服务端只使用 X-Client-ID 的加盐哈希查询，不保存原始值。

统计中还包含：

skipCount：这些片段实际被其他匿名用户跳过的次数；
helpedPeople：去重后的匿名用户数；
secondsSaved：实际累计节省秒数。
receivedUpvotes / receivedDownvotes：投稿收到的赞成与反对总数；
disputedCount：当前处于争议状态的投稿数量。

修改或撤回自己的投稿

PATCH /v1/me/segments/{segmentId}
X-Client-ID: 匿名贡献者 UUID
Content-Type: application/json

{ "start": 19.2, "end": 30.8, "category": "sponsor" }

修改成功后会清除该片段原有的投票、举报和帮助统计，并记录修改前后的时间与分类。

DELETE /v1/me/segments/{segmentId}
X-Client-ID: 匿名贡献者 UUID

撤回会把片段标记为 rejected 并停止分发，不直接删除修订记录。

记录一次有效跳过

POST /v1/segments/{segmentId}/skips
X-Client-ID: 匿名贡献者 UUID

同一匿名用户对同一片段每天最多计入一次，提交者自己跳过自己的片段不计入。

投票

POST /v1/segments/{segmentId}/votes

{ "vote": 1 }

vote 只能为 1 或 -1。同一匿名客户端对同一片段只能保留一个当前投票。

POST /v1/segments/{segmentId}/reports

举报原因应使用有限枚举：wrong_video、wrong_time、not_ad、abuse、other。

防滥用最低要求

IP 与匿名客户端双层限流；
请求体 Schema 校验；
幂等请求 ID；
审核日志；
不向客户端暴露提交者 IP；
合法提交可立即成为可信片段；社区反对、举报和管理员操作用于事后纠错。

FilesExpand file tree

API.md

Latest commit

History