aria2 JSON-RPC-Leitfaden — alle 36 Methoden mit echten Beispielen

Start mit zwei Befehlen

Starten Sie aria2 mit RPC und einem Secret und senden Sie ihm dann eine Anfrage. Jedes Werkzeug, das einen HTTP-POST senden kann, funktioniert; hier ist es 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 lauscht jetzt auf Port 6800, und zwar nur auf diesem Computer. Ergänzen Sie --rpc-listen-all=true nur, wenn sich ein anderes Gerät in einem vertrauenswürdigen Netzwerk verbinden muss, und --rpc-allow-origin-all=true, wenn eine Webseite im Browser es aufruft.

Verbindung testen

Prüfen Sie von dieser Seite aus, ob Ihr Browser Ihr aria2 erreicht. Sie sendet aria2.getVersion an die eingegebene Adresse und sonst nichts.

So sieht ein Aufruf aus

Jede Anfrage ist ein kleines JSON-Objekt. Das sind seine Bestandteile:

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

"jsonrpc": "2.0"Immer dieser Wert.
"id": "1"Eine beliebige Zeichenkette Ihrer Wahl. aria2 kopiert sie in die Antwort, sodass Sie Antworten den Anfragen zuordnen können.
"method": "aria2.addUri"Eine der 36 Methoden unten.
"token:s3cret"Der erste Parameter: Ihr --rpc-secret mit dem Präfix token:. Jede aria2.*-Methode benötigt ihn.
["https://…"]Danach folgen die eigenen Parameter der Methode, in ihrer Reihenfolge.
{"split": "16"}Optionen verwenden die Namen aus der Optionsreferenz, und ihre Werte sind Zeichenketten.

Fünf Wege, sie zu senden

Alle fünf wurden mit aria2 1.37.0 getestet.

01

HTTP-POST an /jsonrpc

Der übliche Weg. Der Body ist die JSON-Anfrage.

02

WebSocket unter ws://host:6800/jsonrpc

Dieselben Anfragen über eine dauerhafte Verbindung, dazu Benachrichtigungen, die aria2 von sich aus sendet. Verwenden Sie wss:// mit --rpc-secure.

03

Ein Batch: ein JSON-Array von Anfragen

aria2 antwortet mit einem Array von Antworten in derselben Reihenfolge.

04

system.multicall

Eine Anfrage, die mehrere Methoden ausführt. Jeder innere Aufruf trägt sein eigenes Token; der äußere hat keines.

05

XML-RPC unter /rpc

Dieselben Methoden für XML-RPC-Clients. Die Werte sind XML-RPC-Typen statt JSON.

Alle 36 Methoden

Die Parameter sind nach dem Token aufgeführt. Öffnen Sie eine Zeile, um eine echte Anfrage und die echte Antwort von aria2 zu sehen.

Downloads hinzufügen

aria2.addUri (uris[], options?, position?) → GID Fügt einen Download aus einer oder mehreren URLs derselben Datei hinzu (HTTP, FTP, SFTP, Magnet).

Echte Anfrage und Antwort

