aria2 JSON-RPC ガイド — 全 36 メソッドを実例付きで解説

2 つのコマンドで始める

RPC とシークレットを指定して aria2 を起動し、リクエストを送ります。HTTP POST を送れるツールなら何でも使えます。ここでは curl を使います。

aria2c --enable-rpc --rpc-secret=s3cretcurl -s http://localhost:6800/jsonrpc -d '{"jsonrpc":"2.0","id":"1","method":"aria2.getVersion","params":["token:s3cret"]}'{"id":"1","jsonrpc":"2.0","result":{"enabledFeatures":["Async DNS","BitTorrent","Firefox3 Cookie","GZip","HTTPS","Message Digest","Metalink","XML-RPC","SFTP"],"version":"1.37.0"}}

これで aria2 はこのコンピューターだけでポート 6800 を待ち受けます。信頼できるネットワーク上の別のデバイスから接続する必要がある場合にだけ --rpc-listen-all=true を、ブラウザー内の Web ページから呼び出す場合には --rpc-allow-origin-all=true を追加してください。

接続をテストする

お使いのブラウザーから aria2 に接続できるかを、このページで確認できます。入力したアドレスに aria2.getVersion を送るだけで、それ以外は何も送りません。

呼び出しの構成

すべてのリクエストは小さな JSON オブジェクトです。各部分は次のとおりです：

{"jsonrpc": "2.0", "id": "1",
 "method": "aria2.addUri",
 "params": ["token:s3cret", ["https://example.com/file.iso"], {"split": "16"}]}

"jsonrpc": "2.0"常にこの値です。
"id": "1"任意の文字列です。aria2 はこれを返信にコピーするので、返信とリクエストを対応付けられます。
"method": "aria2.addUri"下にある 36 メソッドのいずれかです。
"token:s3cret"最初のパラメーターです。--rpc-secret の値の前に token: を付けたものです。aria2.* のメソッドはすべてこれが必要です。
["https://…"]その後にメソッド固有のパラメーターを順番に続けます。
{"split": "16"}オプションにはオプションリファレンスの名前を使い、値は文字列で指定します。

5 つの送信方法

5 つすべてを aria2 1.37.0 でテストしました。

01

/jsonrpc への HTTP POST

一般的な方法です。本文が JSON リクエストになります。

02

ws://host:6800/jsonrpc での WebSocket

持続的な接続で同じリクエストを送れるうえ、aria2 から通知が届きます。--rpc-secure を使う場合は wss:// にします。

03

バッチ：リクエストの JSON 配列

aria2 は返信の配列を同じ順番で返します。

04

system.multicall

1 つのリクエストで複数のメソッドを実行します。内側の各呼び出しにそれぞれトークンを付け、外側には付けません。

05

/rpc での XML-RPC

XML-RPC クライアント向けの同じメソッドです。値は JSON ではなく XML-RPC の型になります。

全 36 メソッド

パラメーターはトークンの後に続くものを示しています。行を開くと、実際のリクエストと aria2 の実際の返信を確認できます。

ダウンロードの追加

aria2.addUri (uris[], options?, position?) → GID 同じファイルの 1 つ以上の URL（HTTP、FTP、SFTP、マグネット）からダウンロードを追加します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "3",
 "method": "aria2.addUri",
 "params": [
  "token:s3cret",
  [
   "https://example.com/file.iso"
  ],
  {
   "max-download-limit": "2M",
   "out": "big.bin"
  }
 ]
}

{
 "id": "3",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}

