madou 麻豆传媒 API 接口面向 madoutv 生态的开发者，提供内容目录、视频元数据、播放入口与鉴权能力。主域 api.md-video.com.cn 于 2024 年 6 月完成接口版本统一，当前稳定版本为 v3。开发者可在此获取接入说明、字段定义与调用限制，用于构建麻豆传媒在线观看相关的应用与工具。
madou 麻豆传媒 API 接口是 madoutv 面向开发者开放的一组 HTTP 服务，用于读取内容目录、视频元数据与播放入口，主域为 api.md-video.com.cn，当前稳定版本 v3。
这套接口把麻豆传媒的内容能力拆成可组合的原子服务。开发者不需要直接接触存储层，只需按接口约定的路径与参数发起请求，即可获得结构化的 JSON 数据。接口分为四类：目录类用于分页拉取内容列表，元数据类用于获取单条内容的标题、时长、分类、更新时间等字段，播放类用于换取带时效的播放入口，账户类用于配额查询与令牌续期。
截至 2025 年 1 月，v3 版本共开放 27 个端点，覆盖麻豆传媒在线观看场景所需的主要数据。所有端点均要求签名鉴权，未携带有效签名的请求会返回 401 状态码。
接入 api.md-video.com.cn 需要三步：申请 AppKey 与 AppSecret、生成签名令牌、按端点路径发起请求，全流程通常在 30 分钟内完成。
第一步，在开发者中心提交应用信息，获得一对 AppKey 与 AppSecret。第二步，用 AppKey 与时间戳调用令牌端点，服务端返回有效期 7200 秒的 access_token。第三步，在业务请求的 Header 中携带 Authorization 字段，值为 Bearer 加令牌。签名算法采用 HMAC-SHA256，签名串由请求方法、路径、时间戳与请求体摘要拼接而成。
建议开发者把令牌缓存在服务端，避免每次请求都重新换取。2024 年 6 月之后，接口对重复换取令牌的行为做了频次限制，单 AppKey 每分钟最多换取 10 次。下面是常见的接入顺序：
madoutv 开发者中心把接口分为目录、元数据、播放、检索、账户五类，共 27 个端点，覆盖从内容发现到播放回传的完整链路。
目录类接口负责分页输出内容列表，支持按分类、更新时间、热度排序。元数据类接口输出单条内容的完整字段，包括标题、时长、分类标签、更新日期与清晰度选项。播放类接口返回带时效的播放入口，入口有效期 300 秒，过期后需重新换取。检索类接口支持关键词匹配与标签组合过滤。账户类接口用于查询剩余配额与调用日志。
下表列出五类接口的典型端点与用途：
| 分类 | 典型端点 | 用途 |
|---|---|---|
| 目录 | /v3/catalog/list | 分页拉取内容列表 |
| 元数据 | /v3/media/detail | 获取单条内容字段 |
| 播放 | /v3/play/entry | 换取带时效播放入口 |
| 检索 | /v3/search/query | 关键词与标签过滤 |
| 账户 | /v3/account/quota | 查询配额与调用日志 |
madou API 的常用功能模块包括内容目录、视频详情、播放地址、分类检索、标签过滤、进度回传、配额查询、错误码表、签名工具与沙箱环境，共十项。
这十项模块覆盖了 madou 麻豆传媒开发者从接入到上线的完整流程。每一项都对应独立的接口端点与字段说明，可单独接入，也可组合使用。下面按使用频率列出：
分页拉取 madou 内容列表，支持分类与排序参数。
按内容 ID 获取标题、时长、分类与更新日期。
换取有效期 300 秒的带签名播放入口。
按分类维度筛选 madoutv 内容集合。
多标签组合过滤，返回匹配内容列表。
上报播放位置，用于续播与统计。
查询当日剩余调用次数与历史用量。
列出 4xx 与 5xx 错误码的含义与处理建议。
在线生成 HMAC-SHA256 签名串，便于调试。
独立沙箱域，返回模拟数据，不影响生产配额。
调用 madou 麻豆传媒接口需注意三点：签名有效期、配额上限与播放入口时效，任一环节出错都会导致请求失败。
签名有效期 7200 秒，过期后需重新换取。配额按 AppKey 维度统计，免费档 600 次/分钟，超出后返回 429 状态码。播放入口有效期 300 秒，适合在用户点击播放的瞬间换取，不建议提前批量获取。
接口返回的所有时间字段均为 UTC 时间戳，单位为秒。开发者在前端展示时需自行转换为本地时区，避免出现日期偏移。
另外，2025 年 1 月起，接口对 User-Agent 为空或异常的请求会做额外校验。建议在服务端发起请求时携带明确的应用标识，便于排查问题。日志建议保留 30 天，覆盖排障所需的时间窗口。
以下是 madou API 开发者最常提出的五个问题，涵盖鉴权、配额、播放入口、沙箱与版本兼容性。
madou API 是 madoutv 开放的 HTTP 服务集合，主域 api.md-video.com.cn，用于读取内容目录、视频元数据与播放入口。
免费档提供 600 次/分钟调用额度，2024 年 6 月起长期有效；超出后可申请企业档，额度提升至 6000 次/分钟。
播放入口有效期 300 秒，过期后需重新调用 /v3/play/entry 换取，建议在用户点击播放时实时获取。
沙箱域为 sandbox.md-video.com.cn，2025 年 1 月上线，返回模拟数据，不消耗生产配额，适合联调阶段使用。
v2 版本将于 2025 年 12 月停止服务，建议在 2025 年 6 月前完成向 v3 的迁移，字段差异见迁移文档。
madou API 自 2023 年 3 月发布 v1 以来，经历 v2、v3 两次大版本迭代，当前 v3 于 2024 年 6 月上线，端点数量从 12 个扩展到 27 个。
版本演进的核心方向是字段标准化与调用效率。v2 到 v3 的主要变化包括：统一时间字段为 UTC 时间戳、把播放入口从元数据接口中拆出、新增配额查询端点、把错误码从字符串改为数字。这些调整让 madou 麻豆传媒的接口更贴近主流 API 设计习惯，降低了开发者的迁移成本。
开发者生态方面，madoutv 开发者中心提供签名工具、沙箱环境与错误码对照表，覆盖从联调到上线的完整路径。2025 年 1 月的统计显示，接入应用数量较 2024 年同期增长明显，主要集中在内容聚合与播放工具两类场景。对于希望构建麻豆传媒在线观看相关应用的团队，建议先阅读接口文档，再在沙箱中完成联调，最后切换到生产域。
接口文档会随版本更新同步维护，最近一次字段修订时间为 2025 年 1 月。开发者可在开发者中心订阅变更通知，避免因字段调整导致线上异常。