← Все обновленияHANDWRITTNER · PUBLIC API

Public API Handwrittner: рукописные документы из вашего приложения

Собирайте шаблоны из текста, таблиц, изображений и колонок, настраивайте почерк в полном редакторе и передавайте новые данные через API. Один шаблон — множество разных документов.

Шаблоны документовВаш почеркPDF через API

Создать свой API-шаблон →

Структурированный API-шаблон Handwrittner: блоки, колонки, таблица и настройки страницы — Слева — элементы документа, в центре — схема структуры, справа — настройки страницы и выбранного блока.

01 · СТРУКТУРА ДОКУМЕНТА

Настройте шаблон один раз, меняйте данные в каждом запросе

API Template — сохранённое оформление будущего документа: почерк, размер бумаги, поля и расположение элементов. Ваше приложение отправляет ID шаблона и новые данные, а Handwrittner создаёт документ с теми же настройками. Это удобно для конспектов, персональных писем, учебных материалов и отчётов.

В структурированном шаблоне документ собирается из блоков. Выберите элемент слева, настройте его справа и задайте имя поля API key. Например, заголовок может получать значение из title, текст — из body, а картинка — из photo.

Текст

Один или несколько абзацев: постоянный текст либо новое значение из API.

Заголовок

Название документа или раздела с отдельным размером и оформлением.

Изображение

Загруженная картинка по assetId, с настройками ширины и выравнивания.

Таблица

Колонки с заданными ключами, строки данных, заголовки и оформление линий.

Список

Маркеры или нумерация. Приложение передаёт массив пунктов.

Колонки

Две или три колонки с текстом, картинками и другими блоками внутри.

Разделитель

Горизонтальная линия между разделами документа.

Промежуток

Свободное место нужной высоты между элементами.

Разрыв страницы

Начало следующего раздела на новом листе.

Постоянное или динамическое?

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

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

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

02 · ЛИЧНЫЙ ПОЧЕРК

Создайте свой шрифт и используйте его в API

Вместо стандартного почерка можно выбрать собственный шрифт из библиотеки Handwrittner. В FontCreator вы создаёте буквы и их варианты, настраиваете интервалы и соединения, собираете шрифт, а затем выбираете его в API-шаблоне.

Подписка нужна для создания и редактирования шрифта.

После создания и сборки сохранённый шрифт остаётся доступен для API даже после окончания подписки. Чтобы снова редактировать его, понадобится подходящая подписка. Оплата API-генераций учитывается отдельно.

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

Подробнее о создании своего шрифта →

03 · ТОЧНАЯ НАСТРОЙКА

Полный редактор /main для оформления текста

Нажмите «Настроить шаблон» или «Почерк и модификации в /main», чтобы перейти в привычный редактор Handwrittner. Здесь можно точечно настроить размер текста, цвет, поля, межстрочный интервал, красную строку, сетку и фон бумаги.

Текст в редакторе служит примером для настройки почерка. Новое содержимое документа ваше приложение передаёт через API. У структурированного шаблона блоки остаются в Builder, а предпросмотр использует значения из его Test Data.

Полный редактор API-шаблона с Tiptap, параметрами текста и предпросмотром PDF — Точная настройка почерка и страницы в /main: сохраните оформление и используйте его с новыми данными.

Предпросмотр обновляется по кнопке: меняйте настройки, затем нажмите «Обновить Preview», переключайте страницы и увеличивайте изображение. Для проверки сохранять шаблон заранее не нужно. В превью видны первые 4 страницы с водяным знаком; готовый PDF содержит весь документ.

04 · ЖИВАЯ РУКОПИСЬ

Те же модификаторы, что в обычном редакторе

API-шаблон использует инструменты оформления обычного сайта. Не нужно отдельно программировать каждое отклонение букв: включите нужные эффекты, выберите пресет или уточните значения вручную и сохраните настройки в шаблоне.

Слова

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

Буквы

Небольшие изменения наклона, размера и положения символов делают текст менее однообразным. Интенсивность эффектов можно настроить.

Строки

Настройте поведение строк и интервалы, чтобы почерк был аккуратнее или свободнее — в зависимости от задачи.

Бумага и фон

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

Модификаторы слов с пресетами, настройками наклона, зигзага и предпросмотром — Включайте эффекты, выбирайте пресеты и проверяйте их на примере перед сохранением шаблона.

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

05 · БЕЗ СЛОЖНОЙ СТРУКТУРЫ

Для обычного текста — Simple Text Template

Если нужны только абзацы, выберите «Простой текст». Настройте шрифт, бумагу и интервалы, сохраните шаблон и передавайте каждый новый текст в поле text. Добавлять блоки, колонки и отдельные поля не потребуется.

Выбор между простым текстом и структурированным API-шаблоном — Simple Text принимает text. Structured Template принимает data для настроенных блоков.

Один перенос строки в JSON записывается как \n, а разделение абзацев — как \n\n. Например, ваше приложение может отправлять новый конспект каждый день, сохраняя одинаковый почерк и оформление.

{
  "templateId": "tpl_ЗАМЕНИТЕ_ID_ШАБЛОНА",
  "text": "Конспект по биологии\n\nКлетка — основная единица строения живых организмов.\n\nВывод: строение клетки связано с её функциями."
}

06 · ПРИМЕРЫ ДАННЫХ

Выберите элемент и посмотрите, что передавать в API

Примеры расположены слева направо. Нажмите на нужный сценарий: ниже появятся схема документа, настройка блоков и JSON запроса. Названия полей должны совпадать с API key в вашем сохранённом шаблоне.