{
 "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 Fügt einen Torrent aus dem Inhalt einer .torrent-Datei hinzu, Base64-kodiert.

Echte Anfrage und Antwort

{
 "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[] Fügt die Downloads hinzu, die eine Metalink-Datei beschreibt, Base64-kodiert. Gibt eine GID pro Datei zurück.

Echte Anfrage und Antwort

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

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

Anhalten, fortsetzen, entfernen

aria2.remove (gid) → GID Stoppt und entfernt einen Download, nachdem die Tracker benachrichtigt und die Verbindungen geschlossen wurden.

Echte Anfrage und Antwort

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

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

aria2.forceRemove (gid) → GID Entfernt einen Download sofort, ohne die Aufräumschritte.

Echte Anfrage und Antwort

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

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

aria2.pause (gid) → GID Hält einen Download an. Er bleibt in der Warteschlange, bis Sie ihn fortsetzen.

Echte Anfrage und Antwort

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

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

aria2.forcePause (gid) → GID Hält sofort an, ohne die Aufräumschritte.

Echte Anfrage und Antwort

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

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

aria2.pauseAll () → "OK" Hält alle aktiven und wartenden Downloads an.

Echte Anfrage und Antwort

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

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

aria2.forcePauseAll () → "OK" Hält alles sofort an.

Echte Anfrage und Antwort

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

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

aria2.unpause (gid) → GID Stellt einen angehaltenen Download zurück in die Warteschlange.

Echte Anfrage und Antwort

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

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

aria2.unpauseAll () → "OK" Stellt alle angehaltenen Downloads zurück in die Warteschlange.

Echte Anfrage und Antwort

{
 "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 Verschiebt einen Download in der Warteschlange: an eine Position, um eine Anzahl nach oben oder unten oder relativ zum Ende.

Echte Anfrage und Antwort

{
 "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] Entfernt und ergänzt URLs (Mirrors) einer Datei eines Downloads.

Echte Anfrage und Antwort

{
 "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
 ]
}

Downloads beobachten

aria2.tellStatus (gid, keys[]?) → status object Fortschritt und Details eines Downloads. Übergeben Sie eine Liste von Schlüsseln, um nur diese zu erhalten.

Echte Anfrage und Antwort

{
 "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 Die URLs eines Downloads und ob jede verwendet wird oder wartet.

Echte Anfrage und Antwort

{
 "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 Die Dateien eines Downloads mit Größe, Fortschritt und Auswahl.

Echte Anfrage und Antwort

{
 "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 Die BitTorrent-Peers eines Torrent-Downloads.

Echte Anfrage und Antwort

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

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

aria2.getServers (gid) → server list Die Server, von denen jede Datei gerade geladen wird, mit ihrer Geschwindigkeit.

Echte Anfrage und Antwort

{
 "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 Alle Downloads, die gerade laufen.

Echte Anfrage und Antwort

{
 "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 Wartende und angehaltene Downloads, ab offset, höchstens num.

Echte Anfrage und Antwort

{
 "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 Fertige, fehlgeschlagene und entfernte Downloads, die noch im Speicher sind.

Echte Anfrage und Antwort

{
 "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"
  }
 ]
}

Optionen ändern

aria2.getOption (gid) → options Alle Optionen eines Downloads.

Echte Anfrage und Antwort

{
 "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" Ändert Optionen eines Downloads. Bei einem laufenden Download lassen sich nur 7 Optionen ändern; siehe Optionsreferenz.

Echte Anfrage und Antwort

{
 "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 Die aktuellen globalen Optionen von aria2.

Echte Anfrage und Antwort

{
 "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" Ändert globale Optionen, während aria2 läuft, etwa die Geschwindigkeitslimits oder max-concurrent-downloads.

Echte Anfrage und Antwort

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

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

aria2 selbst

aria2.getGlobalStat () → speeds and counts Gesamte Download- und Upload-Geschwindigkeit sowie die Anzahl aktiver, wartender und gestoppter Downloads.

Echte Anfrage und Antwort

{
 "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" Vergisst alle fertigen, fehlgeschlagenen und entfernten Downloads.

Echte Anfrage und Antwort

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

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

aria2.removeDownloadResult (gid) → "OK" Vergisst einen fertigen, fehlgeschlagenen oder entfernten Download.

Echte Anfrage und Antwort

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

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

aria2.getVersion () → version, features Die aria2-Version und die Funktionen, mit denen es gebaut wurde. Ein guter erster Aufruf, um eine Verbindung zu testen.

Echte Anfrage und Antwort

{
 "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 Eine ID, die sich bei jedem Start von aria2 ändert.

Echte Anfrage und Antwort

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

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

aria2.saveSession () → "OK" Schreibt die Sitzungsdatei sofort. Setzt voraus, dass --save-session gesetzt ist.

Echte Anfrage und Antwort

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

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

aria2.shutdown () → "OK" Beendet aria2 sauber, wie einmaliges Drücken von Strg+C.

Echte Anfrage und Antwort

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

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

aria2.forceShutdown () → "OK" Beendet aria2 sofort, ohne die Aufräumschritte.

Echte Anfrage und Antwort

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

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

Systemmethoden

system.multicall ([{methodName, params}, …]) → list of results Führt mehrere Methoden in einer Anfrage aus.

Echte Anfrage und Antwort

{
 "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 Die Namen aller Methoden. Funktioniert ohne Token. · Kein Token nötig

Echte Anfrage und Antwort

{
 "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 Die Namen aller Benachrichtigungen. Funktioniert ohne Token. · Kein Token nötig

Echte Anfrage und Antwort

{
 "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"
 ]
}

Benachrichtigungen: aria2 meldet sich selbst

Über WebSocket sendet aria2 eine Nachricht, wenn mit einem Download etwas passiert, sodass Ihr Programm nicht regelmäßig abfragen muss. Jede enthält die GID; Details liefert aria2.tellStatus.

aria2.onDownloadStartEin Download hat begonnen oder wurde nach einer Pause fortgesetzt.
aria2.onDownloadPauseEin Download wurde angehalten.
aria2.onDownloadStopEin Download wurde von Ihnen gestoppt (entfernt).
aria2.onDownloadCompleteEin Download ist fertig. Bei Torrents: nach dem Ende des Seedings.
aria2.onDownloadErrorEin Download ist fehlgeschlagen. tellStatus zeigt errorCode und errorMessage.
aria2.onBtDownloadCompleteEin Torrent ist fertig heruntergeladen; jetzt beginnt das Seeding.

{"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"}]}

Download-Zustände

Das Feld status von tellStatus hat immer einen dieser sechs Werte:

activeLädt gerade herunter oder seedet.
waitingIn der Warteschlange, wartet auf einen freien Platz (max-concurrent-downloads).
pausedVon Ihnen angehalten.
errorWegen eines Fehlers gestoppt; errorCode enthält den Exit-Code.
completeFertig.
removedVon Ihnen entfernt. Sein errorCode ist 31.

Fehler und ihre Bedeutung

Fehler kommen als error-Objekt statt result zurück. Diese haben wir ausgelöst:

aria2 meldet	Ursache und Lösung
`Unauthorized`	Das Token ist falsch oder fehlt. Senden Sie als ersten Parameter token: gefolgt von genau dem Wert von --rpc-secret.
`GID … is not found`	Die GID ist falsch, oder der Download ist fertig und wurde bereinigt. Fertige Downloads bleiben nur bis zur Bereinigung erhalten (max-download-result, Standard 1000).
`No such method: …`	Ein Tippfehler im Methodennamen. Bei den Namen wird zwischen Groß- und Kleinschreibung unterschieden: aria2.addUri, nicht aria2.adduri.
`Parse error. (code -32700)`	Der Body ist kein gültiges JSON. Prüfen Sie die Anführungszeichen; schließen Sie das JSON in einer Shell in einfache Anführungszeichen ein.
`We encountered a problem while processing the option …`	Ein Optionswert, den aria2 nicht akzeptiert. Prüfen Sie die zulässigen Werte in der Optionsreferenz.
`Filename is not given.`	aria2.saveSession ohne --save-session. Starten Sie aria2 mit einer Sitzungsdatei.
`The parameter at 0 has wrong type.`	Ein Token wurde auf die oberste Ebene von system.multicall gesetzt. Das Token gehört in jeden inneren Aufruf.

Aus Python und Node.js

Keine zusätzlichen Bibliotheken nötig. Beide Beispiele liefen wie gezeigt gegen aria2 1.37.0, nur die URL wurde geändert.

Python 3 (Standardbibliothek)

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+ (eingebautes fetch und 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);

Es gibt auch fertige Clients: aria2p für Python sowie den Code in AriaNg und in unserer WebUI für den Browser.

Sicher betreiben

Setzen Sie immer --rpc-secret. Ohne Secret kann jeder, der den Port erreicht, aria2 Dateien auf Ihren Datenträger laden und seine Hook-Befehle ausführen lassen.
Belassen Sie den Port auf Ihrem eigenen Rechner oder in einem vertrauenswürdigen Netzwerk. Leiten Sie Port 6800 niemals ins Internet weiter.
Für den Fernzugriff betreiben Sie aria2 hinter HTTPS: --rpc-secure mit einem Zertifikat oder ein Reverse Proxy wie nginx (unser Docker-Leitfaden enthält ein getestetes Setup).
--rpc-allow-origin-all=true erlaubt jeder Webseite in Ihrem Browser, aria2 aufzurufen. Verwenden Sie es nur zusammen mit einem Secret.

Häufige Fragen

Was ist der Standard-RPC-Port von aria2?

6800. Ändern Sie ihn mit --rpc-listen-port. Der JSON-RPC-Pfad ist /jsonrpc, der XML-RPC-Pfad /rpc.

Warum gibt meine Anfrage Unauthorized zurück?

aria2 wurde mit --rpc-secret gestartet, und Ihre Anfrage enthält es nicht. Setzen Sie "token:YOUR_SECRET" als erstes Element von params. system.listMethods und system.listNotifications sind die einzigen Aufrufe, die ohne Secret funktionieren.

Warum müssen Optionswerte Zeichenketten sein?

Das aria2-Handbuch definiert Optionswerte als Zeichenketten, und aria2 wertet sie genauso aus wie auf der Kommandozeile. Senden Sie {"split": "16"}, nicht {"split": 16}.

Kann eine Webseite aria2 direkt aufrufen?

Ja, wenn aria2 mit --rpc-allow-origin-all=true läuft, damit der Browser die Anfrage zulässt. So funktionieren AriaNg und unsere Online-WebUI. Lassen Sie dabei ein Secret gesetzt.

Woran erkenne ich, dass ein Download fertig ist?

Verbinden Sie sich über WebSocket und warten Sie auf aria2.onDownloadComplete, oder fragen Sie regelmäßig aria2.tellStatus ab und prüfen Sie auf den Status "complete". Ein Hook (--on-download-complete) funktioniert ganz ohne RPC-Code.

aria2 JSON-RPC: aria2 aus jedem Programm steuern

Start mit zwei Befehlen

Verbindung testen

So sieht ein Aufruf aus

Fünf Wege, sie zu senden

HTTP-POST an /jsonrpc

WebSocket unter ws://host:6800/jsonrpc

Ein Batch: ein JSON-Array von Anfragen

system.multicall

XML-RPC unter /rpc

Alle 36 Methoden

Downloads hinzufügen

Anhalten, fortsetzen, entfernen

Downloads beobachten

Optionen ändern

aria2 selbst

Systemmethoden

Benachrichtigungen: aria2 meldet sich selbst

Download-Zustände

Fehler und ihre Bedeutung

Aus Python und Node.js

Sicher betreiben

Häufige Fragen

Weiterführend