REST API · версия 1

Создавайте сайты
через API

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

Быстрый старт Создать API-ключ

Базовый адрес https://platform.osnovator.ru

создание проекта 201

$ curl -X POST "https://platform.osnovator.ru/api/v1/projects" \
  -H "X-API-Key: $OSNOVATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

# Ответ
{
  "success": true,
  "project_id": 276,
  "status": "processing"
}

Рабочий процесс

От брифа до готового сайта

Генерация идёт асинхронно. API сразу возвращает идентификатор проекта, а состояние проверяется отдельным запросом.

01POSTСоздать проектБриф и параметры бизнеса 02GETДождаться макетовОпрос до состояния selecting 03GETПолучить превьюСравнить направления 04POSTФинализироватьСтраницы, тексты и изображения 05GETСкачать архивГотовый сайт одним ZIP-файлом

Подготовка

Быстрый старт

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

Адрес API задаёт сервер

Для страницы используется SIMPLE_API_PUBLIC_URL. Если переменная не задана, применяется DOMAIN_WIZARD, затем PREVIEW_PUBLIC_URL.

.env

OSNOVATOR_API_URL="https://platform.osnovator.ru"
OSNOVATOR_API_KEY="sb_ваш_ключ"
BRIEF_PATH="/путь/к/brief.md"

1Создайте ключНастройки → API-ключи. Полное значение показывается один раз.

2Установите jqОн понадобится для сборки JSON и чтения ответов в примерах.

3Подготовьте брифОбычный текстовый или Markdown-файл с описанием бизнеса.

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

Авторизация

Передавайте ключ в заголовке X-API-Key. Также поддерживается стандартный заголовок Authorization: Bearer.

РекомендуетсяX-API-Key: $OSNOVATOR_API_KEY

АльтернативаAuthorization: Bearer $OSNOVATOR_API_KEY

Не публикуйте ключ

Не вставляйте его в клиентский JavaScript, мобильное приложение или открытый репозиторий. Выполняйте запросы со своего сервера.

POST/api/v1/projects

Создание проекта

Передайте сведения о компании и содержимое брифа. В ответ API вернёт project_id, по которому отслеживается весь дальнейший процесс.

shell

set -a
source .env
set +a

PAYLOAD=$(jq -n \
  --arg company "ООО «Пример»" \
  --arg domain "example.ru" \
  --rawfile brief "$BRIEF_PATH" \
  '{company_name: $company, domain: $domain, user_brief: $brief, auto_naming: false, lang: "ru"}')

curl -sS -X POST "$OSNOVATOR_API_URL/api/v1/projects" \
  -H "X-API-Key: $OSNOVATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" \
  -o project.json

PROJECT_ID=$(jq -r '.project_id' project.json)
printf 'project_id = %s\n' "$PROJECT_ID"

Ответ201 Created

{
  "success": true,
  "project_id": 276,
  "status": "processing",
  "credits_balance": 1500
}

Поля запроса

Поле	Тип	Описание
`company_name`	строка	Название компании. Обязательно, если `auto_naming=false`.
`domain`	строка	Желаемый или существующий домен.
`user_brief`	строка	Полный текст брифа.
`auto_naming`	логическое	Создать название автоматически. По умолчанию `true`.
`lang`	строка	Язык проекта. По умолчанию `ru`.
`competitor_urls`	массив	Адреса сайтов конкурентов для анализа.
`enable_shop`	логическое	Добавить возможности интернет-магазина.
`phone`, `email`, `address`	строка	Контактные данные для сайта.

GET/api/v1/projects/{project_id}/status

Проверка состояния

Опрашивайте проект с разумным интервалом. Когда project.status станет selecting, макеты готовы к просмотру и выбору.

автоматический опрос

while sleep 15; do
  RESPONSE=$(curl -sS \
    "$OSNOVATOR_API_URL/api/v1/projects/$PROJECT_ID/status" \
    -H "X-API-Key: $OSNOVATOR_API_KEY")

  echo "$RESPONSE" | jq -c '.project | {status, current_step}'

  STATUS=$(echo "$RESPONSE" | jq -r '.project.status')
  [ "$STATUS" = "selecting" ] && break
done

processingАнализ и генерация

selectingМакеты готовы

finalizingДогенерация

selectingВыбранный макет готов

✓

Проверяйте состояние конкретного макета

После финализации проект снова получает состояние selecting, а выбранный элемент в drafts_info меняется с finalizing на ready.

