Guutrix API

1. Обзор

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

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

Для каждого запроса передавайте заголовокAuthorization: Bearer YOUR_KEY. Ключ выдаётся администратором (запросите в поддержке).

Формат ключа: gtx_live_<64 hex>.

curl

curl https://api-v1.guutrix.ru/api/v1/me \
  -H "Authorization: Bearer gtx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

Успех:

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

Ошибка:

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Недостаточно средств на балансе",
    "details": { "required": 12.5 }
  }
}

Коды ошибок

code	HTTP	Когда
INVALID_REQUEST	400	Невалидные параметры запроса (формат, types)
INVALID_BODY	400	Невалидный JSON в теле
PAYLOAD_TOO_LARGE	413	Тело запроса слишком большое
VALIDATION_ERROR	400	Не прошла валидация (превышены лимиты, неверный формат)
UNAUTHORIZED	401	Нет/неверный/отозванный/просроченный API-ключ
FORBIDDEN	403	аккаунт заблокирован/неверифицирован
NOT_FOUND	404	Эндпоинт не существует или заказ не найден
INSUFFICIENT_FUNDS	402	Недостаточно средств на балансе
CONFLICT	400	Превышен лимит активных заказов
ORDER_CONFLICT	422	Система отклонила изменение
IDEMPOTENCY_CONFLICT	409	Idempotency-Key переиспользован с другим телом
RATE_LIMIT_EXCEEDED	429	Превышен лимит запросов
BAD_GATEWAY	502	Сервер недоступен
API_DISABLED	503	API временно отключен
INTERNAL_ERROR	500	Внутренняя ошибка — обратитесь в поддержку с X-Request-Id

4. Лимиты

Авторизация: обязательна для всех эндпоинтов API — каждый запрос должен содержать заголовок Authorization: Bearer ....
Размер тела: до 64 KB. Превышение — 413 PAYLOAD_TOO_LARGE. Для нашего API любой осмысленный запрос укладывается в единицы килобайт.
Idempotency-Key (необязателен, но рекомендуется): для POST/PATCH можно передавать уникальный Idempotency-Key: <uuid> (8–128 символов). Ответ будет закэширован на 24 часа: повтор с тем же ключом и телом — одинаковый результат, повтор с тем же ключом и другим телом — 409 IDEMPOTENCY_CONFLICT. Используйте для безопасных ретраев при сетевых таймаутах.
Каждый ответ содержит X-Request-Id — указывайте его при обращениях в поддержку.

5. Эндпоинты

GET/api/v1/me

Сводка по ключу и владельцу: id, имя ключа, префикс, лимиты, баланс. Email возвращается в маскированном виде (например, u***@example.com).

GET/api/v1/balance

Текущий баланс пользователя

GET/api/v1/pricing

Цены на все услуги Twitch и параметры (мин/макс, шаги, скидка).

GET/api/v1/orders

Список ваших заказов.

Параметр	Тип	Обяз.	Описание
status	string	нет	PENDING\|PROCESSING\|ACTIVE\|COMPLETED\|CANCELLED\|FAILED
limit	number	нет	1-100, default 50
before	number	нет	ID, заказы более старые которого нужно вернуть. Передавайте сюда поле nextBefore из предыдущего ответа.

GET/api/v1/orders/{id}

Один заказ по ID.

POST/api/v1/orders/twitch/viewers

Создать заказ зрителей Twitch.

Параметр	Тип	Обяз.	Описание
channel	string	да	Имя канала
viewers	number	да	Количество зрителей, см. /pricing
viewersInList	number	нет	Количество зрителей в списке
viewsPerHour	number	нет	Просмотры/час от 1 зрителя (0 — выкл)
rampUpMinutes	number	нет	Время подключения в минутах (0..60)
duration	number	да	Длительность в минутах (для isPerMinute=false)
isPerMinute	boolean	нет	Поминутная оплата (default false)
uniqueRatio	number	нет	Доля уникальных зрителей. Допустимы только: 1 (100%), 2 (50%), 3 (33%), 4 (25%)

curl

curl -X POST https://api-v1.guutrix.ru/api/v1/orders/twitch/viewers \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-05-07-001" \
  -d '{
    "channel": "channel",
    "viewers": 100,
    "viewersInList": 50,
    "viewsPerHour": 120,
    "rampUpMinutes": 5,
    "duration": 60
  }'

POST/api/v1/orders/twitch/followers

Создать заказ фолловеров Twitch.

Параметр	Тип	Обяз.	Описание
channel	string	да	Имя канала или URL
followers	number	да	Количество фолловеров
followIntervalMs	number	нет	Интервал между фолловами в мс (0 — авто)
followOnlyWhenOnline	boolean	нет	Фолловить только когда стрим online

POST/api/v1/orders/twitch/recording-views

Накрутка просмотров на запись стрима (VOD).

Параметр	Тип	Обяз.	Описание
recordingUrl	string	да	Ссылка на запись стрима или клип
recordingViews	number	да	Количество просмотров, см. /pricing

PATCH/api/v1/orders/{id}

Изменить параметры активного заказа

Параметр	Тип	Обяз.	Описание
viewers	number	нет	Количество зрителей
viewersInList	number	нет	Количество зрителей в списке
raidPercent	number	нет	0-100
raidDisconnectPerMinutePercent	number	нет	0-100
raidKeepPercent	number	нет	0-100
fluctuationPercent	number	нет	0 (выкл) или 10-50
fluctuationIntervalSeconds	number	нет	0 (выкл) или ≥240

POST/api/v1/orders/{id}/extend

Продлить активный заказ

Параметр	Тип	Обяз.	Описание
extendMinutes	number	да	См. лимиты из /pricing

GET/api/v1/orders/{id}/follow-progress

Прогресс фолловеров для заказа. Возвращает текущее/целевое количество, процент выполнения и статус стрима.

Ответ

{
  "ok": true,
  "data": {
    "orderId": 123,
    "status": "ACTIVE",
    "followers": 200,
    "followersCompleted": 87,
    "progressPercent": 43.5,
    "followOnlyWhenOnline": true,
    "streamOnline": true,
    "updatedAt": "2026-05-18T21:30:00.000Z"
  }
}

POST/api/v1/orders/{id}/cancel

Отменить активный заказ. Деньги не возвращаются.

6. Примеры

JavaScript (fetch)

const res = await fetch("https://api-v1.guutrix.ru/api/v1/orders/twitch/viewers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.GUUTRIX_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    channel: "channel",
    viewers: 100,
    duration: 60,
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error.message);
console.log("Order:", data.data);

Python (requests)

import os, uuid, requests

resp = requests.post(
    "https://api-v1.guutrix.ru/api/v1/orders/twitch/followers",
    headers={
        "Authorization": f"Bearer {os.environ['GUUTRIX_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"channel": "channel", "followers": 200},
    timeout=30,
)
data = resp.json()
if not data["ok"]:
    raise RuntimeError(data["error"]["message"])
print("Order:", data["data"])