Chatterino+

Chatterino+ public API v1

API для тех, кто хочет показывать в СВОЁМ чате (экранный чат для OBS, бот, расширение, клиент) то, что есть у подписчиков Chatterino+ PLUS: пейнты ников, значки перед ником и эффекты смайликов. Больше ничего API не даёт.

База: https://chat.eblo.id/api/v1. Только чтение, без ключей и входа. Ответы — JSON в UTF-8, Access-Control-Allow-Origin: *. Версия в адресе: несовместимые изменения выйдут как /api/v2, а /v1 продолжит работать. Новые поля в ответах могут появляться — неизвестные поля пропускайте.

Ошибки: {"error": "<код>", "message": "<текст>"} с HTTP-кодом 400/429/5xx. «Не найдено» у /plus/users и /plus/paints — обычный ответ 200 с null (не 404). Пределы частоты — по IP; при превышении 429 и заголовок Retry-After. Просите сжатие (Accept-Encoding: gzip, браузеры делают это сами): весь список подписчиков — ~35 КБ вместо ~185 КБ.

Остальные адреса сайта chat.eblo.id — внутренние, для нашего собственного экранного чата. Они не часть API и чужим страницам не отвечают.

Содержание: Как пользоваться бережно · Пределы · Подписчики PLUS · Каталог значков · Только изменения · Один подписчик · Пейнт · Живые изменения · Формат пейнта · Эффекты смайликов

Как пользоваться бережно

  1. При запуске — один раз GET /plus/roster; запомните version.
  2. Откройте живое соединение /plus/events и применяйте кадры user.
  3. В hello пришла другая версия списка или у кадра prev не равен вашей версии — вы пропустили изменения: GET /plus/roster?since=<ваша версия>. Обычно это несколько записей вместо всего списка.
  4. Без живого соединения (бот, сервер) — сверяйтесь не чаще раза в минуту тем же ?since= или If-None-Match.
  5. В hello другая версия каталога значков (badges) или у человека значок, которого нет в вашем каталоге, — GET /plus/badges.

Опрашивать весь список по таймеру не нужно: после каждой правки он меняется целиком, а изменения приходят сами.

Пределы

адресс одного IP
/plus/roster60 в минуту (сразу — до 30)
/plus/users, /plus/paints120 в минуту (сразу — до 60)
/plus/badges30 в минуту (сразу — до 10)
/plus/events10 соединений одновременно

Подписчики PLUS: GET /plus/roster

Все действующие подписчики одним ответом — вместе с их пейнтами и значками.

{
  "version": "3f9a1c0d2b7e4411",
  "users": [
    {"id": "47966045", "login": "nick", "badge": true, "badge_id": "m2", "months": 3, "paint": 42, "paint_v": 3},
    {"id": "11112222", "login": "other", "badge": false, "paint": null, "paint_v": 0}
  ],
  "paints": {
    "42": {"v": 3, "spec": {"type": "linear", "angle": 137, "stops": [[0, "#fcf9ff"], [1, "#9f73e6"]],
                             "shadows": [[0, 0, 8, "#9f73e6"]], "anim": {"kind": "slide", "speed": 3}}}
  },
  "badges": {
    "set": {
      "m1": {"title": "PLUS", "title_en": "PLUS", "kind": "month", "months": 1,
             "urls":  {"1x": "https://chat.eblo.id/chat/static/pb-m1-v1-dark-18.png",
                       "2x": "https://chat.eblo.id/chat/static/pb-m1-v1-dark-36.png",
                       "4x": "https://chat.eblo.id/chat/static/pb-m1-v1-dark-72.png"},
             "light": {"1x": "https://chat.eblo.id/chat/static/pb-m1-v1-light-18.png",
                       "2x": "https://chat.eblo.id/chat/static/pb-m1-v1-light-36.png",
                       "4x": "https://chat.eblo.id/chat/static/pb-m1-v1-light-72.png"}},
      "lead1": {"title": "Top-1 Leaderboard", "title_en": "Top-1 Leaderboard", "kind": "leader", "solo": true,
                "urls": {…}, "light": {…}}
    },
    "plus": {"title": "Chatterino+ PLUS", "urls": {…}}
  }
}

Каталог значков (badges.set)

полезначение
title, title_enподпись по-русски и по-английски
kindmonth — за стаж, event — праздничный (день рождения), special — особый, leader — место в таблице лидеров
monthsу month: с какого стажа он доступен
urlsкартинки для тёмного фона: 1x/2x/4x = 18/36/72 px
lightто же для светлого фона
soloподсказка — только подпись, без стажа

Подсказка у значка: title и, если нет solo и есть months у человека, — «N мес.». badge_id, которого нет в вашем каталоге (каталог обновился), — перекачайте /plus/badges, а пока рисуйте m1. В ответах до 09.11.2026 у стандартного значка не было badge_id — нет поля при badge: true значит m1. badges.plus — устаревшее (прежняя картинка), для старых клиентов.

Только изменения: GET /plus/roster?since=<версия>

