接口调用

如果您希望把 MediaGo 当成一个可调用的下载服务来使用，这一页可以直接作为调用说明。

本文只覆盖当前版本已经对外可用的接口行为，不涉及源码运行或开发模式。

适用场景

想用 curl、Postman、Node.js 或其他脚本直接调本地接口
想把 MediaGo 当成一个本地下载执行器使用
想让自己写的工具或自动化脚本接入 MediaGo

先确认你在调哪一个服务

桌面端内置本地服务

如果您启动的是 打包好的 MediaGo 桌面程序，应用会在本机启动一个下载服务，固定监听：

http://127.0.0.1:59673/api/v1

只要桌面程序处于运行状态，您就可以直接在本机脚本里调用这个地址。

Server / NAS 服务

如果您调用的是 自己已经部署好的 MediaGo Server / NAS 服务，那么基础地址就是您自己的服务地址，例如：

http://你的服务器地址:9900/api/v1

这类服务通常需要 API Key。

响应格式

MediaGo 的本地接口统一返回如下结构：

{
  "code": "0",
  "message": "",
  "data": {}
}

code = "0" 表示成功
非 0 表示失败
真实数据都在 data 字段里

鉴权规则

桌面端本地模式

桌面端本地接口通常不需要额外带 X-AUTH-APIKEY。
也就是说，只要桌面程序已经启动，本机脚本一般可以直接请求。

Server / NAS 模式

如果您调的是已经部署好的 Server / NAS 服务，那么除这三个接口之外，其余接口都需要带：

X-AUTH-APIKEY: your-api-key

白名单接口只有：

/api/v1/auth/is-setup
/api/v1/auth/setup-auth
/api/v1/auth/signin

最常用的 4 个调用示例

下面示例默认以桌面端本地服务为例：

export BASE_URL="http://127.0.0.1:59673/api/v1"

1. 健康检查

curl -s "$BASE_URL/healthy"

返回成功时，说明本地服务已经启动并且可以响应请求。

2. 读取当前配置

curl -s \
  -X POST "$BASE_URL/config/get" \
  -H "Content-Type: application/json" \
  -d '{}'

这个接口会返回当前配置，例如下载目录、代理、并发数、API Key 等。

3. 获取任务列表

curl -s \
  -X POST "$BASE_URL/tasks/list" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 10,
    "filter": "list"
  }'

可用筛选值：

list：进行中、等待中、暂停、失败等未完成任务
done：已完成任务

4. 创建一个下载任务

curl -s \
  -X POST "$BASE_URL/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-video",
    "url": "https://example.com/video.m3u8",
    "folder": "demo",
    "headers": "User-Agent: Mozilla/5.0",
    "downloadNow": false
  }'

说明：

headers 当前接口里是字符串，不是数组
如果要立即开始下载，把 downloadNow 改成 true
创建成功后会在 data.id 返回任务 ID

继续控制任务

拿到任务 ID 后，可以继续调用：

开始下载

curl -s \
  -X POST "$BASE_URL/tasks/start" \
  -H "Content-Type: application/json" \
  -d '{"id":"your-task-id"}'

暂停下载

curl -s \
  -X POST "$BASE_URL/tasks/stop" \
  -H "Content-Type: application/json" \
  -d '{"id":"your-task-id"}'

删除任务

curl -s \
  -X POST "$BASE_URL/tasks/delete" \
  -H "Content-Type: application/json" \
  -d '{"id":"your-task-id"}'

Server / NAS 模式的初始化示例

如果您调的是已经部署好的 Server / NAS 服务，通常先要完成一次初始化。下面用一个局域网地址举例：

export BASE_URL="http://你的服务器地址:9900/api/v1"
export API_KEY="your-api-key"

检查是否已经初始化

curl -s \
  -X POST "$BASE_URL/auth/is-setup" \
  -H "Content-Type: application/json" \
  -d '{}'

首次设置 API Key

curl -s \
  -X POST "$BASE_URL/auth/setup-auth" \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\":\"$API_KEY\"}"

后续请求带上鉴权头

curl -s \
  -X POST "$BASE_URL/config/get" \
  -H "Content-Type: application/json" \
  -H "X-AUTH-APIKEY: $API_KEY" \
  -d '{}'

JavaScript 调用示例

const baseURL = "http://127.0.0.1:59673/api/v1";

const res = await fetch(`${baseURL}/tasks/list`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    page: 1,
    pageSize: 10,
    filter: "list",
  }),
});

const json = await res.json();

if (json.code !== "0") {
  throw new Error(json.message || "Request failed");
}

console.log(json.data);