API Keys Setup RU

Настройка API ключей

Tonkatsu Box использует бесплатные API для получения данных об играх и фильмах. Все ключи бесплатны и настраиваются за несколько минут.

IGDB - для игр (рекомендуется)

IGDB принадлежит Twitch (Amazon), поэтому нужен аккаунт разработчика Twitch.

Пошаговая инструкция

1. Перейдите на dev.twitch.tv/console и войдите (или создайте бесплатный аккаунт Twitch)

2. Нажмите Register Your Application
3. Заполните форму:
   • Name: что угодно (например, "my-tonkatsu")
   • OAuth Redirect URLs: http://localhost
   • Category: Application Integration
4. Нажмите Create
5. Откройте созданное приложение → скопируйте Client ID
6. Нажмите New Secret → скопируйте Client Secret

7. В Tonkatsu Box: перейдите в Настройки → API ключи
8. Вставьте Client ID и Client Secret в секцию IGDB
9. Нажмите Проверить подключение

✅ Готово! Теперь у вас доступ к 250 000+ игр на 220 платформах.

Решение проблем

• «Ошибка подключения»: Проверьте что скопировали оба значения без лишних пробелов
• «Не подключено»: Токен мог истечь - нажмите «Проверить подключение» ещё раз
• Twitch просит 2FA: Возможно нужно включить двухфакторную аутентификацию в настройках Twitch

TMDB - для фильмов, сериалов и аниме (рекомендуется)

1. Перейдите на themoviedb.org и создайте бесплатный аккаунт
2. В профиле TMDB: Settings → API
3. Нажмите Request an API Key → выберите Developer
4. Заполните форму (любые данные - для личного использования)
5. Скопируйте API Key (v3 auth)
6. В Tonkatsu Box: Настройки → API ключи → секция TMDB → вставьте ключ

✅ Готово! Теперь доступен поиск фильмов, сериалов и аниме.

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

Язык контента

После настройки TMDB можно выбрать язык описаний фильмов и сериалов:

Настройки → Язык контента → English или Русский

Это влияет на язык названий, описаний и жанров из TMDB.

TheTVDB - второй источник фильмов и сериалов (опционально)

TheTVDB отвечает наравне с TMDB в поиске фильмов и сериалов, а его сериалы приносят собственные сезоны и эпизоды в трекер эпизодов.

1. Зайдите на thetvdb.com и создайте бесплатный аккаунт
2. Откройте thetvdb.com/api-information и запросите ключ v4
3. Скопируйте ключ
4. В Tonkatsu Box: Настройки → API ключи → TheTVDB API (фильмы и сериалы) → вставьте ключ → Проверить

Кнопка проверки выполняет настоящий вход, поэтому неверный ключ сообщит о себе сразу. Действие Сброс возвращает встроенный ключ.

Примечания

• У TheTVDB нет пользовательского рейтинга, только показатель популярности, - у его тайтлов нет значка оценки.
• Фильтры жанра и года работают в режиме просмотра. Поисковый эндпоинт TheTVDB не принимает фильтры, поэтому с введённым запросом они не сужают выдачу.
• Без ключа два чипа TheTVDB стартуют выключенными, а не падают на каждом запросе.
• Фильмы теперь мультиисточниковые: один и тот же фильм может прийти из TMDB и из TheTVDB, и они ведутся как отдельные записи. После обновления до 0.42 обложки фильмов один раз перекачиваются заново, потому что кеш обложек разделён по источникам.

SteamGridDB - для арта игр на досках (опционально)

1. Перейдите на steamgriddb.com и создайте бесплатный аккаунт
2. Перейдите в Preferences → API
3. Скопируйте ваш API Key
4. В Tonkatsu Box: Настройки → API ключи → секция SteamGridDB → вставьте

✅ Готово! Теперь можно добавлять качественный игровой арт на визуальные доски.

💡 Приложение имеет встроенный ключ SteamGridDB. Свой ключ опционален.

ScreenScraper - расширенные медиа для игр (опционально)

ScreenScraper даёт дополнительные изображения, которых нет в IGDB: оригинальные обложки коробок (лицевая и задняя), 3D-рендеры коробок, wheel/marquee-арт, тайтл-экраны, скриншоты из игр, фан-арт, mix-рендеры. Покрывает 52 ретро- и современных платформы (от NES до PS4, Saturn, Dreamcast, аркады, портативки и т.д.).

В приложение зашиты dev-ключи разработчика, поэтому интеграция работает «из коробки», но для запросов к API нужно завести бесплатный пользовательский аккаунт.

Пошагово

1. Перейдите на screenscraper.fr и нажмите Inscription (вверху справа) для создания бесплатного аккаунта
2. Подтвердите email
3. В Tonkatsu Box: Настройки → API ключи → секция ScreenScraper
4. Введите ваш ssid (логин на screenscraper.fr) и sspassword
5. Нажмите Проверить квоту - увидите уровень аккаунта, суточный лимит и лимит в минуту

✅ Готово! На экране деталей любой игры с поддерживаемой платформы появится галерея с дополнительными изображениями.

Заметки

• Бесплатные участники получают 20 000 запросов в сутки и один параллельный поток - этого с запасом хватает на обычный просмотр. Результаты кешируются на 30 дней, повторное открытие той же игры не делает сетевого запроса.
• Случай «игра не найдена» тоже кешируется - приложение не пытается перепрашивать.
• Если на экране игры галереи нет, либо платформа не в списке поддерживаемых, либо название игры не сопоставилось с записями ScreenScraper.

Comic Vine - для комиксов и графических романов (опционально)

