StaticGramBot API

Файлы

Загрузка и скачивание файлов работают как в Telegram, но лимиты как у Local Bot API: до 2000 МБ в обе стороны. Отличается формат file_path.

Лимиты

StaticGramapi.telegram.orgLocal Bot API
Загрузка документа, видео, аудио, анимации, голосового, кружка (multipart/form-data)до 2000 МБ на запрос50 МБ2000 МБ
Фото, стикеры, thumbnail, cover, аватаркидо 25 МБфото 10 МБ-
Скачивание через getFileдо 2000 МБ, лимита 20 МБ нет20 МБбез лимита
Загрузка по ссылке (HTTPS URL вместо файла)до 10 МБ, тайм-аут 15 с5 МБ фото, 20 МБ остальное-

Большие файлы сервер не держит в памяти: тело запроса пишется во временный файл и потоком уходит в хранилище. Если тело больше лимита, ответ 413 с "description": "Request Entity Too Large", как у Telegram. Время загрузки не ограничено общим тайм-аутом (до 2 часов на один multipart-запрос).

GIF больше 25 МБ сохраняется как обычный файл, без превращения в анимацию.

Скачивание

Вызовите getFile с file_id, затем скачайте файл по file_path:

Shell
curl "https://api.staticgram.top/bot$TOKEN/getFile?file_id=ZG9jOjEzMTg4MTU4..."
# {"ok":true,"result":{"file_id":"...","file_unique_id":"...","file_size":314572800,"file_path":"ZG9jOjEzMTg4MTU4..."}}

curl -o video.mp4 "https://api.staticgram.top/file/bot$TOKEN/ZG9jOjEzMTg4MTU4..."

В StaticGram file_path совпадает с file_id (URL-safe base64 без /), а не выглядит как photos/file_1.jpg. Используйте значение как есть. Ответ отдаётся потоком с корректными Content-Type и Content-Length. Поддерживается докачка: заголовок Range: bytes=a-b или bytes=a- возвращает 206 Partial Content (один диапазон на запрос).

В библиотеках ничего менять не нужно: bot.download(...) в aiogram и File.download_to_drive() в python-telegram-bot берут адрес из настроек сервера (см. Подключение библиотек). В python-telegram-bot для файлов больше 20 МБ ничего включать не нужно: ограничение 20 МБ есть только у api.telegram.org.

Загрузка

  • Новый файл: multipart/form-data, до 2000 МБ на запрос.
  • Повторная отправка: file_id файла, который уже есть на сервере StaticGram.
  • По ссылке: HTTPS-адрес, сервер скачает файл сам (до 10 МБ).
  • В альбомах и InputMedia: attach://<имя поля>.

Параметры thumbnail, cover, start_timestamp и supports_streaming поддерживаются.

aiogram 3: файл 1,5 ГБ
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
from aiogram.types import FSInputFile

session = AiohttpSession(api=TelegramAPIServer.from_base("https://api.staticgram.top"), timeout=3600)
bot = Bot(TOKEN, session=session)
await bot.send_document(chat_id, FSInputFile("backup.tar.gz"))

Для больших файлов увеличьте тайм-аут HTTP-клиента в своей библиотеке: стандартные 60 секунд малы для гигабайтов.

file_id из Telegram

file_id и file_unique_id, полученные от api.telegram.org, в StaticGram не работают, и это ожидаемо. Идентификатор файла Telegram ссылается на файл в хранилище конкретного дата-центра Telegram и содержит его внутренние ключи (access_hash, file_reference). У StaticGram своё хранилище, своих копий файлов Telegram в нём нет, поэтому такой идентификатор не во что разрешить. Наоборот это тоже верно: file_id StaticGram не работают в Telegram.

Как перенести файлы бота из Telegram:

  1. Скачайте файл из Telegram (через api.telegram.org: getFile + /file/bot…).
  2. Загрузите его в StaticGram обычным multipart/form-data (до 2000 МБ) или передайте публичную HTTPS-ссылку (до 10 МБ).
  3. Сохраните новый file_id из ответа и дальше отправляйте файл по нему без повторной загрузки.

Ссылки вида https://api.telegram.org/file/bot<token>/… передавать как URL нельзя: в них токен вашего бота в Telegram.

Описания методов и типов взяты из официальной документации Telegram Bot API (Bot API 10.3). Адрес API: https://api.staticgram.top