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_ERROR`	400	Некорректное тело запроса
`UNAUTHORIZED`	401	Нет/неверный ключ
`FORBIDDEN`	403	Нет личного лимита или канал не в личном лимите
`NOT_FOUND`	404	Канал/задача не найдены
`CONFLICT`	409	Зрители уже запущены / конфликт настроек
`RATE_LIMIT_EXCEEDED`	429	Превышен лимит запросов на ключ
`API_DISABLED`	503	API временно выключен
`SERVICE_UNAVAILABLE`	503	Сервис зрителей недоступен

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

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

5. Каналы

Канал опознаётся парой «имя + площадка». Площадка передаётся полем platform (twitch по умолчанию).

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

GET/api/tg/v1/channels?platform=kick

Каналы ваших активных подписок Kick. Личного лимита у этой площадки нет — потолок зрителей задаёт тариф.

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

{
  "ok": true,
  "data": {
    "platform": "kick",
    "channels": [
      {
        "channelName": "my-kick-channel",
        "viewersCount": 300,
        "expiresAt": "2026-09-01T00:00:00.000Z",
        "planName": "Kick 300",
        "task": { "id": 91, "status": "ACTIVE", "streamOnline": true,
                  "viewersCount": 300, "activeViewersCount": 300 }
      }
    ]
  }
}

GET/api/tg/v1/geo

Доступные страны для просмотров.

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

{
  "ok": true,
  "data": {
    "enabled": true,
    "default": "RU",
    "countries": [
      { "code": "RU", "name": "Россия" },
      { "code": "KZ", "name": "Казахстан" }
    ]
  }
}

GET/api/tg/v1/view-targeting

Группы источника просмотров

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

{
  "ok": true,
  "data": {
    "enabled": true,
    "groups": [
      {
        "key": "platform",
        "label": "Платформа",
        "enabled": true,
        "options": [
          { "key": "web", "label": "Полная версия (ПК)" },
          { "key": "ios", "label": "iOS" }
        ],
        "defaults": { "web": 38, "android": 28, "mobile": 15, "ios": 14, "other": 5 }
      },
      { "key": "source", "label": "Источник в Twitch", "enabled": true, "options": [], "defaults": {} },
      { "key": "external", "label": "Источник вне Twitch", "enabled": false, "options": [], "defaults": {} }
    ]
  }
}

POST/api/tg/v1/channels

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

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

{ "channelName": "my_channel", "viewersCount": 300 }

PATCH/api/tg/v1/channels/:id

Изменить желаемое кол-во зрителей / настройки личного канала (только Twitch). Настройки канала Kick меняются в панели.

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

{
  "viewersCount": 350,
  "settings": {
    "rampUpMinutes": 5, "uniqueRatio": 3, "listPercent": 100,
    "geo": { "percents": { "RU": 50, "KZ": 50 } },
    "viewTargeting": {
      "platform": { "web": 60, "android": 25, "ios": 15 },
      "source": { "followers": 50, "search": 30, "page_view": 20 }
    }
  },
  "accountListId": 4
}

DELETE/api/tg/v1/channels/:id

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

6. Зрители

POST/api/tg/v1/viewers/start

Запустить зрителей. Без platform — личный канал Twitch; с platform: kick — канал вашей активной подписки Kick.

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

{ "channelName": "my_channel" }
{ "channelName": "my-kick-channel", "platform": "kick" }

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

{
  "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" }
{ "channelName": "my-kick-channel", "platform": "kick" }

POST/api/tg/v1/viewers/modify

Изменение работающей задачи: количество, распределение в рейд, плавающий онлайн. У Kick доступны только количество и плавающий онлайн — listPercent и raid* игнорируются.

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

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

{
  "channelName": "my-kick-channel",
  "platform": "kick",
  "viewersCount": 350,
  "fluctuationMode": "range",
  "fluctuationMinViewers": 280,
  "fluctuationMaxViewers": 360
}

7. Обозначения полей

Ниже расшифрованы все поля, которые встречаются в ответах и в телах запросов. Названия и диапазоны совпадают с настройками в TG веб-панели → «Мои каналы».

7.1. Поля ответов (статус)

Поле	Где встречается	Что означает
`personalOnlineLimit`	GET /channels	Личный лимит онлайна — максимум одновременных зрителей суммарно по всем вашим личным каналам.
`currentPersonalOnline`	GET /channels	Сколько зрителей из лимита сейчас занято активными задачами.
`available`	GET /channels	Свободный остаток лимита: personalOnlineLimit − currentPersonalOnline.
`channelName`	везде	Имя канала.
`viewersCount`	канал / задача	Количество зрителей. Минимум 15.
`activeViewersCount`	task	Сколько зрителей реально подключено в этот момент.
`actualViewersCount`	viewers/start	Сколько фактически удалось запустить (может быть меньше — см. partial).
`partial`	viewers/start	true — часть зрителей подключится позже; actualViewersCount показывает, сколько идёт сейчас.
`status`	task	ACTIVE — зрители идут; MONITORING — задача ждёт появления стрима; STOPPED — остановлена.
`streamOnline`	task	true — стрим сейчас в эфире, false — офлайн.
`online / started`	viewers/start	online — стрим в эфире; started — зрители стартовали.
`rampUpMinutes`	viewers/start	За сколько минут зрители плавно набираются до заказанного числа.
`viewsPerHourConfig`	GET /channels	Настройка «Просмотры в час».
`channelSettings`	GET /channels	Объект с сохранёнными настройками по каждому каналу.

7.2. Параметры настроек канала

Важно: способ применения зависит от эндпоинта, а не только от поля. PATCH /channels/:id только сохраняет настройки в канал — они вступают в силу со следующего запуска зрителей и не меняют уже идущую задачу. Применить изменения к работающей задаче сразу можно только через POST /viewers/modify. Колонка «Применение» показывает, в каком эндпоинте поле доступно: PATCH — только в PATCH /channels/:id (со следующего старта); modify — только в POST /viewers/modify (сразу); PATCH + modify — поле есть в обоих (в PATCH — со старта, в modify — сразу).

Параметр	Диапазон / по умолчанию	Применение	Что означает
`uniqueRatio`	1 / 2 / 3 / 4 (по умолч. 3)	PATCH	«Уникальные зрители»: 1 = 100%, 2 = 50%, 3 = 33%, 4 = 25% уникальных.
`rampUpMinutes`	0–60 мин (0)	PATCH	«Время подключения»
`listPercent`	0–100% (100)	PATCH + modify	«Зрителей в списке»
`raidPercent`	0–100% (80)	PATCH + modify	«Процент в рейд» — какая доля зрителей уходит в рейд.
`raidDisconnectPerMinutePercent`	0–100% (0 = по умолч.)	PATCH + modify	«Откл/мин (рейд)» — сколько % рейда отключается каждую минуту.
`raidKeepPercent`	0–100% (0)	PATCH + modify	«Останется до конца» — доля рейда, остающаяся до конца. Не больше 100 − откл/мин.
`fluctuationMode`	"percent" / "range"	PATCH + modify	Режим «плавающего онлайна»: колебания процентом или по диапазону зрителей.
`fluctuationPercent`	0 = выкл, 10–30%	PATCH + modify	Процент плавающего онлайна в режиме percent.
`fluctuationMinViewers`	от 10	PATCH + modify	Нижняя граница онлайна в режиме range.
`fluctuationMaxViewers`	до personalOnlineLimit	PATCH + modify	Верхняя граница онлайна в режиме range.
`fluctuationIntervalSeconds`	0 = выкл, 240–1800 сек (4–30 мин)	PATCH + modify	«Интервал обновления» — как часто обновляется плавающий онлайн.
`adminViewsPerHour`	0 = выкл,	PATCH	«Просмотры в час».
`adminViewsPerHourMode`	"per_viewer" \| "absolute"	PATCH	Режим просмотров: per_viewer (по умолчанию) — число умножается на количество зрителей; absolute — число это просмотры в час целиком. В режиме absolute, если владелец включил коэффициентный лимит, итоговые просмотры/час дополнительно ограничиваются сверху динамически (не более coefMax × текущий онлайн канала).
`geo`	{ "percents": { … } }	PATCH	«Гео просмотров» — из каких стран идут зрители. Задаётся как percents — доли по странам в процентах, например { RU:50, KZ:50 } = половина зрителей из России, половина из Казахстана. Коды берите из GET /geo. Если гео не задавать, по умолчанию используется Россия.
`viewTargeting`	{ "platform": { … }, "source": { … }, "external": { … } }	PATCH	«Источник просмотров» — с какой платформы и откуда приходят зрители. Три независимые группы, в каждой доли в процентах: platform (web/ios/android/…), source — источник внутри Twitch (followers/search/…), external — реферер вне Twitch (google.com/youtube.com/…). Слать можно только группы и ключи из GET /view-targeting.