aria2.addTorrent (torrent (base64), uris[]?, options?, position?) → GID base64 でエンコードした .torrent ファイルの内容からトレントを追加します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "14",
 "method": "aria2.addTorrent",
 "params": [
  "token:s3cret",
  "ZDg6YW5ub3VuY2UzMDpodHRwOi8vMTI3LjAuMC4xOjY5NjkvYW5ub3VuY2U0OmluZm9kNTpmaWxlc2xkNjpsZW5ndGhpMzAwMDAwZTQ6cGF0aGw5OnZpZGVvLm1rdmVlZDY6bGVuZ3RoaTEwMDBlNDpwYXRobDM6c3ViMTA6cmVhZG1lLnR4dGVlZDY6bGVuZ3RoaTcwMDAwZTQ6cGF0aGwzOnN1Yjk6Y292ZXIuanBnZWVlNDpuYW1lNDpkYXRhMTI6cGllY2UgbGVuZ3RoaTMyNzY4ZTY6cGllY2VzMjQwOpnUbKtB9UspPRSPmbRPBUyJ4y39+NKrYmMRZk3KJrBmwmb9ZgFD/ZbZAb/DTO3/tg0h3x15maLsKqRFgLJpURN/kvfmhAWGoDcxtJNbmObQVfZxkDNIllU5fFojZ4o+5uv8vJlpbXjZnKhXPU48QpPdWyYe/OWnK5yA+SAPzBxkDz2CLRTSXfcu0wS/E1wLRr0NNc+2E0OosvKm+/l7lQ1o8fcZ14G+RSDCDg7B5C3ASfCf/KaLkPktmBHzIxjjbjDMSJH8cQ7FcnC6dXVbB0zbe0FxnaHias8yNDiO+gnEKsbmDx8dafwjjUeU1vLBiWVl",
  [],
  {
   "pause": "true"
  }
 ]
}

{
 "id": "14",
 "jsonrpc": "2.0",
 "result": "7e95de64eed32e26"
}

aria2.addMetalink (metalink (base64), options?, position?) → GID[] base64 でエンコードした Metalink ファイルに記述されたダウンロードを追加します。ファイルごとに 1 つの GID を返します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "24",
 "method": "aria2.addMetalink",
 "params": [
  "token:s3cret",
  "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48bWV0YWxpbmsgeG1sbnM9InVybjppZXRmOnBhcmFtczp4bWw6bnM6bWV0YWxpbmsiPjxmaWxlIG5hbWU9Im0uYmluIj48dXJsPmh0dHA6Ly9sb2NhbGhvc3Q6NDMzMS9zZjAxLmJpbjwvdXJsPjwvZmlsZT48L21ldGFsaW5rPg==",
  {
   "pause": "true"
  }
 ]
}

{
 "id": "24",
 "jsonrpc": "2.0",
 "result": [
  "4792fc4fda863437"
 ]
}

一時停止・再開・削除

aria2.remove (gid) → GID トラッカーへの通知と接続の切断を行ってから、ダウンロードを停止して削除します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "26",
 "method": "aria2.remove",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26"
 ]
}

{
 "id": "26",
 "jsonrpc": "2.0",
 "result": "7e95de64eed32e26"
}

aria2.forceRemove (gid) → GID 後処理を行わずに、ダウンロードをすぐに削除します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "31",
 "method": "aria2.forceRemove",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "31",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}

aria2.pause (gid) → GID ダウンロードを一時停止します。再開するまでキューに残ります。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "10",
 "method": "aria2.pause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "10",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}

aria2.forcePause (gid) → GID 後処理を行わずに、すぐに一時停止します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "27",
 "method": "aria2.forcePause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "27",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}

aria2.pauseAll () → "OK" 実行中と待機中のダウンロードをすべて一時停止します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "29",
 "method": "aria2.pauseAll",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "29",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.forcePauseAll () → "OK" すべてをすぐに一時停止します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "28",
 "method": "aria2.forcePauseAll",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "28",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.unpause (gid) → GID 一時停止したダウンロードをキューに戻します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "12",
 "method": "aria2.unpause",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "12",
 "jsonrpc": "2.0",
 "result": "35b6f22ff341c545"
}

aria2.unpauseAll () → "OK" 一時停止したダウンロードをすべてキューに戻します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "30",
 "method": "aria2.unpauseAll",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "30",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.changePosition (gid, pos, POS_SET | POS_CUR | POS_END) → new position 待機キュー内でダウンロードを移動します。指定した位置へ、指定した数だけ上下へ、または末尾からの相対位置へ移動できます。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "16",
 "method": "aria2.changePosition",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26",
  0,
  "POS_SET"
 ]
}

{
 "id": "16",
 "jsonrpc": "2.0",
 "result": 0
}

aria2.changeUri (gid, fileIndex, delUris[], addUris[], position?) → [deleted, added] ダウンロード内の 1 つのファイルについて、URL（ミラー）を削除・追加します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "17",
 "method": "aria2.changeUri",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  1,
  [],
  [
   "https://mirror.example.com/file.iso"
  ]
 ]
}