Список

Добавьте блок «Список», задайте API key topics и выберите маркеры или нумерацию. Передайте массив строк.

Определение предела
Непрерывность функции
Практические примеры

POST /api/v1/generations

{
  "templateId": "tpl_ЗАМЕНИТЕ_ID_ШАБЛОНА",
  "data": {
    "topics": [
      "Определение предела",
      "Непрерывность функции",
      "Практические примеры"
    ]
  }
}

Слева показана схема. Настоящий почерк и разбивку страниц проверяйте в Preview вашего шаблона.

ID вашего сохранённого шаблона

Замените демонстрационный ID своим. У каждого примера должна быть соответствующая структура и поля в шаблоне; содержимое полей можно менять в каждом запросе.

Весь процесс: создать генерацию → дождаться результата → скачать PDF

Генерація PDF виконується асинхронно. Перший запит створює завдання та повертає його ID. Потім перевірте статус завдання і після completed завантажте PDF за downloadUrl.

POST generation → queued / processing → GET status → completed → GET download → PDF

Для читання JSON у Bash потрібен jq. Виконуйте три кроки послідовно в одному терміналі.

Крок 1. Створити генерацію

POST /api/v1/generations

# Requires jq.
command -v jq >/dev/null || { printf '%s\n' 'Install jq first.' >&2; exit 1; }
export HW_API_KEY='your_api_key'

JOB=$(curl --fail-with-body 'https://handwrittner.com/api/v1/generations' \
  -H "Authorization: Bearer $HW_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'HW_TEMPLATE_JSON'
{
  "templateId": "tpl_ЗАМЕНИТЕ_ID_ШАБЛОНА",
  "data": {
    "topics": [
      "Определение предела",
      "Непрерывность функции",
      "Практические примеры"
    ]
  }
}
HW_TEMPLATE_JSON
) || exit 1
BASE='https://handwrittner.com/api/v1'
printf '%s\n' "$JOB"
GENERATION_ID=$(printf '%s' "$JOB" | jq -er '.id') || exit 1

Сервер повертає ID генерації та статус queued: завдання поставлено в чергу. Відповідь POST не містить PDF.

{
  "id": "gen_...",
  "status": "queued"
}

Крок 2. Перевірити статус генерації

GET /api/v1/generations/{generationId}

while true; do
  STATUS=$(printf '%s' "$JOB" | jq -er '.status') || exit 1
  case "$STATUS" in
    completed) break ;;
    queued|processing) sleep 10 ;;
    *) printf '%s\n' "$JOB" >&2; exit 1 ;;
  esac
  JOB=$(curl --fail-with-body \
    "$BASE/generations/$GENERATION_ID" \
    -H "Authorization: Bearer $HW_API_KEY") || exit 1
  printf '%s\n' "$JOB"
done

queued → processing → completed. Перевіряйте статус раз на 10 секунд. При failed покажіть error і не завантажуйте PDF. Приклад відповіді completed:

{
  "id": "gen_...",
  "status": "completed",
  "pages": 2,
  "creditsSpent": 2,
  "downloadUrl": "/api/v1/generations/gen_.../download"
}

Крок 3. Завантажити PDF

GET downloadUrl

[ "$(printf '%s' "$JOB" | jq -r '.status')" = completed ] || exit 1
DOWNLOAD_URL=$(printf '%s' "$JOB" | jq -er '.downloadUrl') || exit 1
case "$DOWNLOAD_URL" in
  https://*|http://*) ;;
  /*) AUTHORITY="${BASE#*://}"; DOWNLOAD_URL="${BASE%%://*}://${AUTHORITY%%/*}$DOWNLOAD_URL" ;;
  *) printf '%s\n' 'Invalid downloadUrl' >&2; exit 1 ;;
esac
curl --fail-with-body "$DOWNLOAD_URL" \
  -H "Authorization: Bearer $HW_API_KEY" \
  -o 'handwrittner.pdf' || exit 1

Завантажуйте PDF лише після completed. Адреса береться з downloadUrl відповіді; відносний шлях розв’язується відносно адреси API.

07 · ГОТОВЫЙ КОД

Скопируйте API-запрос после создания шаблона

После сохранения Builder автоматически подставляет templateId и текущие данные в примеры кода. Доступны cURL, JavaScript, Python, Java, C++ и C#. Для cURL есть отдельные варианты Linux / macOS и Windows PowerShell.

Тестовые данные, результат предпросмотра и готовый API-запрос с выбором среды cURL — Builder показывает данные, результат и код рядом: можно скопировать отдельный запрос или весь процесс получения PDF.

Создать задачуПроверить статусСкачать PDF

PDF создаётся асинхронно. Первый POST /api/v1/generations возвращает ID задачи и статус queued. Проверяйте GET /api/v1/generations/{id}: после completed скачайте PDF по downloadUrl из ответа. Если задача завершилась со статусом failed, проверьте ошибку; скачивать PDF в этом случае не нужно.

Кнопка «Скопировать весь процесс · 3 шага» позволяет скопировать создание задачи, ожидание результата и скачивание одним фрагментом. Подставьте свой API-ключ и выполните код в выбранной среде. Для PNG и SVG используйте соответствующий формат результата в Builder.

08 · РАСХОД ЛИСТОВ

Размер бумаги сразу показывает стоимость страницы

A51 лист балансаза страницу

A41,5 листа балансаза страницу

A32 листа балансаза страницу

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

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