---
name: mediago
description: Download videos, m3u8/HLS streams, live streams, and direct media URLs through MediaGo. Supports two modes: local packaged MediaGo desktop app at 127.0.0.1:59673, and MediaGo Server/NAS with API key authentication. Triggers on: download video, 下载视频, 下载这个链接, 帮我用 mediago 下载, set mediago server, 设置 mediago server, mediago api key, 切换到本机 mediago.
license: MIT
metadata:
  author: caorushizi
  version: 1.0.0
  homepage: https://mediago.torchstellar.com/
---

# MediaGo Video Downloader

Use MediaGo to create, start, and monitor download tasks.

This skill supports two connection modes:

1. `local`: connect to the packaged MediaGo desktop app on the same machine at `http://127.0.0.1:59673`
2. `server`: connect to a deployed MediaGo Server / NAS instance at a user-provided URL with `X-AUTH-APIKEY`

Do not tell the user to run repository source code. This skill is for:

- an installed MediaGo desktop app that is already running
- or an already deployed MediaGo Server / NAS

## Configuration

Config file: `~/.mediago-skill.json`

```json
{
  "mode": "local",
  "serverUrl": "",
  "apiKey": ""
}
```

### Mode Rules

- If the config file does not exist, default to `local`
- `local` mode always uses `http://127.0.0.1:59673`
- `server` mode uses `serverUrl`
- In `server` mode, always send header `X-AUTH-APIKEY: <apiKey>`
- In `local` mode, do not send an API key

When reading `serverUrl`, normalize it:

- strip the trailing slash
- strip a trailing `/api`
- strip a trailing `/api/v1`

Store only the root server address, for example:

- correct: `http://你的服务器地址:9900`
- not recommended: `http://你的服务器地址:9900/api/v1`

## First-Time Setup / 首次配置

If the config file does not exist, do not block immediately. Try `local` mode first.

If `local` mode health check fails and there is no valid server config, respond in the user's language:

> EN: "MediaGo is not reachable yet. To use this skill:
>
> 1. Open the installed MediaGo desktop app on this machine and keep it running, then ask me to retry.
> 2. Or configure MediaGo Server mode, for example:
>    - `set mediago server to http://your-server:9900`
>    - `set mediago api key to YOUR_API_KEY`
> 3. To switch back to local desktop mode later, say: `use local mediago`"

> CN: "还没有连上 MediaGo。要使用这个 skill：
>
> 1. 打开这台机器上已经安装好的 MediaGo 桌面版，并保持运行，然后让我重试。
> 2. 或者配置 MediaGo Server 模式，例如：
>    - `设置 mediago server 为 http://你的服务器地址:9900`
>    - `设置 mediago api key 为 你的密钥`
> 3. 之后如果要切回本机桌面版模式，可以说：`切换 mediago 到本机模式`"

## Config Update Triggers / 更新配置触发词

Trigger config updates on phrases like:

- EN:
  - `set mediago server to ...`
  - `mediago api key is ...`
  - `use local mediago`
  - `use mediago server mode`
  - `show mediago config`
- CN:
  - `设置 mediago server 为 ...`
  - `设置 mediago api key 为 ...`
  - `切换 mediago 到本机模式`
  - `切换 mediago 到 server 模式`
  - `查看 mediago 配置`

Update rules:

- if the user sets `serverUrl`, write it back normalized and switch `mode` to `server`
- if the user sets `apiKey`, preserve the existing `mode`
- if the user says `use local mediago` / `切换 mediago 到本机模式`, set `mode` to `local` and keep `serverUrl` / `apiKey` for future reuse
- if the user says `use mediago server mode` / `切换 mediago 到 server 模式`, set `mode` to `server`
- always preserve unknown fields if they already exist

## API Basics

All successful responses use this envelope:

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

Any non-zero `code` means the request failed, even if the HTTP status is `200`.

### Health Check

Local mode:

```bash
curl -s http://127.0.0.1:59673/api/v1/healthy
```

Server mode:

```bash
curl -s \
  -H "X-AUTH-APIKEY: YOUR_API_KEY" \
  http://YOUR_SERVER/api/v1/healthy
```

Expect `code` to be `"0"` and `data` to be `"OK"`.

If server mode returns auth failure, tell the user the API key may be missing or incorrect and ask them to update it.

## Request Rules / 调用规则

- Always respond in the same language as the user
- If the user only asks to download a URL, proceed without unnecessary confirmation
- Default to `downloadNow: true`
- If the user explicitly says "just add it" / `先加入任务不要开始`, use `downloadNow: false`
- If the user provides multiple URLs and does not need custom names, use `batchCreate`
- If the user provides a custom file name, folder, or special headers, use `create`
- If the user provides cookies or request headers, pass them as one newline-separated string in `headers`
- Never ask the user to manually build or run repository code