{
 "id": "17",
 "jsonrpc": "2.0",
 "result": [
  0,
  1
 ]
}

ダウンロードの監視

aria2.tellStatus (gid, keys[]?) → status object 1 つのダウンロードの進行状況と詳細です。キーのリストを渡すと、そのキーだけを取得します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "4",
 "method": "aria2.tellStatus",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  [
   "gid",
   "status",
   "totalLength",
   "completedLength",
   "downloadSpeed",
   "connections",
   "dir"
  ]
 ]
}

{
 "id": "4",
 "jsonrpc": "2.0",
 "result": {
  "completedLength": "2113536",
  "connections": "1",
  "dir": "/downloads",
  "downloadSpeed": "1467780",
  "gid": "35b6f22ff341c545",
  "status": "active",
  "totalLength": "50000000"
 }
}

aria2.getUris (gid) → URI list ダウンロードの URL と、それぞれが使用中か待機中かです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "6",
 "method": "aria2.getUris",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "6",
 "jsonrpc": "2.0",
 "result": [
  {
   "status": "used",
   "uri": "https://example.com/file.iso"
  },
  {
   "status": "waiting",
   "uri": "https://example.com/file.iso"
  }
 ]
}

aria2.getFiles (gid) → file list ダウンロードのファイルと、そのサイズ、進行状況、選択状態です。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "5",
 "method": "aria2.getFiles",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "5",
 "jsonrpc": "2.0",
 "result": [
  {
   "completedLength": "2097152",
   "index": "1",
   "length": "50000000",
   "path": "/downloads/big.bin",
   "selected": "true",
   "uris": [
    {
     "status": "used",
     "uri": "https://example.com/file.iso"
    },
    "…"
   ]
  }
 ]
}

aria2.getPeers (gid) → peer list トレントのダウンロードの BitTorrent ピアです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "15",
 "method": "aria2.getPeers",
 "params": [
  "token:s3cret",
  "7e95de64eed32e26"
 ]
}

{
 "id": "15",
 "jsonrpc": "2.0",
 "result": []
}

aria2.getServers (gid) → server list 各ファイルが現在ダウンロードしているサーバーとその速度です。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "7",
 "method": "aria2.getServers",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "7",
 "jsonrpc": "2.0",
 "result": [
  {
   "index": "1",
   "servers": [
    {
     "currentUri": "https://example.com/file.iso",
     "downloadSpeed": "1458725",
     "uri": "https://example.com/file.iso"
    }
   ]
  }
 ]
}

aria2.tellActive (keys[]?) → status objects 現在実行中のすべてのダウンロードです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "13",
 "method": "aria2.tellActive",
 "params": [
  "token:s3cret",
  [
   "gid",
   "status",
   "downloadSpeed"
  ]
 ]
}

{
 "id": "13",
 "jsonrpc": "2.0",
 "result": [
  {
   "downloadSpeed": "0",
   "gid": "35b6f22ff341c545",
   "status": "active"
  }
 ]
}

aria2.tellWaiting (offset, num, keys[]?) → status objects 待機中と一時停止中のダウンロードを、offset から最大 num 件返します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "11",
 "method": "aria2.tellWaiting",
 "params": [
  "token:s3cret",
  0,
  10,
  [
   "gid",
   "status"
  ]
 ]
}

{
 "id": "11",
 "jsonrpc": "2.0",
 "result": [
  {
   "gid": "35b6f22ff341c545",
   "status": "paused"
  }
 ]
}

aria2.tellStopped (offset, num, keys[]?) → status objects メモリに残っている完了・失敗・削除済みのダウンロードです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "32",
 "method": "aria2.tellStopped",
 "params": [
  "token:s3cret",
  0,
  10,
  [
   "gid",
   "status",
   "errorCode"
  ]
 ]
}

{
 "id": "32",
 "jsonrpc": "2.0",
 "result": [
  {
   "errorCode": "0",
   "gid": "4792fc4fda863437",
   "status": "complete"
  },
  {
   "errorCode": "31",
   "gid": "35b6f22ff341c545",
   "status": "removed"
  }
 ]
}

オプションの変更

aria2.getOption (gid) → options 1 つのダウンロードのすべてのオプションです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "9",
 "method": "aria2.getOption",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "9",
 "jsonrpc": "2.0",
 "result": {
  "allow-overwrite": "false",
  "allow-piece-length-change": "false",
  "always-resume": "true",
  "async-dns": "true",
  "…": "…"
 }
}

