糖心Vlog 开放接口围绕内容检索、视频元数据、分类目录与榜单查询四类能力展开，主域 api.tangxing.cloud 提供 RESTful 风格调用。2025 年 6 月更新后，接口统一返回 JSON 结构，鉴权使用 Bearer Token，单账号默认每分钟 600 次请求配额。本页面向开发者梳理接入流程、字段含义与常见问题，帮助你在较短时间内完成糖心Vlog 内容服务的对接与联调。
糖心Vlog API 提供内容检索、视频元数据、分类目录、榜单查询四类接口，覆盖糖心传媒、糖心影视、糖心动漫等主要内容板块。开发者可按需组合调用，构建自己的内容聚合页面或播放列表服务。
分类目录接口 /v2/categories 返回树形结构，一级分类下挂二级标签，方便前端做多级筛选。视频元数据接口 /v2/videos/{id} 则返回标题、时长、封面、简介、标签、发布时间等字段，其中发布时间统一为 ISO 8601 格式。内容检索接口支持关键词、分类、时间范围三类过滤条件，分页参数为 page 与 size，单页上限 50 条。榜单查询接口按日榜、周榜、月榜三种维度返回，2025 年 6 月起新增动漫专区榜单，与糖心动漫频道数据同步。
接入糖心Vlog API 需要先在开发者控制台创建应用，获取 Client ID 与 Client Secret，再换取 Bearer Token 后调用接口。整个流程分为注册、换 Token、调用、刷新四步。
第一步，在控制台创建应用并填写回调地址；第二步，使用 Client ID 与 Secret 调用 /oauth/token 换取访问令牌；第三步，在请求头中加入 Authorization: Bearer <token> 调用业务接口；第四步，Token 到期前使用 refresh_token 续期，避免业务中断。2025 年 6 月之后签发的 Token 有效期为 90 天，刷新后原 Token 立即失效。建议在服务端缓存 Token 并做统一刷新，不要在前端明文存放 Secret。
接入前请确认服务端时间已与 NTP 同步，时间偏差超过 5 分钟会导致签名校验失败。
糖心Vlog API 常用接口共 10 个，覆盖鉴权、检索、详情、分类、榜单与状态查询六类场景，字段命名统一使用小驼峰，便于前端直接映射。以下卡片列出各接口的用途与入口。
使用 Client ID 与 Secret 换取 Bearer Token，有效期 90 天。
按关键词、分类、时间范围组合过滤，单页最多返回 50 条。
按视频 ID 获取标题、时长、封面、标签与发布时间等字段。
返回糖心传媒、糖心影视、糖心动漫等一级分类与二级标签。
日榜、周榜、月榜三种维度，2025 年 6 月新增动漫专区榜。
一次请求最多传入 20 个视频 ID，减少往返次数与配额消耗。
按标签聚合内容数量，适合做标签云与专题聚合页。
输入前缀返回候选词，用于搜索框联想与自动补全。
返回带时效签名的播放地址，签名默认 30 分钟有效。
返回各接口可用性与当前配额余量，便于做健康检查。
糖心Vlog API 默认单账号每分钟 600 次请求，超出后返回 429 状态码并附带 Retry-After 头，建议按该头等待后重试。错误码采用统一结构，code 为业务码，message 为可读描述。
常见错误码包括 401 未授权、403 权限不足、404 资源不存在、429 触发限流、500 服务端异常。401 通常由 Token 过期或签名错误引起，检查 Authorization 头与系统时间即可；429 需要做指数退避重试，避免短时间高频重放。2025 年 6 月后，接口对批量请求做了合并优化，批量元数据接口一次最多 20 个 ID，可显著降低配额消耗。若业务需要更高配额，可在控制台提交提额申请并说明调用场景。
| 状态码 | 含义 | 建议处理 |
|---|---|---|
| 401 | Token 无效或过期 | 重新换取 Token 并检查系统时间 |
| 403 | 权限不足 | 确认应用已开通对应接口权限 |
| 404 | 资源不存在 | 核对视频 ID 或分类标识 |
| 429 | 触发限流 | 按 Retry-After 等待后指数退避重试 |
| 500 | 服务端异常 | 记录请求 ID 并稍后重试 |
糖心Vlog API 是面向开发者的内容开放接口，提供检索、元数据、分类与榜单能力，主域为 api.tangxing.cloud。
若需要聚合糖心传媒、糖心影视、糖心动漫等内容，接入可省去自建抓取与清洗环节，按配额调用即可。
2025 年 6 月发布 v2 稳定版，旧版接口兼容至 2026 年 3 月，迁移窗口约 9 个月。
登录开发者控制台创建应用后，用 Client ID 与 Secret 调用 /oauth/token 换取 Bearer Token。
检索接口单页最多 50 条，批量元数据接口一次最多传入 20 个视频 ID。
分类目录覆盖糖心传媒、糖心影视、糖心动漫等板块，一级分类下挂二级标签，可多级筛选。
糖心Vlog API 自 2025 年 6 月发布 v2 版本以来，接口结构与字段命名保持稳定，便于开发者长期维护。糖心Vlog 的内容体系由糖心传媒、糖心娱乐、糖心影视、糖心视频、糖心动漫等板块组成，API 将这些板块统一抽象为分类目录与内容条目两层结构，开发者无需关心底层存储差异，只需按分类标识与内容 ID 调用即可。
实践层面，建议先用分类目录接口拉取全量分类树并本地缓存，再按业务场景调用检索与详情接口。榜单数据适合做首页推荐位，更新频率为每日一次；播放地址解析适合在用户点击播放时实时调用，避免签名过期。2025 年 6 月后新增的服务状态接口可纳入健康检查流程，结合配额余量做告警。若你正在规划糖心Vlog 相关的聚合应用，从 api.tangxing.cloud 的文档页开始阅读，通常能在一天内完成基础对接。