GET/api/v1/projects/{project_id}/mockups/{draft_id}/preview.png

Превью макета

Возьмите идентификатор нужного макета из project.drafts_info и загрузите изображение. Для доступа к файлу также нужен API-ключ.

загрузка первого превью

PROJECT=$(curl -sS \
  "$OSNOVATOR_API_URL/api/v1/projects/$PROJECT_ID/status" \
  -H "X-API-Key: $OSNOVATOR_API_KEY")

DRAFT_ID=$(echo "$PROJECT" | jq -r '.project.drafts_info[0].draft_id')

curl -sS \
  "$OSNOVATOR_API_URL/api/v1/projects/$PROJECT_ID/mockups/$DRAFT_ID/preview.png" \
  -H "X-API-Key: $OSNOVATOR_API_KEY" \
  -o preview.png

Если финальное изображение ещё не готово, конечная точка автоматически отдаст раннее превью. Если нет ни одного файла, ответит 404.

POST/api/v1/projects/{project_id}/mockups/{draft_id}/finalize

Финализация макета

Выберите один макет со состоянием main_ready. Основатор создаст внутренние страницы, подготовит изображения и завершит сайт.

запуск финализации

curl -sS -X POST \
  "$OSNOVATOR_API_URL/api/v1/projects/$PROJECT_ID/mockups/$DRAFT_ID/finalize" \
  -H "X-API-Key: $OSNOVATOR_API_KEY" | jq

Ответ202 Accepted

{
  "success": true,
  "project_id": 276,
  "draft_id": "draft_abc123"
}

Операция асинхронная

202 означает, что задача принята. Продолжайте проверять проект, пока у выбранного макета в drafts_info не появится status: "ready".

GET/api/v1/projects/{project_id}/download

Скачивание архива

Заберите готовый сайт одним запросом. API вернёт ZIP-архив с самодостаточным проектом — его можно развернуть на своём хостинге или передать клиенту. Скачивание доступно, когда у выбранного макета в drafts_info появился статус ready.

скачивание архива

curl -sS \
  "$OSNOVATOR_API_URL/api/v1/projects/$PROJECT_ID/download" \
  -H "X-API-Key: $OSNOVATOR_API_KEY" \
  -OJ

Флаг -OJ сохранит файл под именем из заголовка Content-Disposition (например, example.com.zip). Повторный запрос отдаёт архив из кэша — без ожидания сборки.

Скидка 50% для профессионалов

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

Тарификация

Сценарий	Стоимость
Первое скачивание проекта	50% от базовой цены выгрузки (2500 ₽ при цене 5000 ₽), списывается с баланса ключа
Повторные скачивания	Бесплатно — оплата фиксируется один раз на проект
Ключ администратора	Бесплатно всегда

Пополняйте баланс заранее

Если на балансе не хватает средств, API ответит 402 с полями cost (цена со скидкой) и balance (текущий остаток). Проект при этом не пострадает — просто пополните баланс и повторите запрос.

Справочник

Конечные точки

POST/api/v1/projectsСоздать проект201

GET/api/v1/projects/{id}/statusПолучить состояние200

GET/api/v1/projects/{id}/mockups/{draft}/preview.pngСкачать превью200

POST/api/v1/projects/{id}/mockups/{draft}/finalizeФинализировать макет202

GET/api/v1/projects/{id}/downloadСкачать архив сайта200

Основные поля состояния

Поле	Назначение
`project.status`	Общее состояние проекта: `processing`, `selecting` или `finalizing`.
`project.current_step`	Текущий этап конвейера. Макеты доступны на этапе `4`.
`project.drafts_info`	Состояние, ход генерации и адрес превью для каждого макета.
`drafts_info[].status`	`pending`, `main_ready`, `finalizing` или `ready`.
`drafts_info[].image_progress`	Количество и процент подготовленных изображений.
`credits`	Текущий баланс пользователя.

Диагностика

Ошибки

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

401Нет авторизацииКлюч отсутствует, отозван или введён неверно.

402Недостаточно средствНа балансе не хватает средств для генерации или скачивания архива.

404Объект не найденПроект, макет или превью не существует либо принадлежит другому ключу.

409Неверное состояниеПроект ещё не готов или финализация уже выполняется.

Формат ошибки401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Готовы начать?

Запустите первую генерацию

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

Создать API-ключ Задать вопрос

Создавайте сайтычерез API