Comic Vine добавляет источник Comics в таб поиска по книгам: большой каталог серий комиксов и графических романов (volumes) с издателями, годами выхода, количеством выпусков, обложками, авторами и персонажами.

Встроенного ключа нет, поэтому источник Comics остаётся пустым, пока вы не добавите свой бесплатный ключ.

Пошагово

1. Перейдите на comicvine.gamespot.com и создайте бесплатный аккаунт (Sign Up, вверху справа). Comic Vine входит в сеть GameSpot, поэтому подойдёт и существующий аккаунт GameSpot/Fandom
2. Войдя в аккаунт, откройте страницу API: comicvine.gamespot.com/api
3. Ваш персональный API key показан вверху этой страницы - скопируйте его

4. В Tonkatsu Box: Настройки → API ключи → секция ComicVine → вставьте ключ
5. Нажмите Test для проверки - должно появиться "ComicVine API key is valid"

✅ Готово! Откройте Поиск → Книги, и источник Comics начнёт выдавать результаты.

Заметки

• Бесплатный ключ ограничен 200 запросами в час. Обычный просмотр укладывается с большим запасом.
• Данные Comic Vine разрешены только для некоммерческого использования.
• Комиксы отображаются внутри таба поиска Книги рядом с OpenLibrary и Fantlab, а не отдельным табом.

Hardcover - для книг (опционально)

Hardcover добавляет источник книг в таб поиска по книгам и позволяет импортировать библиотеку Hardcover в коллекцию. Нужен бесплатный персональный ключ доступа.

Пошагово

1. Перейдите на hardcover.app и войдите (или создайте бесплатный аккаунт)
2. Откройте настройки аккаунта
3. Скопируйте ваш персональный ключ доступа
4. В Tonkatsu Box: Настройки → API ключи → секция Hardcover → вставьте ключ
5. Нажмите Test для проверки - должно появиться "Hardcover API token is valid"

✅ Готово! Откройте Поиск → Книги, и источник Hardcover начнёт выдавать результаты. Также можно импортировать библиотеку из Настройки → Импорт → Hardcover.

Заметки

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

Podcast Index - для подкастов (опционально)

Podcast Index - каталог подкастов за вкладкой «Аудио»: поиск подкастов, списки в тренде и лента эпизодов, с которой сохраняется каждый подкаст. В релизных сборках есть встроенная пара ключей, поэтому подкасты работают сразу; своя пара нужна, чтобы отделить своё использование от общего.

По шагам

1. Зайдите на api.podcastindex.org и зарегистрируйтесь
2. Скопируйте API key и API secret со страницы аккаунта
3. В Tonkatsu Box: Настройки → API ключи → Podcast Index API → вставьте оба
4. Нажмите Проверить - должно появиться «Ключи Podcast Index действительны»

Мастер первого запуска спрашивает ту же пару.

Заметки

• Podcast Index подписывает каждый запрос текущим временем, поэтому сбитые на несколько минут системные часы приводят к отказу. Сначала проверьте часы, потом ключи.
• Пара уезжает вместе с дампом настроек и с полной резервной копией.
• На selfhost-сборке запросы подписывает сервер, и секрет не попадает в браузер.

Без ключа

Эти источники работают без API ключей:

Источник	Что предоставляет
VNDB	Визуальные новеллы - поиск, теги, рейтинги
AniList	Аниме и манга - поиск, жанры/формат, прогресс
Kitsu	Аниме и манга - поиск, обзор, данные по каждой серии для трекера
MangaBaka	Манга, манхва, маньхуа, ранобэ - поиск и обзор
MangaDex	Манга - поиск, обзор, локализованные названия, число глав
TVmaze	Сериалы - поиск по названию, сезоны, серии, календарь релизов
OpenLibrary	Книги - поиск по названию или автору, обложки, описания
Fantlab	Книги - поиск, издания со своими обложками, похожие тайтлы
MusicBrainz	Музыка - альбомы, исполнители, издания и треклисты, обложки из Cover Art Archive
Готовые коллекции	.xcollx файлы с полными библиотеками - полностью оффлайн

Импортам из Steam, RetroAchievements и Simkl тоже нужен ключ или вход, но это делается на их собственных экранах импорта, а не здесь. См. Импорт из Steam, Импорт из RetroAchievements и Импорт из Simkl.

Сводная таблица

Источник	Для чего	Нужен ключ?	Время настройки
IGDB	Игры (250K+ тайтлов)	Да (бесплатный токен Twitch)	~2 мин
TMDB	Фильмы, сериалы, аниме	Да (бесплатный) или встроенный	~3 мин
TheTVDB	Фильмы, сериалы (второй источник, свои эпизоды)	Бесплатный ключ v4 или встроенный	~2 мин
SteamGridDB	Арт игр для досок	Опционально (есть встроенный)	~1 мин
ScreenScraper	Расширенные медиа для игр (52 платформы)	Бесплатный аккаунт на screenscraper.fr	~2 мин
Comic Vine	Комиксы и графические романы	Бесплатный ключ (без встроенного)	~2 мин
Hardcover	Книги (поиск + импорт библиотеки)	Бесплатный ключ доступа (без встроенного)	~2 мин
Podcast Index	Подкасты (поиск + ленты эпизодов)	Бесплатная пара ключ/секрет или встроенная	~2 мин
VNDB	Визуальные новеллы	Нет	-
AniList / Kitsu	Аниме, манга	Нет	-
MangaBaka / MangaDex	Манга	Нет	-
TVmaze	Сериалы	Нет	-
OpenLibrary / Fantlab	Книги	Нет	-
MusicBrainz	Музыкальные альбомы	Нет	-
Simkl	Импорт фильмов, сериалов и аниме	Нет - вход по коду на экране импорта	~1 мин