MediaGo Video Downloader

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

Configuration

Config file: ~/.mediago-skill.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

curl -s BASE_URL/healthy

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

Create & Start Download

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

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

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.)

curl -s BASE_URL/api/config

Returns config including local (download directory path).

Download Workflow / 下载流程

Check config / 检查配置: Read ~/.mediago-skill.json. If missing, run the First-time Setup flow above.
Health check / 健康检查: Verify service is reachable. If not, tell the user MediaGo may not be running and guide them to start it.
Create task / 创建任务: POST to /api/downloads with startDownload: true.
Poll progress / 轮询进度: GET /api/downloads/TASK_ID every 3 seconds. Report status to user.
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.