since — версия вашего списка. Если сервер помнит изменения с неё:

{"version": "<нынешняя>", "since": "<ваша>",
 "changes": [{"login": "nick", "user": {…как в users…} | null, "paint": {"id": 42, "v": 3, "spec": {…}} | null}]}

По одной (последней) записи на человека; применяйте их как кадры user (ниже) и запомните новую version. since в ответе не равен вашей версии — скачайте весь список. Ваша версия совпадает с нынешней — changes: []. Если не помнит (перезапуск сервера, давно, слишком много изменений), приходит обычный полный ответ — отличайте по наличию users. Кэш 15 с.

Каталог значков: GET /plus/badges

{"version": "<версия каталога>", "default": "m1", "badges": {…как badges.set…}}. Меняется редко (с обновлением сервера); version — та же, что в hello живых изменений. Кэш 1 ч, ETag / If-None-Match → 304.

Один подписчик: GET /plus/users/{login_or_id}

{"user": {…как в roster…}, "paint": {"id": 42, "v": 3, "spec": {…}} | null, "badge": {"id": "m2", …как в каталоге…} | null}. Не подписчик — "user": null (код 200). Кэш 60 с. Для одного-двух человек; для всего чата берите список.

Пейнт: GET /plus/paints/{id}

{"id": 42, "v": 3, "spec": {…}}. Отдаются только пейнты, которые кто-то носит или которые опубликованы; нет такого или отклонён модерацией — {"id": 42, "v": 0, "spec": null} (код 200). Кэш 5 мин (нет такого — 1 мин).

Живые изменения: wss://chat.eblo.id/api/v1/plus/events

После подключения сервер присылает {"op": "hello", "version": "<версия списка>", "badges": "<версия каталога значков>"}, затем на каждое изменение:

{"op": "user", "login": "nick", "user": {…} | null, "paint": {"id": 42, "v": 3, "spec": {…}} | null,
 "version": "<после>", "prev": "<до>"}

Формат пейнта (spec)

Градиент (type: linear | radial)

полезначение
angle0–360, как у CSS linear-gradient(<угол>deg) (у radial не используется)
stops2–16 пар [позиция 0..1, "#rrggbb"]
tiles1–6: сколько раз рисунок повторяется по длине (нет поля — 1)
repeatустаревшее: true без tiles означает 3 повтора
shadowsдо 3 теней [dx, dy, blur, "#rrggbb"]: dx/dy −4…4, blur 0–8
anim{"kind": "none" | "slide" | "spin" | "pulse", "speed": секунд на цикл} (нет поля или speed < 0,5 — 6 с)

Как рисовать, чтобы совпадало с Chatterino+ и сайтом PLUS:

Картинка (type: image)

полезначение
imgадрес webp (может быть анимированным)
fitcover (заполнить, по центру) | tile (по высоте ника, повтор вбок) | stretch (растянуть)
w, hразмеры картинки
anim1 — картинка анимированная
shadowsкак у градиента

Рядом с картинкой лежит лёгкое превью первого кадра — тот же адрес с .p.webp: показывайте его, пока грузится основная картинка. Не загрузилась — рисуйте ник обычным цветом.

Общее

Эффекты смайликов: GET /effects

Справочник модификаторов: кто их пишет, где они стоят, кому доступны и что делают. Кэш 1 ч.

{"effects": [
  {"code": "w!",       "provider": "bttv", "position": "before", "applies_to": "third_party", "case_sensitive": true, "effect": "wide"},
  {"code": "ffzSpin",  "provider": "ffz",  "position": "after",  "applies_to": "any", "requires": "ffz_supporter", "effect": "spin"},
  {"code": "+spin",    "provider": "plus", "position": "before", "applies_to": "third_party", "case_sensitive": false, "requires": "plus_subscriber", "effect": "spin"}
]}
полезначение
codeслово в сообщении
providerbttv | ffz | plus
positionbefore — слово стоит перед смайликом, after — после
applies_tothird_party — только смайлики 7TV/BTTV/FFZ (не Twitch), any — любые
case_sensitiveучитывать ли регистр букв
requiresнет поля — доступно всем; plus_subscriber — автор есть в /plus/roster; ffz_supporter — автор поддержал FFZ (список у FFZ, набор «Subwoofer Emote Effects»)
effectчто сделать со смайликом (ниже)

Значения effect: wide — растянуть вчетверо в ширину; grow_x — вдвое; flip_x, flip_y — отразить по горизонтали / вертикали; rotate_left, rotate_right — повернуть на 90°; no_space — поставить вплотную к предыдущему, без пробела; cursed — обесцветить и затемнить; party — перелив цветов; rainbow — бегущий оттенок; hyper — красный оттенок и мелкая тряска; shake — тряска; spin — вращение; jam — покачивание; bounce — подпрыгивание; slide — бегущая дорожка; arrive — въезжает; leave — уезжает. Несколько модификаторов на одном смайлике складываются; повороты и отражения — нет (действует один).

← Настройка экранного чата