热门跟拍 API

服务地址：https://server.diandianmaomi.com。官网入口：https://diandianmaomi.com/trends.html。

本功能只接收外部推送的热门分析、保存用户请求并展示外部回填的方案，不自动抓取热门视频、不调用模型、不播放原作音视频。列表初始为空；以下数据都是调用格式示例，不代表真实热门作品。

配置与鉴权

在后端运行环境配置 TRENDS_ADMIN_API_KEY，使用独立的 32–256 位随机字母、数字、下划线或连字符。可用 node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))" 在你控制的终端生成，再写入服务器受保护的 .env 并重启 API 服务。保留原有 AUTH_SECRET、短信、数据库等配置。

管理请求都要携带 Authorization: Bearer <TRENDS_ADMIN_API_KEY>。JSON 请求携带 Content-Type: application/json。此密钥能读取所有跟拍请求及用户主动提交的作品资料，只能放在可信后端或受保护的本地环境中，不写进网页、插件安装包、公开文档或 Git。普通登录凭证不能调用管理接口。管理接口拒绝携带 Origin 的浏览器请求。

未配置密钥返回 503；缺少或错误密钥返回 401。下文先在本地环境变量中设置同一个 TRENDS_ADMIN_API_KEY，然后使用 PowerShell：

$base = 'https://server.diandianmaomi.com'

$headers = @{ Authorization = 'Bearer ' + $env:TRENDS_ADMIN_API_KEY }

1. 推送一条热门视频分析

POST /v1/admin/trends/analyses

{

  "externalId": "your-system-analysis-001",

  "title": "替换为真实热门作品的分析标题",

  "authorName": "原作者名称",

  "sourceUrl": "https://www.douyin.com/video/1234567890123456789",

  "summary": "这一条作品值得研究的核心内容。",

  "analysis": "内容结构\n填写有依据的分析。\n\n拍摄与表达\n填写具体观察。"

}

先将上述内容保存为 UTF-8 的 analysis.json，将示例视频链接替换成真实原作链接：

$published = Invoke-RestMethod -Method Post -Uri "$base/v1/admin/trends/analyses" -Headers $headers -ContentType 'application/json; charset=utf-8' -Body ([IO.File]::ReadAllBytes((Join-Path $PWD 'analysis.json')))

$analysisId = $published.analysis.id

必填：externalId（1–120 字符，调用方唯一业务编号）、title（1–160）、sourceUrl（抖音作品 HTTPS 地址）、analysis（1–40000）。可选：authorName（最多 100）、summary（最多 600）、publishedAt（含时区的 ISO 8601 时间，例如 2026-09-15T09:00:00+08:00，不能晚于当前时间）。

默认 publishedAt 是首次接收时间，列表按这个时间从新到旧展示；同时间用 ID 稳定排序。这是分析的发布时间，并非原视频上传时间，也不表示系统验证了视频热度。支持 v.douyin.com 短链接、www.douyin.com/video/…、图文 /note/… 和 www.iesdouyin.com/share/video/…。

返回 201：{"created":true,"analysis":{"id":"…", ...}}。相同 externalId 和完全相同的字段重试返回 200 和原记录；相同 externalId 对应不同内容返回 409，不覆盖已发布内容。新版本分析使用新的 externalId。时间戳字段响应为 Unix 毫秒。

2. 查询用户提交的应用请求

GET /v1/admin/trends/requests?status=pending&limit=10

$page = Invoke-RestMethod -Uri "$base/v1/admin/trends/requests?status=pending&limit=10" -Headers $headers

$page.requests

if ($page.nextCursor) {

  $after = [Uri]::EscapeDataString($page.nextCursor)

  $nextPage = Invoke-RestMethod -Uri "$base/v1/admin/trends/requests?status=pending&limit=10&after=$after" -Headers $headers

}

