Документация API — Руководство по интеграции

Модель URL

У dice83 нет традиционного REST API, возвращающего JSON. Каждый URL отдаёт полноценную HTML-страницу с предварительно настроенным инструментом. Затем ваш браузер генерирует случайный результат локально с помощью Web Cryptography API. Это означает, что на сервере нет вычислений и нет способа «вызвать» dice83 для получения случайного значения по HTTP.

Преимущество этой модели: каждый URL — это самодостаточная, доступная для обмена и добавления в закладки конфигурация инструмента. Составьте правильный путь — и инструмент загрузится с вашими точными параметрами. Используйте его в ссылках, рабочих листах, презентациях, iframe-вставках или QR-кодах.

Структура URL

https://dice83.com / {lang} / {tool} / {params...}
https://dice83.com / de / integer / 5 / 1 / 100
^^ ^^^^^^^ ^ ^ ^^^
lang tool count min max

Префикс языка — необязателен. Опустите его для английского языка. Имя инструмента выбирает генератор. Параметры — это значения, разделённые косой чертой, которые настраивают инструмент. Отсутствующие в URL параметры используют разумные значения по умолчанию.

Быстрые примеры

Составьте эти URL, чтобы мгновенно получить предварительно настроенную страницу инструмента:

/coin/10 Подбросить 10 монет одновременно

/integer/1/1000 Случайное целое число от 1 до 1000

/integer/5/-50/50 Пять случайных целых чисел от -50 до 50

/password/24 Надёжный пароль из 24 символов

/4d6kh3 Бросить 4d6, оставить 3 наибольших (значение характеристики)

/pattern/LLL-DDDD Случайная строка вида QXR-4829

/color/5/rgb Пять случайных цветов в формате RGB

/groups/24/4 Разделить 24 участника на 4 команды

/de/2d6 Бросить 2d6 с немецким интерфейсом

/100 Случайное число от 1 до 100

Справочник маршрутов

Каждый маршрут ниже принимает необязательный двухбуквенный языковой префикс. Параметры, выделенные курсивом, являются сегментами пути. Диапазоны используют разделители в виде косой черты, что позволяет задавать отрицательные значения.

Основные инструменты и инструменты принятия решений

/coin Подбросить одну монету

/coin/count Подбросить COUNT монет (1-1000)

/yes-no Случайное «да» или «нет»

/true-false Случайное логическое значение

/left-right Случайное направление

/rps Камень, ножницы или бумага

/dice-face Одна грань кубика в Unicode ⚀-⚅

Безопасность

/password/length Случайный пароль (по умолчанию 16, макс. 256)

/diceware/words Парольная фраза из словаря EFF (по умолчанию 6, макс. 20)

/pin/length Числовой ПИН-код (по умолчанию 4, макс. 20)

Генераторы чисел

/integer/min/max Случайное целое число в диапазоне (поддерживает отрицательные)

/integer/count/min/max Несколько целых чисел в диапазоне

/numbers/count/min/max Уникальные неповторяющиеся целые числа

/sequence/min/max Перемешать диапазон в случайном порядке

/decimal/count/decimals Случайные дроби от 0 до 1

/percent/decimals Случайный процент от 0% до 100%

/ratio/parts Случайные пропорции, в сумме дающие 100

/prime/min/max Случайное простое число в диапазоне

/fibonacci Случайное число Фибоначчи

/binary/bits Случайная битовая строка (макс. 64)

/bytes/count/format Необработанные байты в hex, base64 или bin

/even/min/max Случайное чётное число (поддерживает отрицательные)

/odd/min/max Случайное нечётное число (поддерживает отрицательные)

Строки и символы

/generate/length Буквенно-цифровая строка (макс. 256)

/uuid UUID v4 по RFC 4122

/unicode/count Случайные печатные символы Unicode

/letter/count Случайные буквы (зависят от языка)

/ascii Случайный печатный символ ASCII (33-126)

/emoji/count Случайные эмодзи

/roman/min/max Случайное римское число

/pattern/template Пользовательская строка по шаблону (L, l, D, H)

Время и дата

/calendar Визуальная сетка года со случайной датой

/date/from/to Случайная дата в диапазоне лет

/time/min/max Случайное время в диапазоне часов

/duration/min/max Случайная длительность в минутах

/timestamp/year Случайная метка времени Unix

/week Случайная неделя ISO 1-52

/month Случайный месяц (локализованный)

/weekday Случайный день недели (локализованный)

/season Случайное время года

Международные данные (Browser Intl API)

/timezone Случайный часовой пояс IANA + смещение UTC

/currency Случайная валюта ISO 4217

/language Случайный язык мира

/country/count Случайные страны с флагами

Визуальные инструменты и цвет

/color/count/format Случайные цвета (hex, rgb, hsl)

/gradient Случайный двухцветный CSS-градиент

/palette/harmony Гармоничная палитра (комплементарная, аналоговая, триада, монохромная)

/pixel/size/colors Случайная пиксельная сетка

/avatar Геометрический идентикон в SVG

/wavelength Случайная длина волны видимого спектра

Организационные

/order/count Случайный порядок очерёдности для COUNT участников

/pairs/count Случайное разбиение COUNT участников на пары

/groups/count/m Разделить COUNT на M случайных групп

/bracket/count Турнирная сетка с жеребьёвкой

/grid/rows/cols Случайная ячейка из сетки

/winner/count Выбрать одного из COUNT с визуальным эффектом