aria2.changeOption (gid, options) → "OK" 1 つのダウンロードのオプションを変更します。実行中のダウンロードで変更できるのは 7 つのオプションだけです。オプションリファレンスを参照してください。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "8",
 "method": "aria2.changeOption",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545",
  {
   "max-download-limit": "4M"
  }
 ]
}

{
 "id": "8",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.getGlobalOption () → options aria2 の現在のグローバルオプションです。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "18",
 "method": "aria2.getGlobalOption",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "18",
 "jsonrpc": "2.0",
 "result": {
  "allow-overwrite": "false",
  "allow-piece-length-change": "false",
  "always-resume": "true",
  "async-dns": "true",
  "…": "…"
 }
}

aria2.changeGlobalOption (options) → "OK" 速度制限や max-concurrent-downloads などのグローバルオプションを、aria2 の実行中に変更します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "19",
 "method": "aria2.changeGlobalOption",
 "params": [
  "token:s3cret",
  {
   "max-concurrent-downloads": "3"
  }
 ]
}

{
 "id": "19",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2 本体

aria2.getGlobalStat () → speeds and counts ダウンロードとアップロードの合計速度と、実行中・待機中・停止済みのダウンロードの数です。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "20",
 "method": "aria2.getGlobalStat",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "20",
 "jsonrpc": "2.0",
 "result": {
  "downloadSpeed": "928974",
  "numActive": "1",
  "numStopped": "0",
  "numStoppedTotal": "0",
  "numWaiting": "1",
  "uploadSpeed": "0"
 }
}

aria2.purgeDownloadResult () → "OK" 完了・失敗・削除済みのダウンロードをすべて消去します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "34",
 "method": "aria2.purgeDownloadResult",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "34",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.removeDownloadResult (gid) → "OK" 完了・失敗・削除済みのダウンロードを 1 つ消去します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "33",
 "method": "aria2.removeDownloadResult",
 "params": [
  "token:s3cret",
  "35b6f22ff341c545"
 ]
}

{
 "id": "33",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.getVersion () → version, features aria2 のバージョンと、ビルド時に組み込まれた機能です。接続をテストする最初の呼び出しに適しています。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "1",
 "method": "aria2.getVersion",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "1",
 "jsonrpc": "2.0",
 "result": {
  "enabledFeatures": [
   "Async DNS",
   "BitTorrent",
   "Firefox3 Cookie",
   "GZip",
   "HTTPS",
   "Message Digest",
   "Metalink",
   "XML-RPC",
   "SFTP"
  ],
  "version": "1.37.0"
 }
}

aria2.getSessionInfo () → sessionId aria2 を起動するたびに変わる ID です。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "2",
 "method": "aria2.getSessionInfo",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "2",
 "jsonrpc": "2.0",
 "result": {
  "sessionId": "c25a0a2ad315b68eb70f9ec1479050ff9f2b6399"
 }
}

aria2.saveSession () → "OK" セッションファイルを今すぐ書き出します。--save-session の設定が必要です。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "s",
 "method": "aria2.saveSession",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "s",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.shutdown () → "OK" Ctrl+C を 1 回押したときと同じように、aria2 を正常に停止します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "37",
 "method": "aria2.shutdown",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "37",
 "jsonrpc": "2.0",
 "result": "OK"
}

aria2.forceShutdown () → "OK" 後処理を行わずに、aria2 をすぐに停止します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "z",
 "method": "aria2.forceShutdown",
 "params": [
  "token:s3cret"
 ]
}

{
 "id": "z",
 "jsonrpc": "2.0",
 "result": "OK"
}

システムメソッド

system.multicall ([{methodName, params}, …]) → list of results 1 つのリクエストで複数のメソッドを実行します。

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "m",
 "method": "system.multicall",
 "params": [
  [
   {
    "methodName": "aria2.getGlobalStat",
    "params": [
     "token:s3cret"
    ]
   },
   {
    "methodName": "aria2.addUri",
    "params": [
     "token:s3cret",
     [
      "https://example.com/small3.bin"
     ],
     {
      "pause": "true"
     }
    ]
   }
  ]
 ]
}