status 可选 pending、completed，省略查询全部。limit 为 1–30，默认 10。管理列表按提交时间从旧到新排列，先处理较早请求。分页时保持相同 status；nextCursor 为 null 表示当前没有后续页面。下一轮重新从第一页开始查询 pending，避免遗漏新请求。

响应结构：

{

  "requests": [{

    "id": "请求UUID",

    "userId": "内部账号ID",

    "analysisId": "分析UUID",

    "status": "pending",

    "sourceWork": {

      "shareText": "用户复制的本人作品完整分享内容",

      "shareUrl": "https://v.douyin.com/作品短链接/"

    },

    "analysis": {

      "id": "分析UUID", "title": "分析标题", "authorName": "原作者",

      "sourceUrl": "原作品地址", "summary": "摘要", "analysis": "完整分析"

    },

    "result": null,

    "createdAt": 1789430400000,

    "completedAt": null,

    "updatedAt": 1789430400000

  }],

  "nextCursor": null

}

GET /v1/admin/trends/requests/:id 可读取单个请求。sourceWork 是提交时的资料快照：之后修改个人配置不会改变旧请求。保存分享内容不等于验证用户拥有该抖音账号，也不会自动解析出作者主页，后续处理方按需使用链接与分享原文。接口不返回手机号或其他登录资料。

每个账号对同一分析只产生一个请求，重复点击返回原请求。GET 不领取、不锁定任务；多个处理程序需要自行协调，同一请求回填使用 PUT 语义。

3. 填写“如何应用到自己的作品”

PUT /v1/admin/trends/requests/:id/result

{

  "content": "适合你的主题\n填写结合用户作品的具体建议。\n\n拍摄步骤\n1. …\n2. …\n\n可用文案\n…"

}

将方案保存为 UTF-8 的 result.json，将下面的请求 ID 换成查询返回的 id：

$requestId = '替换为查询返回的请求UUID'

$saved = Invoke-RestMethod -Method Put -Uri "$base/v1/admin/trends/requests/$requestId/result" -Headers $headers -ContentType 'application/json; charset=utf-8' -Body ([IO.File]::ReadAllBytes((Join-Path $PWD 'result.json')))

$saved.request.status

content 必填，1–40000 字符。返回 200，状态变为 completed。用户登录官网，在“我的跟拍”刷新即可看到。支持换行的纯文字；HTML 和 Markdown 图片不会执行或嵌入。相同内容重试不改变更新时间；再次提交不同内容会修订该方案，保留首次完成时间并更新 updatedAt。不存在的请求返回 404。

公开与网站接口

- GET /v1/public/trends/analyses?limit=10&after=…：公开分析，按发布时间倒序，不需要密钥。

- GET /v1/public/trends/analyses/:id：公开单条分析。

- GET/POST /v1/web/trends/profile：本人的作品配置，POST 为 {"shareText":"完整分享内容"}。

- POST /v1/web/trends/requests：{"analysisId":"分析UUID"}；初次 201，重复 200；没配置作品返回 428。

- GET /v1/web/trends/requests?limit=10&after=…：本人的请求，按提交时间倒序。

- GET /v1/web/trends/requests/:id：本人的单个请求和方案。

网站接口沿用官网短信登录后的安全 Cookie 和精确 Origin 校验，不接受管理密钥来冒充用户。创建请求不另行扣款；直播观察会员规则没有改动。

常见错误

400：字段、作品链接或分页格式不合法。401：未登录或管理密钥错误。403：请求来源不允许。404：记录不存在或不属于本人。409：externalId 与已有内容冲突。428：先保存本人作品。429：请求太频繁。503：管理密钥尚未配置。响应包含 error 中文说明。

默认每分钟管理接口 300 次，公开读取每 IP 120 次；用户提交每分钟 20 次、每天 100 次，另受已有账号读取限制。对 429 使用退避重试。推送时保留 externalId、回填时保留请求 ID，避免网络重试造成重复工作。