/countdown/min/max Случайный таймер обратного отсчёта (минуты)

Наборы данных

/element Случайный элемент периодической таблицы

/planet Случайная планета Солнечной системы

/note Случайная музыкальная нота (хроматическая)

/zodiac/system Случайный знак зодиака (западный или китайский)

/tarot/count Вытянуть карты из колоды Таро (78 карт)

/rune Случайная руна Старшего Футарка

/iching Случайная гексаграмма И Цзин

/nato Случайный код фонетического алфавита НАТО

Распределения

/gaussian/mean/stdev Нормальное (колоколообразное) распределение

/weighted/w1/w2/w3... Взвешенный выбор (до 5 весов)

Генеративное искусство

/blob/count Органическая SVG-форма (клякса)

/wave/count SVG-разделитель в виде волны

/noise/size Процедурная шумовая текстура

/mandala/count Симметричный радиальный узор

/spirograph Гипотрохоидная кривая

/voronoi/count Диаграмма Вороного

/delaunay/count Триангуляция Делоне

/terrain/size Топографическая контурная карта

/lsystem/count Ветвящаяся структура L-системы

/halftone/count Полутоновый точечный узор

/moire Интерференционный узор муарé

/guilloche Математическая линейная сетка

/lines/count Параллельные линии со смещением шумом

/stipple/count Взвешенная точечная россыпь

Инструменты дизайна

/proportion Случайная классическая пропорция (золотое сечение, корень из 2 и др.)

/rating/count Случайные звёздные рейтинги (с точностью до половины звезды)

/checker/cols/rows Шахматная доска со случайными цветами

/matrix/cols/rows Асимметричное деление сетки

Динамические маршруты

/NdS Выражение для кубиков: /d20, /2d6, /4d6kh3, /d8+5

/N Быстрое случайное число от 1 до N: /100, /20

/N/M Два числа: 1-N и 1-M: /100/500

/N/M/K Три числа: /100/200/300

Грамматика выражений для кубиков

Выражения для кубиков извлекаются из пути URL. Полная грамматика:

# Format [N]d<SIDES>[kh|kl<KEEP>][!][+|-<MOD>] # Examples d6 # один шестигранный кубик 2d6 # два шестигранных кубика, сумма 4d6kh3 # бросить 4d6, оставить 3 наибольших 2d20kl1 # бросить 2d20, оставить 1 наименьший d6! # взрывающийся d6 (перебросить при максимуме, прибавить) 2d6+3 # 2d6 плюс 3 d20-2 # d20 минус 2 4d6kh3+2 # всё вместе

Ограничения параметров

N (количество кубиков): от 1 до 100. SIDES: от 2 до 1 000 000. KEEP: от 1 до N. MOD: от -10 000 до +10 000.

Некорректные выражения автоматически заменяются на 1d6.

Языковой префикс

Каждый маршрут принимает необязательный двухбуквенный префикс ISO 639-1, задающий язык интерфейса. По умолчанию используется английский язык, если префикс не указан.

enzhjakohiesarfritptbnruuridtrvi

Языковой префикс влияет на надписи интерфейса, локализованный вывод (названия месяцев, дней недели, стран через браузерный Intl API) и SEO-теги. Он никогда не влияет на движок генерации случайных чисел или ограничения параметров.

/ko/letter Случайная корейская буква

/ja/month Случайное название месяца на японском

/de/integer/1/100 Немецкий интерфейс, целое число 1-100

/fr/zodiac/western Французский интерфейс, западный зодиак

Правила параметров

Диапазоны через косую черту

Все параметры диапазонов используют разделители / в URL. Это позволяет задавать отрицательные значения: /integer/-10/10. Диапазоны нормализуются так, чтобы меньшее значение шло первым. /integer/100/5 автоматически становится /integer/5/100.

Значения по умолчанию

Каждый параметр имеет разумное значение по умолчанию. Маршруты без параметров допустимы: /integer по умолчанию задаёт диапазон 1-100, /password — 16 символов, /percent — 0 десятичных знаков. Пропущенные параметры никогда не вызывают ошибок.

Ограничение значений

Все параметры проходят валидацию, приведение типов и ограничение до безопасных диапазонов. Значения, превышающие лимиты, автоматически усекаются. Неизвестные параметры игнорируются. Ни один URL не приводит к странице ошибки для разрешённых маршрутов.

Строки запроса отбрасываются

Сервер получает только параметры из пути. Строки запроса, добавленные к любому URL, автоматически отбрасываются при маршрутизации. /coin?count=50 работает идентично /coin. Путь URL — это полный и единственный интерфейс.

Интеграция

Встраивание через iframe

Встройте любой инструмент в iframe. Инструмент полностью отрисовывается внутри фрейма и генерирует результаты, используя энтропию браузера посетителя родительской страницы.

<iframe src="https://dice83.com/coin/5" width="100%" height="600"></iframe>

Прямые ссылки

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

<a href="https://dice83.com/integer/5/1/100">Сгенерировать 5 чисел</a>
<a href="https://dice83.com/groups/24/4">Создать 4 команды по 6</a>
<a href="https://dice83.com/4d6kh3">Бросить кубики для характеристик</a>

Рабочие листы и презентации

Печатайте URL прямо на учебных листах или слайдах презентаций. Ученики вводят путь в любой браузер. Каждый ученик генерирует независимые результаты. URL вроде dice83.com/coin/100 достаточно короткие, чтобы вводить вручную.