MediaGo Video Downloader#

Download videos from m3u8/HLS streams, Bilibili, and direct URLs via a running MediaGo instance.

Configuration#

Config file: ~/.mediago-skill.json

json

{
  "url": "http://localhost:8899",
  "apiKey": ""
}

First-time Setup / 首次配置#

If ~/.mediago-skill.json does not exist, show the following message (respond in the user's language):

EN: "MediaGo is not configured yet. To use this skill:

1. Install MediaGo (if you haven't already):

• Desktop app: Download from https://github.com/caorushizi/mediago/releases
• Docker: docker run -d --name mediago -p 8899:8899 -v /path/to/mediago:/app/mediago ghcr.io/caorushizi/mediago:latest

2. Initialize — tell me your MediaGo address, for example:

• Docker: 设置 mediago 地址为 http://localhost:8899
• Desktop app: 设置 mediago 地址为 http://192.168.x.x:39719"

CN: "MediaGo 还没有配置。要使用此功能：

1. 安装 MediaGo（如果还没装）：

• 桌面客户端：从 https://github.com/caorushizi/mediago/releases 下载安装
• Docker 部署： docker run -d --name mediago -p 8899:8899 -v /path/to/mediago:/app/mediago ghcr.io/caorushizi/mediago:latest

2. 初始化配置 — 告诉我你的 MediaGo 地址，例如：

• Docker： 设置 mediago 地址为 http://localhost:8899
• 桌面客户端： 设置 mediago 地址为 http://192.168.x.x:39719"

When the user provides the URL (and optionally an API key), write it to ~/.mediago-skill.json.

Updating Config / 更新配置#

Trigger on phrases like:

• EN: "set mediago url to ...", "mediago api key is ...", "my mediago is at ..."
• CN: "设置 mediago 地址为 ...", "mediago api key 是 ...", "我的 mediago 跑在 ..."

Read the existing config, update the relevant field, and write it back.

API Reference#

All API calls use curl. Read url and apiKey from ~/.mediago-skill.json before each call.

If apiKey is set, add header: -H "X-API-Key: API_KEY"

Health Check#

text

curl -s BASE_URL/healthy

Returns {"success":true,...} if service is running.

Create & Start Download#

text

curl -s -X POST BASE_URL/api/downloads \
  -H "Content-Type: application/json" \
  -d '{"tasks":[{"type":"TYPE","url":"VIDEO_URL","name":"NAME"}],"startDownload":true}'

• type (required): m3u8, bilibili, or direct
• url (required): video URL
• name (optional): custom filename

Type detection from URL:

• Contains bilibili.com or b23.tv → bilibili
• Contains .m3u8 → m3u8
• Otherwise → direct

Response data is an array of created tasks. Extract data[0].id as the task ID.

Get Task Status#

text

curl -s BASE_URL/api/downloads/TASK_ID

Response data fields: id, name, status, type, exists, file.

Status values: pending, downloading, success, failed, stopped.

List Downloads#

text

curl -s "BASE_URL/api/downloads?current=1&pageSize=20"

Response: data.total (count) and data.list (array of tasks).

Get Config (download directory etc.)#

text

curl -s BASE_URL/api/config

Returns config including local (download directory path).

Download Workflow / 下载流程#

1. Check config / 检查配置: Read ~/.mediago-skill.json. If missing, run the First-time Setup flow above.

2. Health check / 健康检查: Verify service is reachable. If not, tell the user MediaGo may not be running and guide them to start it.

3. Create task / 创建任务: POST to /api/downloads with startDownload: true.

4. Poll progress / 轮询进度: GET /api/downloads/TASK_ID every 3 seconds. Report status to user.

5. Report result / 报告结果:

   • success → EN: "Download complete! File: [path]" / CN: "下载完成！文件：[path]"
   • failed → EN: "Download failed." / CN: "下载失败。"
   • If polling exceeds 5 minutes, tell user the download is still in progress.

Important Notes / 注意事项#

• Language / 语言: Always respond in the same language the user is using (Chinese or English).
• If API returns HTTP 401, tell the user their API key may be wrong and ask them to update it.
• Always auto-detect the download type from the URL unless the user specifies it.
• If name is not provided, omit it from the request — the server will auto-generate one.