芒果TV视频解析API返回JSON格式说明

一、为什么需要了解芒果TV视频解析API的JSON格式

在对接芒果TV视频解析接口时，开发者最常遇到的问题就是：明明按照文档传了参数，却不知道返回的JSON里每个字段代表什么、该如何取值。本文用通俗的语言，把返回结果拆开讲清楚，让你看完就能上手写代码。

二、一个完整的JSON返回示例

下面是一段经过简化、但结构真实的返回示例，方便后续逐字段对照：

{   "code": 200,   "msg": "success",   "data": {     "title": "乘风破浪的姐姐 第1期",     "video_id": "8a9c3b1f",     "duration": 5400,     "cover": "https://img.mgtv.com/cover.jpg",     "play_url": "https://cdn.mgtv.com/play.m3u8",     "definition": [       {"name": "标清", "url": "https://cdn.mgtv.com/480p.m3u8"},       {"name": "高清", "url": "https://cdn.mgtv.com/720p.m3u8"},       {"name": "超清", "url": "https://cdn.mgtv.com/1080p.m3u8"}     ],     "subtitles": [       {"lan": "zh", "url": "https://sub.mgtv.com/zh.vtt"}     ]   } }

三、顶层字段含义说明

3.1 code（状态码）

code 表示请求是否成功。常见取值：

• 200：请求成功，可以读取 data 节点；
• 400：参数错误，通常是缺少必填字段或格式不合法；
• 403：权限不足，可能是密钥未通过或接口被禁用；
• 404：视频不存在或已被下架；
• 500：服务器内部错误，建议稍后重试。

3.2 msg（提示信息）

msg 是对 code 的文字说明，方便排查问题。例如 code 为 403 时，msg 可能返回 "invalid api key"。

3.3 data（业务数据）

当 code 等于 200 时，data 节点才会有内容，否则可能为 null。下面重点拆解 data 内部的字段。

四、data 节点关键字段详解

4.1 基础信息

• title：视频标题，例如 "乘风破浪的姐姐 第1期"；
• video_id：视频唯一标识，用于二次请求或日志追踪；
• duration：视频总时长，单位为秒；
• cover：封面图片 URL，可直接用于前端展示。

4.2 播放地址 play_url 与清晰度 definition

play_url 是默认清晰度的播放链接，通常为 m3u8 或 mp4 格式。如果接口支持多清晰度切换，则会返回 definition 数组，开发者可以根据用户网络环境选择合适的 URL。

4.3 字幕信息 subtitles

subtitles 为数组结构，每一项包含 lan（语言标识，如 zh、en）和 url（字幕文件地址）。如果视频没有外挂字幕，该字段可能为空数组。

五、用 Python 快速解析

下面给出一段最简示例，演示如何读取 title 和 play_url：

import requests
res = requests.get("https://api.example.com/mgtv/parse?url=xxx")
result = res.json()
if result["code"] == 200:
    print("标题：", result["data"]["title"])
    print("播放地址：", result["data"]["play_url"])
else:
    print("错误：", result["msg"])

六、用 JavaScript 解析

前端通过 fetch 获取数据时，可以这样处理：

fetch("https://api.example.com/mgtv/parse?url=xxx")   .then(res => res.json())   .then(json => {     if (json.code === 200) {       document.title = json.data.title;       videoPlayer.src = json.data.play_url;     } else {       alert(json.msg);     }   });

七、常见问题排查

1. 返回 code 为 400：检查请求参数是否完整，特别是视频 URL 是否经过 urlencode；
2. definition 数组为空：说明该视频只有单一清晰度，可直接使用 play_url；
3. play_url 播放失败：可能是链接已过期，建议重新调用解析接口获取最新地址；
4. subtitles 为空数组：表示视频没有外挂字幕，可在前端隐藏字幕按钮。

八、温馨提示与总结

对接芒果TV视频解析API时，先确认 code 是否为 200，再读取 data 内部字段；遇到错误优先看 msg 提示；播放链接通常有时效性，建议在用户点击播放时再实时请求，而不是提前缓存过久。掌握以上要点，就能稳定、高效地完成视频解析与播放功能。