mirror of
https://github.com/krau/SaveAny-Bot.git
synced 2026-05-19 08:39:31 +08:00
docs: Add documentation for various features including Aria2, direct download links, parsers, storage rules, silent mode, storage transfer, chat watching, and yt-dlp video download
- Created new markdown files for Aria2 download, direct download links, parsers, storage rules, silent mode, storage transfer, chat watching, and yt-dlp video download. - Included usage examples, configuration instructions, and detailed explanations for each feature. - Translated documentation into Chinese for accessibility.
This commit is contained in:
krau
@@ -13,248 +13,4 @@ To use the bot's Telegram file saving feature, you need to send or forward the f
|
||||
|
||||
1. File or media messages, such as images, videos, documents, etc.
|
||||
2. Telegram message links, for example: `https://t.me/acherkrau/1097`. **Even if the channel prohibits forwarding and saving, the bot can still download its files.**
|
||||
3. Telegra.ph article links. The bot will download all images in the article.
|
||||
|
||||
## Silent Mode (silent)
|
||||
|
||||
Use the `/silent` command to toggle silent mode.
|
||||
|
||||
By default, silent mode is off, and the bot will ask you for the save location of each file.
|
||||
|
||||
When silent mode is enabled, the bot will save files directly to the default location without confirmation.
|
||||
|
||||
Before enabling silent mode, you need to set the default save location using the `/storage` command.
|
||||
|
||||
|
||||
## Storage Rules
|
||||
|
||||
Storage rules allow you to define redirection rules when the bot uploads files to storage, so that saved files are automatically organized.
|
||||
|
||||
See: <a href="https://github.com/krau/SaveAny-Bot/issues/28" target="_blank">#28</a>
|
||||
|
||||
Currently supported rule types:
|
||||
|
||||
1. FILENAME-REGEX
|
||||
2. MESSAGE-REGEX
|
||||
3. IS-ALBUM
|
||||
|
||||
Basic syntax for adding rules:
|
||||
|
||||
"RuleType RuleContent StorageName Path"
|
||||
|
||||
Pay attention to spaces; the bot can only parse correctly formatted syntax. Below is an example of a valid rule command:
|
||||
|
||||
```
|
||||
/rule add FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos
|
||||
```
|
||||
|
||||
In addition, if `CHOSEN` is used as the storage name in the rule, it means files will be stored under the path of the storage you selected by clicking the inline button.
|
||||
|
||||
Rule types:
|
||||
|
||||
### FILENAME-REGEX
|
||||
|
||||
Matches based on filename regex. The rule content must be a valid regular expression, such as:
|
||||
|
||||
```
|
||||
FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos
|
||||
```
|
||||
|
||||
This means files with extensions mp4, mkv, ts, avi, flv will be saved to the `/videos` directory in the storage named `MyAlist` (also affected by the `base_path` in the configuration file).
|
||||
|
||||
### MESSAGE-REGEX
|
||||
|
||||
Similar to the above, but matches based on the text content of the message itself.
|
||||
|
||||
### IS-ALBUM
|
||||
|
||||
Matches album messages (media groups). Rule content can only be `true` or `false`.
|
||||
|
||||
If the path in the rule uses `NEW-FOR-ALBUM`, the bot will create a new folder for each media group and store all files of that group there. See: https://github.com/krau/SaveAny-Bot/issues/87
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
IS-ALBUM true MyWebdav NEW-FOR-ALBUM
|
||||
```
|
||||
|
||||
This will save media-group messages to the storage named `MyWebdav`, creating a new folder (generated from the first file) for each album.
|
||||
|
||||
## Watch Chats
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires enabling UserBot integration.
|
||||
{{< /hint >}}
|
||||
|
||||
You can watch messages in a specific chat and automatically save them to the default storage, following storage rules. You can also add filters so that only matching messages are saved.
|
||||
|
||||
Watch a chat:
|
||||
|
||||
```
|
||||
/watch <chat_id/username> [filter]
|
||||
```
|
||||
|
||||
Stop watching:
|
||||
|
||||
```
|
||||
/unwatch <chat_id/username>
|
||||
```
|
||||
|
||||
Filter types:
|
||||
|
||||
### msgre
|
||||
|
||||
Regex-match the message text. For example:
|
||||
|
||||
```
|
||||
/watch 12345678 msgre:.*hello.*
|
||||
```
|
||||
|
||||
This will watch the chat with ID `12345678`, and only save messages whose text contains `hello`.
|
||||
|
||||
## Direct Download Links
|
||||
|
||||
Use the `/dl` command to directly download one or more HTTP/HTTPS files to storage.
|
||||
|
||||
```bash
|
||||
/dl <url1> [url2] [url3] ...
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
/dl https://example.com/file.zip
|
||||
/dl https://example.com/file1.zip https://example.com/file2.zip
|
||||
```
|
||||
|
||||
The bot will validate the link format and then ask you to select the target storage location.
|
||||
|
||||
## Aria2 Download
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires enabling Aria2 in the configuration file and configuring the RPC connection.
|
||||
{{< /hint >}}
|
||||
|
||||
Use the `/aria2dl` command to download files via the Aria2 download manager, supporting HTTP/HTTPS, FTP, BitTorrent, and other protocols.
|
||||
|
||||
```bash
|
||||
/aria2dl <uri1> [uri2] [uri3] ...
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Download HTTP link
|
||||
/aria2dl https://example.com/file.zip
|
||||
|
||||
# Download magnet link
|
||||
/aria2dl magnet:?xt=urn:btih:...
|
||||
|
||||
# Download torrent file (need to upload .torrent file first)
|
||||
/aria2dl https://example.com/file.torrent
|
||||
```
|
||||
|
||||
Configure Aria2:
|
||||
|
||||
Add to `config.toml`:
|
||||
|
||||
```toml
|
||||
[aria2]
|
||||
enable = true
|
||||
url = "http://localhost:6800/jsonrpc"
|
||||
secret = "your-rpc-secret" # If rpc-secret is configured
|
||||
remove_after_transfer = true # Remove local files after transfer
|
||||
```
|
||||
|
||||
## yt-dlp Video Download
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires the yt-dlp command-line tool installed on your system.
|
||||
{{< /hint >}}
|
||||
|
||||
Use the `/ytdlp` command to download videos and audio from supported video websites, including YouTube, Bilibili, Twitter, and 1000+ other sites.
|
||||
|
||||
```bash
|
||||
/ytdlp <url1> [url2] [flags...]
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Basic download
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
||||
|
||||
# Download multiple videos
|
||||
/ytdlp https://www.youtube.com/watch?v=video1 https://www.youtube.com/watch?v=video2
|
||||
|
||||
# Use custom parameters
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ -f best
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ --extract-audio --audio-format mp3
|
||||
```
|
||||
|
||||
Common parameters:
|
||||
|
||||
- `-f <format>`: Specify download format (e.g., `best`, `worst`, `bestvideo+bestaudio`)
|
||||
- `--extract-audio`: Extract audio
|
||||
- `--audio-format <format>`: Audio format (e.g., `mp3`, `m4a`, `wav`)
|
||||
- `--write-sub`: Download subtitles
|
||||
- `--write-thumbnail`: Download thumbnail
|
||||
|
||||
For more parameters, see [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp#usage-and-options).
|
||||
|
||||
## Storage Transfer
|
||||
|
||||
Use the `/transfer` command to transfer files directly between different storages without going through Telegram.
|
||||
|
||||
```bash
|
||||
/transfer <source_storage>:/<source_path> [filter]
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `source_storage`: Source storage name
|
||||
- `source_path`: Source path
|
||||
- `filter`: Optional regex filter to transfer only matching files
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Transfer entire directory
|
||||
/transfer local1:/downloads
|
||||
|
||||
# Transfer files from specified path
|
||||
/transfer alist1:/media/photos
|
||||
|
||||
# Transfer only mp4 files
|
||||
/transfer webdav1:/videos ".*\.mp4$"
|
||||
|
||||
# Transfer image files
|
||||
/transfer local1:/pictures "(?i)\.(jpg|png|gif)$"
|
||||
```
|
||||
|
||||
The bot will:
|
||||
|
||||
1. List all files in the source path
|
||||
2. Apply the filter (if provided)
|
||||
3. Display file count and total size
|
||||
4. Ask you to select the target storage
|
||||
5. Ask you to select the target directory (if configured for that storage)
|
||||
6. Start the transfer task
|
||||
|
||||
Notes:
|
||||
|
||||
- Source storage must support listing and reading
|
||||
- Target storage must support writing
|
||||
- Real-time progress is displayed during transfer
|
||||
- Transfer tasks can be cancelled
|
||||
|
||||
## Save Files Outside Telegram
|
||||
|
||||
Besides files on Telegram, the bot can also save files from other websites via JavaScript plugins or built-in parsers.
|
||||
|
||||
> See the [Contributing Parsers](../contribute) document for details.
|
||||
|
||||
Just send links that match the requirements of a parser to the bot. Currently built-in parsers include:
|
||||
|
||||
- Twitter
|
||||
- Kemono
|
||||
3. Telegra.ph article links. The bot will download all images in the article.
|
||||
442
docs/content/en/usage/api.md
Normal file
442
docs/content/en/usage/api.md
Normal file
@@ -0,0 +1,442 @@
|
||||
---
|
||||
title: "HTTP API"
|
||||
weight: 20
|
||||
---
|
||||
|
||||
# HTTP API
|
||||
|
||||
SaveAny-Bot provides an HTTP API that allows you to programmatically create download/transfer tasks, query task status, cancel tasks, and more — without going through Telegram.
|
||||
|
||||
## Enabling the API
|
||||
|
||||
Add or modify the following section in `config.toml`:
|
||||
|
||||
```toml
|
||||
[api]
|
||||
enable = true
|
||||
host = "0.0.0.0" # Bind address, default 0.0.0.0
|
||||
port = 8080 # Listen port, default 8080
|
||||
token = "your-token" # Auth token — strongly recommended
|
||||
```
|
||||
|
||||
You can also override these settings with environment variables (prefix `SAVEANY_`):
|
||||
|
||||
| Environment Variable | Config Key |
|
||||
|---|---|
|
||||
| `SAVEANY_API_ENABLE` | `api.enable` |
|
||||
| `SAVEANY_API_HOST` | `api.host` |
|
||||
| `SAVEANY_API_PORT` | `api.port` |
|
||||
| `SAVEANY_API_TOKEN` | `api.token` |
|
||||
|
||||
{{< hint warning >}}
|
||||
If `token` is empty, the API server will be accessible **without any authentication**, which is a security risk.
|
||||
{{< /hint >}}
|
||||
|
||||
## Authentication
|
||||
|
||||
When `token` is configured, all API requests must include a Bearer token in the HTTP header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <your-token>
|
||||
```
|
||||
|
||||
On authentication failure, the server returns `401`:
|
||||
|
||||
```json
|
||||
{ "error": "unauthorized", "message": "invalid token" }
|
||||
```
|
||||
|
||||
## Error Response Format
|
||||
|
||||
All errors use a consistent JSON format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "human readable description"
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
|
||||
| Error Code | HTTP Status | Meaning |
|
||||
|---|---|---|
|
||||
| `unauthorized` | 401 | Authentication failed |
|
||||
| `method_not_allowed` | 405 | Wrong HTTP method |
|
||||
| `invalid_request` | 400 | Malformed request body or parameters |
|
||||
| `task_creation_failed` | 400 | Failed to create task |
|
||||
| `task_not_found` | 404 | Task ID does not exist |
|
||||
| `cancel_failed` | 500 | Failed to cancel task |
|
||||
| `internal_error` | 500 | Internal server error |
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### GET /health — Health Check
|
||||
|
||||
No authentication required.
|
||||
|
||||
**Response `200 OK`:**
|
||||
|
||||
```json
|
||||
{ "status": "ok" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/storages — List Storages
|
||||
|
||||
Returns all currently loaded storage backends.
|
||||
|
||||
**Response `200 OK`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"storages": [
|
||||
{ "name": "local", "type": "local" },
|
||||
{ "name": "MyMinio", "type": "s3" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/task-types — List Supported Task Types
|
||||
|
||||
**Response `200 OK`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"types": [
|
||||
"directlinks",
|
||||
"ytdlp",
|
||||
"aria2",
|
||||
"parseditem",
|
||||
"tgfiles",
|
||||
"tphpics",
|
||||
"transfer"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /api/v1/tasks — Create Task
|
||||
|
||||
**Request headers:**
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Request body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "<task_type>",
|
||||
"storage": "<storage_name>",
|
||||
"path": "<subpath>",
|
||||
"webhook": "<callback_url>",
|
||||
"params": { }
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `type` | string | Yes | Task type — see below |
|
||||
| `storage` | string | Yes | Target storage name, must match a name in your config |
|
||||
| `path` | string | No | Subdirectory path within the storage |
|
||||
| `webhook` | string | No | Callback URL invoked when the task reaches a terminal state |
|
||||
| `params` | object | Yes | Type-specific parameters — see below |
|
||||
|
||||
**Response `201 Created`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "abc123xyz",
|
||||
"type": "directlinks",
|
||||
"status": "queued",
|
||||
"created_at": "2026-03-11T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### Task Types and params
|
||||
|
||||
##### directlinks — Direct URL Download
|
||||
|
||||
Download one or more files from direct HTTP/HTTPS URLs.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "directlinks",
|
||||
"storage": "local",
|
||||
"path": "downloads",
|
||||
"params": {
|
||||
"urls": [
|
||||
"https://example.com/file.zip",
|
||||
"https://example.com/other.zip"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `urls` | []string | Yes | List of download URLs, at least 1 |
|
||||
|
||||
##### ytdlp — yt-dlp Media Download
|
||||
|
||||
{{< hint warning >}}
|
||||
Requires yt-dlp to be installed on the system.
|
||||
{{< /hint >}}
|
||||
|
||||
Download videos or audio via yt-dlp, supporting YouTube, Bilibili, and 1000+ other sites.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "ytdlp",
|
||||
"storage": "local",
|
||||
"path": "videos",
|
||||
"params": {
|
||||
"urls": ["https://www.youtube.com/watch?v=xxx"],
|
||||
"flags": ["--extract-audio", "--audio-format", "mp3"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `urls` | []string | Yes | List of media URLs, at least 1 |
|
||||
| `flags` | []string | No | Extra yt-dlp command-line flags |
|
||||
|
||||
##### aria2 — Aria2 Download
|
||||
|
||||
{{< hint warning >}}
|
||||
Requires Aria2 to be enabled and configured (RPC) in the config file.
|
||||
{{< /hint >}}
|
||||
|
||||
Download files via the Aria2 download manager, supporting HTTP/HTTPS, FTP, BitTorrent (magnet links, torrent files), and more.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "aria2",
|
||||
"storage": "local",
|
||||
"path": "downloads",
|
||||
"params": {
|
||||
"urls": ["magnet:?xt=urn:btih:..."],
|
||||
"options": { "split": "4" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `urls` | []string | Yes | List of download URIs, at least 1 |
|
||||
| `options` | map[string]string | No | Aria2 download options |
|
||||
|
||||
##### parseditem — Parser Plugin Download
|
||||
|
||||
Hand a URL off to a registered JS plugin or built-in parser for processing and downloading.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "parseditem",
|
||||
"storage": "local",
|
||||
"path": "parsed",
|
||||
"params": {
|
||||
"url": "https://some-site.com/page"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `url` | string | Yes | The URL to parse |
|
||||
|
||||
Returns `400 task_creation_failed` if no parser is able to handle the URL.
|
||||
|
||||
##### tgfiles — Telegram Message File Download
|
||||
|
||||
Download files from Telegram messages via message links. Supported link formats:
|
||||
|
||||
- `https://t.me/username/123` — public channel or group
|
||||
- `https://t.me/c/123456789/123` — private channel by numeric ID
|
||||
- `https://t.me/c/123456789/111/456` — topic message (thread ID / message ID)
|
||||
- `https://t.me/username/111/456` — topic under a username-based chat
|
||||
|
||||
If the message is part of a media group (album), all files in the group are downloaded by default. Append `?single` to the link to force downloading only the single specified message.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tgfiles",
|
||||
"storage": "local",
|
||||
"path": "telegram",
|
||||
"params": {
|
||||
"message_links": [
|
||||
"https://t.me/username/123",
|
||||
"https://t.me/c/1234567890/456"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `message_links` | []string | Yes | List of Telegram message links, at least 1 |
|
||||
|
||||
##### tphpics — Telegraph Article Images
|
||||
|
||||
Download all images from a Telegra.ph article.
|
||||
|
||||
Supported URL prefixes: `https://telegra.ph/`, `http://telegra.ph/`, `https://telegraph.co/`, `http://telegraph.co/`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tphpics",
|
||||
"storage": "local",
|
||||
"path": "telegraph",
|
||||
"params": {
|
||||
"telegraph_url": "https://telegra.ph/Some-Article-01-01"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `telegraph_url` | string | Yes | URL of the Telegra.ph article |
|
||||
|
||||
##### transfer — Storage-to-Storage Transfer
|
||||
|
||||
Transfer files directly between two storage backends without going through Telegram. The source storage must support both listing and reading.
|
||||
|
||||
{{< hint info >}}
|
||||
For `transfer` tasks, the top-level `storage` field is still required for validation, but the actual storages used are determined by `source_storage` and `target_storage` inside `params`.
|
||||
{{< /hint >}}
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "transfer",
|
||||
"storage": "local",
|
||||
"params": {
|
||||
"source_storage": "MyS3",
|
||||
"source_path": "backups/",
|
||||
"target_storage": "LocalDisk",
|
||||
"target_path": "restored/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| params field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `source_storage` | string | Yes | Source storage name |
|
||||
| `source_path` | string | Yes | Path within the source storage; must contain at least one file |
|
||||
| `target_storage` | string | Yes | Target storage name |
|
||||
| `target_path` | string | Yes | Destination path within the target storage |
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/tasks — List All Tasks
|
||||
|
||||
Returns all tasks created via the API. Task records are stored in memory only and are cleared on restart.
|
||||
|
||||
**Response `200 OK`:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"task_id": "abc123xyz",
|
||||
"type": "directlinks",
|
||||
"status": "running",
|
||||
"title": "file.zip",
|
||||
"storage": "local",
|
||||
"path": "downloads",
|
||||
"error": "",
|
||||
"created_at": "2026-03-11T10:00:00Z",
|
||||
"updated_at": "2026-03-11T10:00:05Z",
|
||||
"progress": {
|
||||
"total_bytes": 10485760,
|
||||
"downloaded_bytes": 5242880,
|
||||
"percent": 50.0
|
||||
}
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
The `progress` field is only included when `total_bytes > 0`. The `error` field is only included when non-empty.
|
||||
|
||||
---
|
||||
|
||||
### GET /api/v1/tasks/{task_id} — Get Task
|
||||
|
||||
**Path parameter:** `task_id` — the ID returned when the task was created.
|
||||
|
||||
**Response `200 OK`:** Same structure as a single task object from the list above.
|
||||
|
||||
**Error responses:**
|
||||
- `400 invalid_request` — no task ID in path
|
||||
- `404 task_not_found` — task does not exist
|
||||
|
||||
---
|
||||
|
||||
### DELETE /api/v1/tasks/{task_id} — Cancel Task
|
||||
|
||||
**Path parameter:** `task_id`
|
||||
|
||||
**Response `200 OK`:**
|
||||
|
||||
```json
|
||||
{ "message": "task cancelled successfully" }
|
||||
```
|
||||
|
||||
**Error responses:**
|
||||
- `400 invalid_request` — no task ID in path
|
||||
- `404 task_not_found` — task does not exist
|
||||
- `500 cancel_failed` — cancellation failed
|
||||
|
||||
---
|
||||
|
||||
## Task Statuses
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| `queued` | Task is queued and waiting to run |
|
||||
| `running` | Task is currently executing |
|
||||
| `completed` | Task finished successfully |
|
||||
| `failed` | Task encountered an error |
|
||||
| `cancelled` | Task was cancelled via the DELETE endpoint |
|
||||
|
||||
---
|
||||
|
||||
## Webhook Callbacks
|
||||
|
||||
When a `webhook` URL is provided in the create request, SaveAny-Bot sends a `POST` request to that URL when the task reaches a terminal state (`completed`, `failed`, or `cancelled`).
|
||||
|
||||
**Callback request headers:**
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
User-Agent: SaveAny-Bot/1.0
|
||||
```
|
||||
|
||||
**Callback request body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "abc123xyz",
|
||||
"type": "directlinks",
|
||||
"status": "completed",
|
||||
"storage": "local",
|
||||
"path": "downloads",
|
||||
"completed_at": "2026-03-11T10:01:00Z",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
`completed_at` is only present when status is `completed` or `failed`. `error` is only present when non-empty.
|
||||
|
||||
**Retry policy:** Up to 3 attempts, with delays of 1s, 2s, and 3s between retries. Each request has a 30-second timeout.
|
||||
41
docs/content/en/usage/aria2.md
Normal file
41
docs/content/en/usage/aria2.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: "Aria2 Download"
|
||||
weight: 6
|
||||
---
|
||||
|
||||
# Aria2 Download
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires enabling Aria2 in the configuration file and configuring the RPC connection.
|
||||
{{< /hint >}}
|
||||
|
||||
Use the `/aria2dl` command to download files via the Aria2 download manager, supporting HTTP/HTTPS, FTP, BitTorrent, and other protocols.
|
||||
|
||||
```bash
|
||||
/aria2dl <uri1> [uri2] [uri3] ...
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Download HTTP link
|
||||
/aria2dl https://example.com/file.zip
|
||||
|
||||
# Download magnet link
|
||||
/aria2dl magnet:?xt=urn:btih:...
|
||||
|
||||
# Download torrent file (need to upload .torrent file first)
|
||||
/aria2dl https://example.com/file.torrent
|
||||
```
|
||||
|
||||
Configure Aria2:
|
||||
|
||||
Add to `config.toml`:
|
||||
|
||||
```toml
|
||||
[aria2]
|
||||
enable = true
|
||||
url = "http://localhost:6800/jsonrpc"
|
||||
secret = "your-rpc-secret" # If rpc-secret is configured
|
||||
remove_after_transfer = true # Remove local files after transfer
|
||||
```
|
||||
21
docs/content/en/usage/directlinks.md
Normal file
21
docs/content/en/usage/directlinks.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: "Direct Download Links"
|
||||
weight: 5
|
||||
---
|
||||
|
||||
# Direct Download Links
|
||||
|
||||
Use the `/dl` command to directly download one or more HTTP/HTTPS files to storage.
|
||||
|
||||
```bash
|
||||
/dl <url1> [url2] [url3] ...
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
/dl https://example.com/file.zip
|
||||
/dl https://example.com/file1.zip https://example.com/file2.zip
|
||||
```
|
||||
|
||||
The bot will validate the link format and then ask you to select the target storage location.
|
||||
15
docs/content/en/usage/parsers.md
Normal file
15
docs/content/en/usage/parsers.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: "Save Files Outside Telegram"
|
||||
weight: 9
|
||||
---
|
||||
|
||||
# Save Files Outside Telegram
|
||||
|
||||
Besides files on Telegram, the bot can also save files from other websites via JavaScript plugins or built-in parsers.
|
||||
|
||||
> See the [Contributing Parsers](../contribute) document for details.
|
||||
|
||||
Just send links that match the requirements of a parser to the bot. Currently built-in parsers include:
|
||||
|
||||
- Twitter
|
||||
- Kemono
|
||||
58
docs/content/en/usage/rules.md
Normal file
58
docs/content/en/usage/rules.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "Storage Rules"
|
||||
weight: 3
|
||||
---
|
||||
|
||||
# Storage Rules
|
||||
|
||||
Storage rules allow you to define redirection rules when the bot uploads files to storage, so that saved files are automatically organized.
|
||||
|
||||
See: <a href="https://github.com/krau/SaveAny-Bot/issues/28" target="_blank">#28</a>
|
||||
|
||||
Currently supported rule types:
|
||||
|
||||
1. FILENAME-REGEX
|
||||
2. MESSAGE-REGEX
|
||||
3. IS-ALBUM
|
||||
|
||||
Basic syntax for adding rules:
|
||||
|
||||
"RuleType RuleContent StorageName Path"
|
||||
|
||||
Pay attention to spaces; the bot can only parse correctly formatted syntax. Below is an example of a valid rule command:
|
||||
|
||||
```
|
||||
/rule add FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos
|
||||
```
|
||||
|
||||
In addition, if `CHOSEN` is used as the storage name in the rule, it means files will be stored under the path of the storage you selected by clicking the inline button.
|
||||
|
||||
Rule types:
|
||||
|
||||
## FILENAME-REGEX
|
||||
|
||||
Matches based on filename regex. The rule content must be a valid regular expression, such as:
|
||||
|
||||
```
|
||||
FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos
|
||||
```
|
||||
|
||||
This means files with extensions mp4, mkv, ts, avi, flv will be saved to the `/videos` directory in the storage named `MyAlist` (also affected by the `base_path` in the configuration file).
|
||||
|
||||
## MESSAGE-REGEX
|
||||
|
||||
Similar to the above, but matches based on the text content of the message itself.
|
||||
|
||||
## IS-ALBUM
|
||||
|
||||
Matches album messages (media groups). Rule content can only be `true` or `false`.
|
||||
|
||||
If the path in the rule uses `NEW-FOR-ALBUM`, the bot will create a new folder for each media group and store all files of that group there. See: https://github.com/krau/SaveAny-Bot/issues/87
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
IS-ALBUM true MyWebdav NEW-FOR-ALBUM
|
||||
```
|
||||
|
||||
This will save media-group messages to the storage named `MyWebdav`, creating a new folder (generated from the first file) for each album.
|
||||
14
docs/content/en/usage/silent.md
Normal file
14
docs/content/en/usage/silent.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: "Silent Mode"
|
||||
weight: 2
|
||||
---
|
||||
|
||||
# Silent Mode (silent)
|
||||
|
||||
Use the `/silent` command to toggle silent mode.
|
||||
|
||||
By default, silent mode is off, and the bot will ask you for the save location of each file.
|
||||
|
||||
When silent mode is enabled, the bot will save files directly to the default location without confirmation.
|
||||
|
||||
Before enabling silent mode, you need to set the default save location using the `/storage` command.
|
||||
50
docs/content/en/usage/transfer.md
Normal file
50
docs/content/en/usage/transfer.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Storage Transfer"
|
||||
weight: 8
|
||||
---
|
||||
|
||||
# Storage Transfer
|
||||
|
||||
Use the `/transfer` command to transfer files directly between different storages without going through Telegram.
|
||||
|
||||
```bash
|
||||
/transfer <source_storage>:/<source_path> [filter]
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- `source_storage`: Source storage name
|
||||
- `source_path`: Source path
|
||||
- `filter`: Optional regex filter to transfer only matching files
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Transfer entire directory
|
||||
/transfer local1:/downloads
|
||||
|
||||
# Transfer files from specified path
|
||||
/transfer alist1:/media/photos
|
||||
|
||||
# Transfer only mp4 files
|
||||
/transfer webdav1:/videos ".*\.mp4$"
|
||||
|
||||
# Transfer image files
|
||||
/transfer local1:/pictures "(?i)\.(jpg|png|gif)$"
|
||||
```
|
||||
|
||||
The bot will:
|
||||
|
||||
1. List all files in the source path
|
||||
2. Apply the filter (if provided)
|
||||
3. Display file count and total size
|
||||
4. Ask you to select the target storage
|
||||
5. Ask you to select the target directory (if configured for that storage)
|
||||
6. Start the transfer task
|
||||
|
||||
Notes:
|
||||
|
||||
- Source storage must support listing and reading
|
||||
- Target storage must support writing
|
||||
- Real-time progress is displayed during transfer
|
||||
- Transfer tasks can be cancelled
|
||||
36
docs/content/en/usage/watch.md
Normal file
36
docs/content/en/usage/watch.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "Watch Chats"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
# Watch Chats
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires enabling UserBot integration.
|
||||
{{< /hint >}}
|
||||
|
||||
You can watch messages in a specific chat and automatically save them to the default storage, following storage rules. You can also add filters so that only matching messages are saved.
|
||||
|
||||
Watch a chat:
|
||||
|
||||
```
|
||||
/watch <chat_id/username> [filter]
|
||||
```
|
||||
|
||||
Stop watching:
|
||||
|
||||
```
|
||||
/unwatch <chat_id/username>
|
||||
```
|
||||
|
||||
Filter types:
|
||||
|
||||
## msgre
|
||||
|
||||
Regex-match the message text. For example:
|
||||
|
||||
```
|
||||
/watch 12345678 msgre:.*hello.*
|
||||
```
|
||||
|
||||
This will watch the chat with ID `12345678`, and only save messages whose text contains `hello`.
|
||||
40
docs/content/en/usage/ytdlp.md
Normal file
40
docs/content/en/usage/ytdlp.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "yt-dlp Video Download"
|
||||
weight: 7
|
||||
---
|
||||
|
||||
# yt-dlp Video Download
|
||||
|
||||
{{< hint warning >}}
|
||||
This feature requires the yt-dlp command-line tool installed on your system.
|
||||
{{< /hint >}}
|
||||
|
||||
Use the `/ytdlp` command to download videos and audio from supported video websites, including YouTube, Bilibili, Twitter, and 1000+ other sites.
|
||||
|
||||
```bash
|
||||
/ytdlp <url1> [url2] [flags...]
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Basic download
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
||||
|
||||
# Download multiple videos
|
||||
/ytdlp https://www.youtube.com/watch?v=video1 https://www.youtube.com/watch?v=video2
|
||||
|
||||
# Use custom parameters
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ -f best
|
||||
/ytdlp https://www.youtube.com/watch?v=dQw4w9WgXcQ --extract-audio --audio-format mp3
|
||||
```
|
||||
|
||||
Common parameters:
|
||||
|
||||
- `-f <format>`: Specify download format (e.g., `best`, `worst`, `bestvideo+bestaudio`)
|
||||
- `--extract-audio`: Extract audio
|
||||
- `--audio-format <format>`: Audio format (e.g., `mp3`, `m4a`, `wav`)
|
||||
- `--write-sub`: Download subtitles
|
||||
- `--write-thumbnail`: Download thumbnail
|
||||
|
||||
For more parameters, see [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp#usage-and-options).
|
||||
Reference in New Issue
Block a user