aria2 JSON-RPC 指南 — 全部 36 个方法及真实示例

两条命令就能开始

启动带 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；当浏览器中的网页要调用它时，加上 --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"}选项使用选项参考中的名称，值都是字符串。

五种发送方式

五种方式都在 aria2 1.37.0 上测试过。

01

HTTP POST 到 /jsonrpc

最常用的方式。请求体就是 JSON 请求。

02

WebSocket：ws://host:6800/jsonrpc

通过持久连接发送同样的请求，还能收到 aria2 推送的通知。配合 --rpc-secure 时使用 wss://。

03

批量请求：由请求组成的 JSON 数组

aria2 以同样的顺序返回一个回复数组。

04

system.multicall

一个请求中运行多个方法。每个内部调用都带有自己的令牌，外层调用不带。

05

XML-RPC：/rpc

为 XML-RPC 客户端提供相同的方法。值使用 XML-RPC 类型，而不是 JSON。

全部 36 个方法

参数列在令牌之后。展开一行即可查看真实的请求和 aria2 的真实回复。

添加下载

aria2.addUri (uris[], options?, position?) → GID 从同一个文件的一个或多个 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 用 .torrent 文件的内容（base64 编码）添加种子下载。

真实的请求和回复

{
 "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[] 添加 Metalink 文件（base64 编码）中描述的下载。每个文件返回一个 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 在通知 Tracker 并关闭连接后，停止并删除一个下载。

真实的请求和回复

{
 "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] 删除和添加某个下载中一个文件的 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 一个下载的进度和详细信息。传入一个键列表可以只获取这些字段。

真实的请求和回复

{
 "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，以及每个 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 节点（Peer）。

真实的请求和回复

{
 "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 一个下载的所有选项。

真实的请求和回复

{
 "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" 修改一个下载的选项。对正在运行的下载只能修改 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" 在 aria2 运行时修改全局选项，例如速度限制或 max-concurrent-downloads。

真实的请求和回复

{
 "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" 清除一个已完成、失败或已删除的下载记录。

真实的请求和回复

{
 "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" 正常停止 aria2，相当于按一次 Ctrl+C。

真实的请求和回复

{
 "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 在一个请求中运行多个方法。

真实的请求和回复

{
 "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 字段总是以下六种之一：

active正在下载或做种。
waiting在队列中，等待空闲名额（max-concurrent-downloads）。
paused被你暂停。
error因出错而停止；errorCode 中是退出码。
complete已完成。
removed被你删除。其 errorCode 为 31。

错误及其含义

出错时返回的是 error 对象，而不是 result。以下是我们实际触发过的错误：

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。检查引号；在 shell 中请用单引号把 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 中调用

无需额外的库。两个示例都按所示代码在 aria2 1.37.0 上运行过，只改了 URL。

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 允许你浏览器中的任何网页调用 aria2。只能与密钥一起使用。

常见问题

aria2 RPC 的默认端口是多少？

6800。用 --rpc-listen-port 修改。JSON-RPC 的路径是 /jsonrpc，XML-RPC 的路径是 /rpc。

为什么我的请求返回 Unauthorized？

aria2 启动时设置了 --rpc-secret，而你的请求没有带上它。把 "token:YOUR_SECRET" 作为 params 的第一个元素。只有 system.listMethods 和 system.listNotifications 不需要它也能调用。

为什么选项值必须是字符串？

aria2 手册把选项值定义为字符串，aria2 会像解析命令行一样解析它们。应发送 {"split": "16"}，而不是 {"split": 16}。

网页可以直接调用 aria2 吗？

可以，前提是 aria2 以 --rpc-allow-origin-all=true 运行，这样浏览器才会放行请求。AriaNg 和我们的在线 WebUI 就是这样工作的。请保持设置密钥。

怎样知道下载已经完成？

通过 WebSocket 连接并等待 aria2.onDownloadComplete，或者轮询 aria2.tellStatus，检查 status 是否为 "complete"。钩子（--on-download-complete）则不需要任何 RPC 代码。

aria2 JSON-RPC：用任何程序控制 aria2

两条命令就能开始

测试你的连接

一次调用长什么样

五种发送方式

HTTP POST 到 /jsonrpc

WebSocket：ws://host:6800/jsonrpc

批量请求：由请求组成的 JSON 数组

system.multicall

XML-RPC：/rpc

全部 36 个方法

添加下载

暂停、继续、删除

查看下载

修改选项

aria2 本身

系统方法

通知：让 aria2 主动告诉你

下载状态

错误及其含义

在 Python 和 Node.js 中调用

保证安全

常见问题

相关内容