Guutrix

TG API

1. Обзор

Базовый URL: https://tg-api.guutrix.ru. Все эндпоинты возвращают JSON в UTF-8.

2. Аутентификация и ключи

В каждом запросе передавайте заголовок Authorization: Bearer ВАШ_КЛЮЧ. Формат ключа: gtx_tg_<64 hex>.

Ключ вы создаёте сами в TG веб-панели → раздел «API доступ»

curl — список каналов
curl https://tg-api.guutrix.ru/api/tg/v1/channels \
  -H "Authorization: Bearer gtx_tg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Формат ответов и ошибки

Успех:

{ "ok": true, "data": { ... } }

Ошибка:

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Этот канал не в ваших личных каналах (Мои каналы)"
  }
}

Коды ошибок:

VALIDATION_ERROR400Некорректное тело запроса
UNAUTHORIZED401Нет/неверный ключ
FORBIDDEN403Нет личного лимита или канал не в личном лимите
NOT_FOUND404Канал/задача не найдены
CONFLICT409Зрители уже запущены / конфликт настроек
RATE_LIMIT_EXCEEDED429Превышен лимит запросов на ключ
API_DISABLED503API временно выключен
SERVICE_UNAVAILABLE503Сервис зрителей недоступен

4. Лимиты запросов

Лимит задаётся на каждый ключ (по умолчанию 60 запросов в минуту, настраивается в панели). При превышении возвращается 429 с заголовками Retry-After, X-RateLimit-Reset. Тело запроса ограничено 32 КБ.

5. Каналы

GET/api/tg/v1/channels

Список ваших личных каналов + занятость личного лимита онлайна.

Пример ответа:

{
  "ok": true,
  "data": {
    "personalOnlineLimit": 1000,
    "currentPersonalOnline": 250,
    "available": 750,
    "channels": [
      {
        "id": 12,
        "channelName": "my_channel",
        "viewersCount": 300,
        "task": { "id": 88, "status": "ACTIVE", "streamOnline": true,
                  "viewersCount": 300, "activeViewersCount": 298 }
      }
    ]
  }
}
POST/api/tg/v1/channels

Добавить личный канал. Минимум 15 зрителей.

Тело запроса:

{ "channelName": "my_channel", "viewersCount": 300 }
PATCH/api/tg/v1/channels/:id

Изменить желаемое кол-во зрителей / настройки.

Тело запроса:

{
  "viewersCount": 350,
  "settings": { "rampUpMinutes": 5, "uniqueRatio": 3, "listPercent": 100 },
  "accountListId": 4
}
DELETE/api/tg/v1/channels/:id

Удалить личный канал. Нельзя, пока на нём идёт онлайн-задача — сначала остановите зрителей.

6. Зрители

POST/api/tg/v1/viewers/start

Запустить зрителей.

Тело запроса:

{ "channelName": "my_channel" }

Пример ответа:

{
  "ok": true,
  "data": {
    "task": { "id": 88, "channelName": "my_channel",
              "viewersCount": 300, "actualViewersCount": 250, "partial": true },
    "online": true, "started": true, "rampUpMinutes": 5
  }
}
POST/api/tg/v1/viewers/stop

Полностью остановить зрителей на канале

Тело запроса:

{ "channelName": "my_channel" }
POST/api/tg/v1/viewers/modify

Изменение работающей задачи: количество, распределение в рейд, плавающий онлайн.

Тело запроса:

{
  "channelName": "my_channel",
  "viewersCount": 350,
  "listPercent": 100,
  "raidPercent": 80,
  "fluctuationMode": "range",
  "fluctuationMinViewers": 280,
  "fluctuationMaxViewers": 360,
  "fluctuationIntervalSeconds": 600
}
Guutrix TG API