API v2: полная справка

Эта страница дополняет быстрый старт: здесь собраны все методы, полезные ответы и рекомендации, чтобы автоматизировать счётчики, таймеры и панели под ваш поток.

Что умеет API

Проверка работоспособности

{
  "ok": true,
  "version": "2.0",
  "status": "healthy",
  "timestamp": "2024-01-20T15:30:00Z"
}

Счётчики смертей

Любое изменение приходит по URL вида /api/v2/counter/{TOKEN}/{SLUG}/. Ниже — базовые операции.

Получаем текущее значение

{
  "ok": true,
  "counter": {
    "slug": "dark-souls",
    "name": "Dark Souls Deaths",
    "value": 42,
    "updated_at": "2024-01-20T15:30:00Z"
  },
  "timestamp": "2024-01-20T15:30:05Z"
}

Меняем значение

{
  "ok": true,
  "counter": {
    "slug": "dark-souls",
    "name": "Dark Souls Deaths",
    "value": 43,
    "updated_at": "2024-01-20T15:31:00Z"
  },
  "old_value": 42,
  "new_value": 43,
  "timestamp": "2024-01-20T15:31:00Z"
}

Обновляем сразу несколько счётчиков

{
  "operations": [
    {"slug": "dark-souls", "action": "increment", "value": 1},
    {"slug": "elden-ring", "action": "increment", "value": 1},
    {"slug": "bloodborne", "action": "reset"}
  ]
}

Таймеры

Структура аналогичная счётчикам. Используйте, если нужно запускать раны, отсчитывать время до события или паузить кат-сцены.

{
  "ok": true,
  "timer": {
    "slug": "speedrun",
    "name": "Speedrun Timer",
    "running": true,
    "elapsed_seconds": 125.342,
    "updated_at": "2024-01-20T15:33:00Z"
  },
  "timestamp": "2024-01-20T15:33:00Z"
}

Единое состояние

Вместо нескольких GET-запросов можно спросить всё сразу: счётчики, таймеры, сводку по стриму.

{
  "ok": true,
  "counters": [
    {"slug": "dark-souls", "name": "Dark Souls", "value": 43},
    {"slug": "elden-ring", "name": "Elden Ring", "value": 129}
  ],
  "timers": [
    {"slug": "speedrun", "name": "Speedrun", "running": true}
  ],
  "stream": {
    "live": true,
    "death_count": 43
  },
  "timestamp": "2024-01-20T15:34:00Z"
}

Панель управления

Для быстрого старта откройте готовую страницу или добавьте её в OBS как Browser Source.

Если получили ошибку

Ответы с ошибками выглядят одинаково:

{
  "ok": false,
  "error": "invalid_token",
  "message": "Токен отключён или не существует"
}

403 — invalid_token

Проверьте, что используете последний токен из раздела Integrations. Старые или отключённые токены блокируются мгновенно.

404 — not_found

Slug написан с ошибкой или сущность ещё не создана. Подсказку найдёте в карточке счётчика.

400 — bad_request

Чаще всего забыли указать поле value для действия set или отправили некорректный JSON.

Примеры кода

Python

import requests

TOKEN = "YOUR_TOKEN"
BASE_URL = "https://vsestream.live/api/v2"

def increment_counter(slug, value=1):
    resp = requests.post(
        f"{BASE_URL}/counter/{TOKEN}/{slug}/",
        json={"action": "increment", "value": value}
    )
    data = resp.json()
    if data.get("ok"):
        print("Counter", data["counter"]["value"])
    else:
        print("Error", data.get("error"))

increment_counter("dark_souls", 1)

JavaScript / Node.js

const TOKEN = "YOUR_TOKEN";
const BASE_URL = "https://vsestream.live/api/v2";

async function incrementCounter(slug, value = 1) {
  const response = await fetch(`${BASE_URL}/counter/${TOKEN}/${slug}/`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ action: 'increment', value })
  });

  const data = await response.json();
  if (!data.ok) {
    throw new Error(`${data.error}: ${data.message}`);
  }
  return data.counter.value;
}

incrementCounter('dark_souls').then(console.log);

cURL

# Увеличить счётчик
curl -X POST "https://vsestream.live/api/v2/counter/TOKEN/SLUG/" \
  -H "Content-Type: application/json" \
  -d '{"action":"increment","value":1}'

# Получить текущее значение
curl "https://vsestream.live/api/v2/counter/TOKEN/SLUG/"

Советы по внедрению

Обрабатывайте ошибки

async function safeAPICall(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    if (!data.ok) {
      console.error('API error:', data.error, data.message);
      return null;
    }
    return data;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

Не спамьте запросами

Если кнопка нажимается много раз подряд, заверните обработчик в debounce/throttle, чтобы не забить очередь запросов.

Используйте batch там, где можно

Один пакетный POST вместо трёх отдельных — меньше задержка и нагрузка.

Если переходите с v1

Подробные шаги есть в руководстве по миграции. Вкратце:

• Меняем пути /integrations/overlay/api/ на /api/v2/.
• Действия выполняем POST-запросами с JSON телом.
• Читаем числа прямо из ответа JSON, а не из HTML.
• Используем готовые действия decrement, set и пакетные операции.

Версия справки: API v2 Full v2. Содержимое актуально на октябрь 2025.