Aether 媒体解析 API

多平台无水印视频/图集解析 · 已注册 12 个通道：抖音 · TikTok · 微信视频号 · X(Twitter) · B站 · 皮皮虾 · 快手 · 小红书 · 西瓜 · 知乎 · 微博 · Instagram

鉴权

所有请求需携带请求头（或 query 参数 access_key）：

x-access-key: 你从管理员处获取的 API Key

限流：解析接口每 IP 每分钟 120 次，超限进入 3 分钟安全冷却（HTTP 429）；转存/裁剪接口单独计数。Key 自身若配配额，用尽后同样返回 429。

POST解析媒体 /api/x/parse

POST https://ddan.tech/api/x/parse
Content-Type: application/json
x-access-key: 你的Key

{"url": "把用户发的分享链接或口令【全文】直接放这里"}
💡 url 字段无需任何预处理：完整链接、无前缀短链（b23.tv/xxx）、纯口令文本（含BV号/av号）都能自动识别。

成功响应 200

{
  "code": 200, "success": true, "cached": false,
  "source": "bilibili_direct",
  "message": "Bilibili 视频解析成功",
  "data": {
    "platform": "bilibili",       // 平台标识
    "mediaType": "video",         // video=视频 / image=图集
    "title": "视频标题",
    "uploader": "作者名",
    "duration": 1044,             // 秒
    "thumbnail": "封面图URL",
    "bestVideo": {                // ⭐ 最佳视频直链（直接下载/播放）
      "url": "https://...", "quality": "1080p",
      "width": 1920, "height": 1080
    },
    "formats": [...],             // 多清晰度列表（部分平台）
    "imageUrls": [...],           // mediaType=image 时：图集各张原图
    "totalImages": 0
  }
}

错误码

HTTP含义
400未能从输入中提取到有效链接/口令
403Key 无效 / 被禁用 / 已过期
422平台解析失败（响应带 debug.lastError 可看原因）
429触发限流或 Key 配额用尽
503该平台通道熔断冷却中（持续失败后自动进入 60s 冷却，稍后重试）
504解析超时（20s 熔断），可重试
💡 皮皮虾说明：bestVideo 已自动优选无片尾水印流，客户端无需再处理。b23.tv 短链走通用通道，标题可能退化为链接码；建议对接方先还原成 BV 直链再调用以获得完整信息。

POST解析媒体 V2 /api/x/parse/v2

POST https://ddan.tech/api/x/parse/v2
Content-Type: application/json
x-access-key: 你的Key

{"url": "分享链接或口令全文"}

推荐使用的增强版解析接口，请求体与 /api/x/parse 完全一致（旧接口保持完全兼容）。增强能力：

能力说明
source 字段响应中标明命中的解析通道（如 bilibili_direct / pipixia_direct / ytdlp_v3）
响应头 X-Channel-Layer格式 hit;平台;通道名 或 miss;...，用于观测解析路径与排障
平台级熔断某平台持续失败自动进入 60 秒冷却，期间快速返回 503，不浪费时间等待
热缓存同链接 5 分钟内重复解析秒回（响应带 cached:true）
异步任务配合 POST /api/x/tasks 提交后台解析，GET /api/x/tasks/:id 轮询结果，适合慢平台

🧪 在线测试

对接示例

推荐接口：POST /api/x/parse/v2（模块化通道层：多解析器容灾、失败归因、热缓存）。老的 /api/x/parse 已逐步淘汰，仅保留兼容，不建议新接入使用。

JavaScript / Node

const res = await fetch('https://ddan.tech/api/x/parse/v2', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-access-key': 'YOUR_KEY' },
  body: JSON.stringify({ url: rawTextFromUser })
});
const { code, data } = await res.json();
if (code === 200 && data.mediaType === 'video') {
  console.log(data.bestVideo.url);      // 视频直链
} else if (code === 200) {
  console.log(data.imageUrls);          // 图集
}

Python

import requests
r = requests.post('https://ddan.tech/api/x/parse/v2',
    headers={'x-access-key': 'YOUR_KEY'},
    json={'url': raw_text_from_user}, timeout=25)
d = r.json()
if d['code'] == 200:
    print(d['data']['bestVideo']['url'])

curl

curl -X POST https://ddan.tech/api/x/parse/v2 \
  -H "Content-Type: application/json" \
  -H "x-access-key: YOUR_KEY" \
  -d '{"url":"https://b23.tv/xxxx"}'

附加接口（进阶）

接口说明
POST /api/x/ingest转存视频到服务器，返回 24 小时有效的临时分享码 playCode
GET /api/x/play/:code查询转存结果（videoUrl / downloadUrl / 过期时间），无需鉴权
GET /api/x/download/:code直接下载转存文件，无需鉴权
POST /api/x/trim片尾智能裁剪：传 {videoUrl:"直链"} 或 {url:"分享链接"}，可选 removeCornerMark:true 抹角标（重编码有痕迹，慎用）。自动检测白色片尾并无损剪切，返回本地直链
GET /api/x/stream?u=代理流：传编码后的直链，自动摘 Referer + 移动 UA 转发，带 Range 断点续传。用于客户端播放器直连部分防盗链 CDN 403 的场景。单流 512MB 上限
POST /api/x/keys/usageKey 自助查询：携带自己的 Key 调用，返回配额 / 已用 / 剩余，适合给下游客户自查