Header format example:

```text
Cookie: SESSDATA=...
Referer: https://www.bilibili.com/
User-Agent: Mozilla/5.0 ...
```

## API Reference

Read the config file before each API call, then compute:

- `BASE_URL`
- `AUTH_HEADER` for server mode only

In the examples below:

- in `local` mode, omit the auth header line
- in `server` mode, include `-H "X-AUTH-APIKEY: $API_KEY"`

### Get Current Download Config

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/config/get"
```

Useful field: `data.local` is the current download directory.

### Create One Task

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/create" \
  -d '{
    "url": "VIDEO_URL",
    "name": "OPTIONAL_NAME",
    "folder": "OPTIONAL_FOLDER",
    "headers": "OPTIONAL_HEADERS",
    "downloadNow": true
  }'
```

Successful response:

```json
{
  "code": "0",
  "data": {
    "id": "TASK_ID",
    "duplicated": false
  }
}
```

### Create Multiple Tasks

Use this when the user gives multiple URLs and does not need per-item custom naming:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/batchCreate" \
  -d '{
    "urls": "URL_1\nURL_2\nURL_3",
    "headers": "OPTIONAL_HEADERS",
    "downloadNow": true
  }'
```

### List Tasks

Running / queued / failed / stopped tasks:

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

Completed tasks:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/list" \
  -d '{"page":1,"pageSize":200,"filter":"done"}'
```

Search `data.list` by task `id`.

### Active Progress

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/progress" \
  -d '{}'
```

`data.list` includes:

- `id`
- `name`
- `status`
- `percent`
- `speed`
- `isLive`
- `url`

### Task Logs

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/logs" \
  -d '{"id":"TASK_ID"}'
```

Use this when a task fails or the user asks why it stopped.

### Control Task

Start:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/start" \
  -d '{"id":"TASK_ID"}'
```

Stop / pause:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/stop" \
  -d '{"id":"TASK_ID"}'
```

Resume:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/resume" \
  -d '{"id":"TASK_ID"}'
```

Delete:

```bash
curl -s \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/api/v1/tasks/delete" \
  -d '{"id":"TASK_ID"}'
```

## Download Workflow / 下载流程

### Single URL

1. Read config. If missing, assume `local`.
2. Compute `BASE_URL` and auth header.
3. Run health check.
4. If health check fails:
   - in `local` mode: ask the user to open the installed MediaGo desktop app, or configure server mode
   - in `server` mode: ask the user to verify the server address and API key
5. Create the task with `downloadNow: true`.
6. Extract `data.id` as `TASK_ID`.
7. Poll every 3 seconds:
   - call `/tasks/progress` and look for `TASK_ID`
   - call `/tasks/list` with `filter: "list"` if the task is not in active progress
   - call `/tasks/list` with `filter: "done"` if still not found
8. Merge the observations:
   - if found in `progress`, report `percent`, `speed`, and `status`
   - if found in `done`, treat it as success
   - if found in `list` with `status: failed` or `stopped`, fetch logs and explain the failure briefly
9. On success:
   - prefer `filePath`
   - fallback to `file`
   - if neither is present, call `/config/get` and report the download directory from `data.local`
10. If polling exceeds 5 minutes, tell the user the task is still running in MediaGo and share the latest known progress.

### Multiple URLs

- Use `batchCreate` when there are multiple URLs and no per-item custom name is required
- Report at least:
  - created count
  - duplicated count
- Only poll each item in detail if the user explicitly asks

## Result Messages / 结果表达

Use natural user-facing language, not raw API dumps.

Examples:

- EN success:
  - `Download started in MediaGo.`
  - `Download complete. File: /path/to/file`
- EN failure:
  - `The task was created, but MediaGo reported a failure.`
  - `The server rejected the request. Your API key may be incorrect.`

- CN success:
  - `已经把任务提交到 MediaGo。`
  - `下载完成，文件路径：/path/to/file`
- CN failure:
  - `任务已经创建，但 MediaGo 返回了失败状态。`
  - `服务端拒绝了请求，可能是 API Key 不正确。`

## Important Notes / 注意事项

- Prefer `local` mode first unless the user explicitly asks for server mode
- `127.0.0.1` only means the current machine; do not replace it with a guessed LAN IP
- For server examples, always use placeholders like `http://你的服务器地址:9900`
- Do not ask the user to compile or launch source code from this repository
- Treat non-zero API `code` as failure even if the HTTP status is `200`