{
 "id": "m",
 "jsonrpc": "2.0",
 "result": [
  [
   {
    "downloadSpeed": "0",
    "numActive": "0",
    "numStopped": "0",
    "numStoppedTotal": "0",
    "numWaiting": "0",
    "uploadSpeed": "0"
   }
  ],
  [
   "9a1c64aae2e967ce"
  ]
 ]
}

system.listMethods () → method names すべてのメソッドの名前です。トークンなしで動作します。 · トークン不要

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "22",
 "method": "system.listMethods",
 "params": []
}

{
 "id": "22",
 "jsonrpc": "2.0",
 "result": [
  "aria2.addUri",
  "aria2.addTorrent",
  "aria2.getPeers",
  "aria2.addMetalink",
  "…"
 ]
}

system.listNotifications () → notification names すべての通知の名前です。トークンなしで動作します。 · トークン不要

実際のリクエストと返信

{
 "jsonrpc": "2.0",
 "id": "23",
 "method": "system.listNotifications",
 "params": []
}

{
 "id": "23",
 "jsonrpc": "2.0",
 "result": [
  "aria2.onDownloadStart",
  "aria2.onDownloadPause",
  "aria2.onDownloadStop",
  "aria2.onDownloadComplete",
  "aria2.onDownloadError",
  "aria2.onBtDownloadComplete"
 ]
}

通知：aria2 から知らせてもらう

WebSocket では、ダウンロードに何かが起きると aria2 がメッセージを送るので、プログラムでポーリングする必要がありません。各通知には GID が含まれます。詳細は aria2.tellStatus で取得してください。

aria2.onDownloadStartダウンロードが開始された、または一時停止から再開されました。
aria2.onDownloadPauseダウンロードが一時停止されました。
aria2.onDownloadStopダウンロードがユーザーによって停止（削除）されました。
aria2.onDownloadCompleteダウンロードが完了しました。トレントの場合はシードの終了後です。
aria2.onDownloadErrorダウンロードが失敗しました。tellStatus で errorCode と errorMessage を確認できます。
aria2.onBtDownloadCompleteトレントのダウンロードが完了しました。ここからシードを開始します。

{"jsonrpc":"2.0","method":"aria2.onDownloadStart","params":[{"gid":"35b6f22ff341c545"}]}
{"jsonrpc":"2.0","method":"aria2.onDownloadComplete","params":[{"gid":"4792fc4fda863437"}]}
{"jsonrpc":"2.0","method":"aria2.onDownloadPause","params":[{"gid":"35b6f22ff341c545"}]}

ダウンロードの状態

tellStatus の status フィールドは、常に次の 6 つのいずれかです：

active現在ダウンロード中またはシード中です。
waitingキューで空きを待っています（max-concurrent-downloads）。
pausedユーザーが一時停止しました。
errorエラーで停止しました。errorCode に終了コードが入ります。
complete完了しました。
removedユーザーが削除しました。errorCode は 31 です。

エラーとその意味

エラーは result の代わりに error オブジェクトとして返されます。私たちが実際に発生させたエラーは次のとおりです：

aria2 の表示	原因と対処法
`Unauthorized`	トークンが間違っているか、ありません。最初のパラメーターとして、token: の後に --rpc-secret の値をそのまま続けて送ってください。
`GID … is not found`	GID が間違っているか、ダウンロードが完了して消去されています。完了したダウンロードは消去されるまでしか残りません（max-download-result、デフォルト 1000）。
`No such method: …`	メソッド名の入力ミスです。名前は大文字と小文字を区別します。aria2.adduri ではなく aria2.addUri です。
`Parse error. (code -32700)`	本文が有効な JSON ではありません。引用符を確認してください。シェルでは JSON を単一引用符で囲みます。
`We encountered a problem while processing the option …`	aria2 が受け付けないオプション値です。オプションリファレンスで使用できる値を確認してください。
`Filename is not given.`	--save-session なしで aria2.saveSession を呼び出しました。セッションファイルを指定して aria2 を起動してください。
`The parameter at 0 has wrong type.`	system.multicall の外側にトークンを付けました。トークンは内側の各呼び出しに入れます。

Python と Node.js から

追加のライブラリは必要ありません。どちらの例も、URL だけを変えて表示どおりに aria2 1.37.0 に対して実行しました。

Python 3（標準ライブラリ）

