MediaGo

日本語

简体中文
English
Italiano

日本語

简体中文
English
Italiano

Appearance

ダウンロード API ​

MediaGo はダウンロードエンジンを HTTP サービスとして公開しています。デスクトップ版はポート 39719 で、Docker デプロイメントはポート 9900 でリッスンします。

HTTP をしゃべれるツール(curl / Python / Node.js / Postman など)なら何でも、この API を直接呼び出してダウンロードタスクの作成、開始、停止、進捗の取得ができます —— MediaGo 自身のブラウザ拡張機能や AI Skill もこの API の利用者です。

基本情報 ​

ベース URL ​

デプロイメントBase URL
デスクトップ版http://localhost:39719
Dockerhttp://<サーバーアドレス>:9900(実際の -p ポートマッピングに合わせて調整)

すべてのエンドポイントは /api プレフィックスの下にあります。以下の例はデスクトップ版のポート 39719 を使っています。Docker 構成の場合はそちらのポートに置き換えてください。

レスポンス形式 ​

すべての /api/* エンドポイントは統一された JSON ラッパー構造を返します:

json
{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": { ... }
}
フィールド型説明
successboolビジネス処理が成功したかどうか
codenumberビジネスエラーコード。0 は成功
messagestring人間が読めるメッセージ
dataany実際のレスポンスペイロード。エンドポイントにより構造が異なる

以下の例の「レスポンス」では data フィールドの内容のみを示します。

認証 ​

  • デスクトップ版:デフォルトで認証不要、localhost:39719 に直接リクエストするだけ
  • Docker デプロイメント:認証を有効にした場合、MediaGo の設定ページから API キーを取得し、以降のリクエストに Authorization: Bearer <key> ヘッダーを付与します

クイックスタート ​

以下の 3 つの curl コマンドで「作成 → ダウンロード開始 → 完了通知」のフローが一通り流れます。

1. ダウンロードタスクの作成 ​

bash
curl -X POST http://localhost:39719/api/downloads \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {
        "type": "m3u8",
        "url": "https://example.com/video.m3u8",
        "name": "私の動画"
      }
    ],
    "startDownload": true
  }'
  • type:ダウンロードタイプ。m3u8 / bilibili / direct / youtube / mediago から選択
  • url:動画の URL
  • name:タスク名(保存ファイル名として使われる)
  • startDownload:作成後すぐにダウンロードを開始するかどうか

レスポンス:

json
[
  {
    "id": 123,
    "name": "私の動画",
    "type": "m3u8",
    "url": "https://example.com/video.m3u8",
    "status": "waiting",
    "createdDate": "2026-04-23T10:00:00Z"
  }
]

返ってきた id を控えておいてください。以降のエンドポイントで使います。

2. ダウンロードイベントの購読(SSE) ​

bash
curl -N http://localhost:39719/api/events

これは長時間接続です。サーバーがプッシュした内容がそのまま流れてきます:

text
event: download-start
data: {"id": "123"}

event: download-success
data: {"id": "123"}

ブラウザ / Node.js の場合:

javascript
const es = new EventSource("http://localhost:39719/api/events");
es.addEventListener("download-success", (e) => {
  const { id } = JSON.parse(e.data);
  console.log("タスク完了:", id);
});

3. 状態の照会 / 手動制御 ​

bash
# すべてのダウンロードタスクを一覧表示(ページング)
curl "http://localhost:39719/api/downloads?current=1&pageSize=20"

# 単一のタスクを取得
curl http://localhost:39719/api/downloads/123

# 既存のタスクを開始
curl -X POST http://localhost:39719/api/downloads/123/start \
  -H "Content-Type: application/json" \
  -d '{"localPath": "/Downloads/MediaGo", "deleteSegments": true}'

# タスクを停止
curl -X POST http://localhost:39719/api/downloads/123/stop

# ログを取得
curl http://localhost:39719/api/downloads/123/logs

ダウンロードイベント ​

GET /api/events は Server-Sent Events ストリームです。ダウンロード関連のイベント:

イベント名ペイロード説明
download-create{ids: number[], count: number}タスクの一括作成
download-start{id: string}ダウンロード開始
download-success{id: string}ダウンロード成功
download-failed{id: string, error: string}ダウンロード失敗
download-stop{id: string}ダウンロードを手動停止

エンドポイントリファレンス ​

一覧 / 照会 ​

GET /api/downloads — ページング付きの一覧取得 ​

クエリパラメータ:

  • current (number, デフォルト 1):ページ番号
  • pageSize (number, デフォルト 20):ページサイズ
  • filter (string, 任意):ステータスでフィルタ(downloading / success / failed)
  • localPath (string, 任意):保存パスでフィルタ

レスポンス:

json
{
  "total": 42,
  "list": [
    /* DownloadTask[] */
  ]
}

