TGifts API
Все запросы — GET, без ключа. Базовый путь: /api/v1/gifts/{model}/{number}, например /api/v1/gifts/PlushPepe/1/backdrop. Регистр в названии модели не важен.
Картинки
| Путь | Что отдаёт |
|---|---|
/image | Подарок с фоном, узором и номером в рамке из жидкого стекла. |
/image/table | То же самое и таблица характеристик снизу. |
Параметр ?format=png (по умолчанию) или webp. Прозрачные углы, ширина 1680 px.
Владелец
| Путь | Что отдаёт |
|---|---|
/owner/username MTProto | {username, type, hidden} |
/owner/id MTProto | {id, type, hidden}. type: user, channel или chat. id — строка. |
/owner/name | {name, hidden}. Имя отдаётся и для скрытого владельца. Без MTProto hidden равен null. |
/owner/wallet | {on_chain, address, domain} |
Характеристики
| Путь | Что отдаёт |
|---|---|
/model | {name, sticker_url, chance} |
/backdrop | {name, colors: {center, edge, pattern, text}, chance} |
/symbol | {name, pattern_url, chance} |
/chance/model | {name, percent, permille, fraction, tier} |
/chance/backdrop | То же для фона. |
/chance/symbol | То же для символа. |
/chance/combined | Произведение вероятностей: {probability, percent, one_in, factors}. |
/crafted MTProto | {crafted, burned}. burned: подарок потрачен на крафт другого. |
/exists | {exists} |
/ | Всё сразу. Поля, для которых нужен MTProto, будут null, если он не настроен. |
Ссылки sticker_url и pattern_url временные: их выдаёт Telegram, не храните их долго.
Список коллекций
/api/v1/collections отдаёт [{slug, name, thumb}]. Список обновляется каждые 15 минут. Новые коллекции появляются из каталога Telegram и стоят в начале.
Ответы
{ "ok": true, "slug": "PlushPepe-1", "result": { "exists": true } }
{ "ok": false, "error": { "code": "gift_not_found", "message": "This gift does not exist" } }
| Код | Когда |
|---|---|
404 gift_not_found | Такого подарка нет. |
429 rate_limited | Превышен лимит на IP: 120 в минуту, запрос картинки стоит 10. Смотри заголовок Retry-After. |
503 upstream_unavailable | Telegram временно не отдал данные. Сервер повторяет запрос, поэтому эта ошибка может прийти только через 1–1,5 минуты. |
503 mtproto_not_configured | Поле доступно только через MTProto, а он не настроен. |
503 flood_wait | Telegram просит подождать. Смотри Retry-After. |
Данные кэшируются на 10 минут, поэтому смена владельца появляется с такой задержкой.