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 · Каталог значков · Только изменения · Один подписчик · Пейнт · Живые изменения · Формат пейнта · Эффекты смайликов
Как пользоваться бережно
- При запуске — один раз
GET /plus/roster; запомнитеversion. - Откройте живое соединение
/plus/eventsи применяйте кадрыuser. - В
helloпришла другая версия списка или у кадраprevне равен вашей версии — вы пропустили изменения:GET /plus/roster?since=<ваша версия>. Обычно это несколько записей вместо всего списка. - Без живого соединения (бот, сервер) — сверяйтесь не чаще раза в минуту тем же
?since=илиIf-None-Match. - В
helloдругая версия каталога значков (badges) или у человека значок, которого нет в вашем каталоге, —GET /plus/badges.
Опрашивать весь список по таймеру не нужно: после каждой правки он меняется целиком, а изменения приходят сами.
Пределы
| адрес | с одного IP |
|---|---|
/plus/roster | 60 в минуту (сразу — до 30) |
/plus/users, /plus/paints | 120 в минуту (сразу — до 60) |
/plus/badges | 30 в минуту (сразу — до 10) |
/plus/events | 10 соединений одновременно |
Подписчики 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": {…}}
}
}
id— идентификатор пользователя Twitch (строка),login— логин.badge: true— показывать значок последним перед ником, вплотную к нему (так он выглядит в Chatterino+);badge_id— какой: ключ вbadges.set. Уbadge: falseполяbadge_idнет — значка перед ником нет.- Значок человек меняет сам в любой момент (стаж, праздник, место в таблице лидеров,
особый) — правка приходит живым кадром
user. Не запоминайте значок навсегда и не выводите его из стажа сами — беритеbadge_id. months— стаж подписки в месяцах (нет поля — меньше месяца). Может отставать до ближайшей правки человека; годится для подсказки «N мес.».paint— номер пейнта илиnull; описание — вpaints,paint_v— версия (сменилась версия — перерисуйте ник).- Эффекты смайликов PLUS работают только у тех, кто есть в этом списке (см. эффекты смайликов).
- Кэш:
Cache-Control: public, max-age=30,ETag; поддерживаетсяIf-None-Match→304.
Каталог значков (badges.set)
| поле | значение |
|---|---|
title, title_en | подпись по-русски и по-английски |
kind | month — за стаж, 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": "<до>"}
- Кадр приходит на смену значка или пейнта и на начало или конец подписки.
user— запись человека целиком: замените прежнюю. user: null— человек больше не подписчик: уберите его пейнт и значок (ищите поlogin).paint— описание его пейнта: обновитеpaints.prevне совпадает с вашей версией списка — вы пропустили изменение:GET /plus/roster?since=<ваша версия>. То же — еслиversionвhelloотличается от вашей (например, после переподключения).- Каждые 20 с приходит
{"op": "ping"}. 50 с тишины — соединение мёртвое: переподключитесь (пауза 5–10 с со случайным разбросом, чтобы сотни чатов не стучались в одну секунду). - Присылать на сервер ничего не нужно. С одного IP — до 10 соединений одновременно: держите одно на приложение, а не на каждый канал.
Формат пейнта (spec)
Градиент (type: linear | radial)
| поле | значение |
|---|---|
angle | 0–360, как у CSS linear-gradient(<угол>deg) (у radial не используется) |
stops | 2–16 пар [позиция 0..1, "#rrggbb"] |
tiles | 1–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:
linear— как CSSlinear-gradient(angle, stops)по размеру ника;radial—radial-gradient(circle farthest-side at 50% 50%, stops).- Повтор (
tiles> 1) или перелив (slide): рисунок «замыкается зеркалом» — от первого цвета к последнему и обратно, период = 1/tiles, без шва на стыке. slide— рисунок сдвигается на один период заspeedсекунд;spin— уголlinearповорачивается на 360° заspeed;pulse— рисунок масштабируется от центра: 1 + 0,25·sin(2π·t).- Фаза анимации — от РЕАЛЬНОГО времени: t = (время в секундах mod
speed) /speed. Так перелив у всех зрителей и на сайте PLUS идёт в лад.
Картинка (type: image)
| поле | значение |
|---|---|
img | адрес webp (может быть анимированным) |
fit | cover (заполнить, по центру) | tile (по высоте ника, повтор вбок) | stretch (растянуть) |
w, h | размеры картинки |
anim | 1 — картинка анимированная |
shadows | как у градиента |
Рядом с картинкой лежит лёгкое превью первого кадра — тот же адрес с .p.webp:
показывайте его, пока грузится основная картинка. Не загрузилась — рисуйте ник обычным цветом.
Общее
- Ник — текст с заливкой пейнта (в вебе:
background-clip: textи прозрачный цвет текста). - Тени заданы в пикселях для шрифта 14 px — масштабируйте пропорционально размеру шрифта. Рисуйте их ОТДЕЛЬНЫМ неподвижным слоем под текстом, а не фильтром на анимированном нике: иначе размытие пересчитывается каждый кадр.
- Значок и пейнт показываются независимо: у подписчика может быть значок без пейнта и пейнт без значка.
Эффекты смайликов: 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 | слово в сообщении |
provider | bttv | ffz | plus |
position | before — слово стоит перед смайликом, after — после |
applies_to | third_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 — уезжает. Несколько модификаторов на одном смайлике складываются; повороты
и отражения — нет (действует один).