GET /api/downloads/active — アクティブなタスクの一覧 ​

waiting / downloading 状態のタスクをすべて返します。

GET /api/downloads/:id — 単一タスクの取得 ​

レスポンス(DownloadTask 構造):

json
{
  "id": 123,
  "name": "私の動画",
  "type": "m3u8",
  "url": "https://example.com/video.m3u8",
  "folder": "my-folder",
  "headers": "User-Agent: ...",
  "isLive": false,
  "status": "success",
  "file": "/path/to/saved.mp4",
  "createdDate": "2026-04-23T10:00:00Z",
  "updatedDate": "2026-04-23T10:05:30Z"
}

GET /api/downloads/folders — 重複なしの保存ディレクトリ一覧 ​

レスポンス: string[]

GET /api/downloads/export — ダウンロードリストのエクスポート ​

プレーンテキスト、1 行 1 URL。

GET /api/downloads/:id/logs — ダウンロードログの取得 ​

レスポンス: { id, log: string }

作成 / 削除 ​

POST /api/downloads — ダウンロードの一括作成 ​

リクエストボディ:

json
{
  "tasks": [
    {
      "type": "m3u8 | bilibili | direct | youtube | mediago",
      "url": "https://example.com/video.m3u8",
      "name": "タスク名",
      "folder": "任意のサブディレクトリ",
      "headers": "任意、複数行の HTTP ヘッダー"
    }
  ],
  "startDownload": true
}

レスポンス: DownloadTask[]

DELETE /api/downloads/:id — タスクの削除 ​

レスポンス: {}

編集 / ステータス ​

PUT /api/downloads/:id — タスクの編集 ​

リクエストボディ(すべて任意):

json
{
  "name": "新しい名前",
  "url": "新しい URL",
  "headers": "新しいヘッダー",
  "folder": "新しいサブディレクトリ"
}

PUT /api/downloads/:id/live — ライブ配信フラグの切り替え ​

リクエストボディ: { "isLive": true }

PUT /api/downloads/status — ステータスの一括更新 ​

リクエストボディ: { "ids": number[], "status": "waiting | downloading | success | failed | stopped" }

開始 / 停止 ​

POST /api/downloads/:id/start — ダウンロード開始 ​

リクエストボディ:

json
{
  "localPath": "/Users/me/Downloads/MediaGo",
  "deleteSegments": true
}
  • localPath:保存先(絶対パス)
  • deleteSegments:m3u8 ダウンロード完了後、分割された .ts ファイルを削除するかどうか

POST /api/downloads/:id/stop — ダウンロード停止 ​

レスポンス: {}

列挙値 ​

ダウンロードタイプ type ​

値説明
m3u8HLS ストリーム(内部では N_m3u8DL-RE を使用)
bilibiliBilibili 動画(内部では BBDown を使用)
direct直接 HTTP ダウンロード(内部では aria2 を使用)
youtubeYouTube および yt-dlp がサポートする 1000+ サイト
mediagoMediaGo 内部タイプ

タスク状態 status ​

値説明
waitingキューに入り、未開始
downloadingダウンロード中
success完了
failed失敗
stopped手動停止
hello world