import json
import urllib.request

RPC = "http://localhost:6800/jsonrpc"
TOKEN = "token:s3cret"

def call(method, *params):
    body = json.dumps({"jsonrpc": "2.0", "id": "py", "method": method,
                       "params": [TOKEN, *params]}).encode()
    with urllib.request.urlopen(RPC, body) as r:
        reply = json.load(r)
    if "error" in reply:
        raise RuntimeError(reply["error"]["message"])
    return reply["result"]

gid = call("aria2.addUri", ["https://example.com/file.iso"], {"split": "16"})
status = call("aria2.tellStatus", gid, ["status", "completedLength", "totalLength"])
print(gid, status)

Node.js 22 以降（組み込みの fetch と WebSocket）

// Node.js 22+: fetch and WebSocket are built in.
const RPC = 'http://localhost:6800/jsonrpc';
const TOKEN = 'token:s3cret';

async function call(method, ...params) {
  const res = await fetch(RPC, { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id: 'js', method, params: [TOKEN, ...params] }) });
  const reply = await res.json();
  if (reply.error) throw new Error(reply.error.message);
  return reply.result;
}

// Get told when a download finishes instead of polling.
const ws = new WebSocket('ws://localhost:6800/jsonrpc');
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.method === 'aria2.onDownloadComplete') console.log('done:', msg.params[0].gid);
};

const gid = await call('aria2.addUri', ['https://example.com/file.iso']);
console.log('added', gid);

既製のクライアントもあります。Python なら aria2p、ブラウザーなら AriaNg や私たちの WebUI の中のコードです。

安全に使うために

必ず --rpc-secret を設定してください。設定しないと、ポートに到達できる人なら誰でも、aria2 にファイルをディスクへダウンロードさせたり、フックコマンドを実行させたりできます。
ポートは自分のマシンか信頼できるネットワーク内にとどめてください。ポート 6800 をインターネットに転送してはいけません。
リモートからアクセスする場合は、aria2 を HTTPS の背後に置いてください。証明書を指定した --rpc-secure か、nginx などのリバースプロキシを使います（Docker ガイドにテスト済みの構成があります）。
--rpc-allow-origin-all=true を付けると、ブラウザー内のどの Web ページからも aria2 を呼び出せるようになります。必ずシークレットと一緒に使ってください。

よくある質問

aria2 の RPC のデフォルトのポートは何番ですか？

6800 です。--rpc-listen-port で変更できます。JSON-RPC のパスは /jsonrpc、XML-RPC のパスは /rpc です。

リクエストが Unauthorized を返すのはなぜですか？

aria2 が --rpc-secret 付きで起動されているのに、リクエストにその値が含まれていないためです。params の最初の要素に "token:YOUR_SECRET" を入れてください。トークンなしで動作するのは system.listMethods と system.listNotifications だけです。

オプションの値を文字列にしなければならないのはなぜですか？

aria2 のマニュアルではオプションの値を文字列と定義しており、aria2 はコマンドラインと同じ方法でそれを解析します。{"split": 16} ではなく {"split": "16"} を送ってください。

Web ページから aria2 を直接呼び出せますか？

はい。aria2 を --rpc-allow-origin-all=true 付きで実行すれば、ブラウザーがリクエストを許可します。AriaNg や私たちのオンライン WebUI はこの仕組みで動いています。シークレットは必ず設定しておいてください。

ダウンロードの完了はどうすればわかりますか？

WebSocket で接続して aria2.onDownloadComplete を待つか、aria2.tellStatus をポーリングして status が "complete" になったかを確認します。フック（--on-download-complete）を使えば、RPC のコードを書かずに済みます。

aria2 JSON-RPC：あらゆるものから aria2 を操作

2 つのコマンドで始める

接続をテストする

呼び出しの構成

5 つの送信方法

/jsonrpc への HTTP POST

ws://host:6800/jsonrpc での WebSocket

バッチ：リクエストの JSON 配列

system.multicall

/rpc での XML-RPC

全 36 メソッド

ダウンロードの追加

一時停止・再開・削除

ダウンロードの監視

オプションの変更

aria2 本体

システムメソッド

通知：aria2 から知らせてもらう

ダウンロードの状態

エラーとその意味

Python と Node.js から

安全に使うために

よくある質問

関連ページ