Developer API · v1

Создавайте книжки с ИИ прямо из кода.

REST API для подписчиков Pro и Premium. Запустите задачу генерации, опрашивайте статус — и готовая книжка автоматически появится в вашей библиотеке ChildrenBooks рядом с книгами, созданными в панели управления.

Безопасность по умолчанию

Ключ API показывается один раз и хранится в виде хеша SHA-256. Ротация и мгновенный отзыв в панели управления. Все запросы — только через TLS.

Лимиты и защита от злоупотреблений

Ограничения в минуту, в день и в месяц защищают квоту при утечке ключа. В ответах есть заголовки x-ratelimit-*, чтобы SDK могли аккуратно снижать частоту запросов.

Одна библиотека, одна квота

Книжки, созданные через API, видны в той же библиотеке, что и созданные в панели. Квота общая с вашим тарифом Pro или Premium.

Быстрый старт и справочник API

Получите ключ Pro или Premium в панели управления и запустите примеры. Некорректное тело запроса возвращает 400 / VALIDATION_ERROR; значения enum должны совпадать точно (с учётом регистра). Ответы содержат ok, необязательный requestId и data или error. При 429 учитывайте x-ratelimit-* и retry-after.

Что нужно заранее

  1. 1. Перейдите на Pro или Premium. На бесплатном тарифе нельзя создать ключ API. Посмотреть цены.
  2. 2. Откройте панель управления и нажмите Generate API key. Сразу скопируйте ключ — повторно он не показывается.
  3. 3. Отправьте первый запрос. Замените cbk_live_XXX своим ключом:

Запрос

POST /v1/stories

Создаёт асинхронную задачу генерации иллюстрированной детской книжки. Сервер ставит задачу в очередь и сразу отвечает 202 Accepted; в теле приходят taskId и bookId, по которым можно опрашивать прогресс через GET /v1/stories/{bookId}. Каждая страница (включая обложку) расходует один кредит из квоты тарифа.

Заголовки

Аутентификация: x-api-key: cbk_live_… (рекомендуется) или Authorization: Bearer cbk_live_….

ЗаголовокОбязательныйОписание
content-typeДаДолжен быть application/json.
Idempotency-KeyНетНеобязательный уникальный ключ для каждого логического создания (например, UUID). Тот же ключ в течение 24 ч с тем же JSON-телом возвращает исходные taskId / bookId (вторая книга не создаётся). Тот же ключ с другим телом возвращает 409 / IDEMPOTENCY_CONFLICT. Максимум 128 символов. Требуется Redis на стороне API; если Redis недоступен, дедупликация пропускается.
X-Request-IdНетЕсли задан, возвращается в ответах и логах для трассировки. Максимум 64 символа; иначе сервер сгенерирует его сам.
Тело JSON
ПолеТипОграниченияПодробности и допустимые значения
storyIdeastringОбязательно. Длина 10–8000 символов.Описание книжки обычными словами (сюжет, персонажи, место действия). Это не шаблон промпта — просто напишите, о чём должна быть история.
ageRangestring (enum)Обязательно. Должно точно совпадать с одним из допустимых значений (с учётом регистра).Целевой возраст читателя (лексика и темы): 0-3, 4-7, 8-12
stylestring (enum)Обязательно. Одно значение enum. С учётом регистра — 3d, а не «3D».

Художественный стиль иллюстраций.

  • watercolor — Мягкая акварельная иллюстрация.
  • oil_painting — Фактура и мазки масляной живописи.
  • 3d — 3D-рендер / стилизованная CGI-графика (отправляйте строку 3d).
  • comic_style — Кадры и линии в стиле комикса или графического романа.
  • crayon — Штрихи восковых мелков, как в детском рисунке.
  • colored_pencil — Фактура и штриховка цветных карандашей.
  • paper_cut — Вырезанная бумага / многослойные силуэты.
pageCountintegerОбязательно. Целое число 6–15 включительно. 1 кредит за страницу.Общее число страниц с обложкой. Каждая страница списывается с месячных кредитов тарифа.
tonestring (enum)Обязательно. Enum в snake_case — отправляйте строку точно как задано.

Настроение / жанр истории.

  • playful_funny — Юмор, лёгкость и озорство.
  • fantasy_magic — Сказки, магия, воображаемые миры.
  • animal — Персонажи-животные и сюжеты о природе.
  • heartwarming — Тёплые чувства, сопереживание и доброта.
  • sci_fi — Космос, роботы, простые технологии будущего (подходит детям).
  • daily_life_basics — Распорядок дня, семья, школа, чувства.
  • adventurous — Исследования, приключения, лёгкое напряжение.
  • educational — Мягкая обучающая подача (числа, привычки, социальные навыки).
languagestring (enum)Обязательно. Только английские ключи в нижнем регистре (например, english, а не en).

Язык текста истории:

english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian

Минимальный вызов с заголовками и полями JSON выше (замените ключ своим). cURL и TypeScript — один и тот же запрос, выберите вкладку. Храните ключ в серверной переменной окружения; никогда не встраивайте его в код для браузера.

cURL — создать книжку
bash
curl -X POST https://api.childrenbooks.online/v1/stories \
  -H "x-api-key: cbk_live_XXXXXXXXXXXX" \
  -H "content-type: application/json" \
  -d '{
    "storyIdea": "A little fox who learns to share carrots with forest friends.",
    "ageRange": "4-7",
    "style": "watercolor",
    "pageCount": 7,
    "tone": "heartwarming",
    "language": "english"
  }'

Ответ

Возвращается с 202 Accepted, когда задача поставлена в очередь, — в той же обёртке ok / data, что и другие успешные ответы. Пример содержимого; раскрывающиеся таблицы полей (POST 202 и другие) — в разделе Ответ.

POST /v1/stories — 202 Accepted (тело)
json
{
  "ok": true,
  "requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "bookId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "pending"
  }
}

GET /v1/stories/{id}

Возвращает метаданные книжки, статус генерации, прогресс и уже записанные страницы. Используйте bookId из POST /v1/stories. Доступны только книги пользователя, которому принадлежит ключ API; несуществующие или чужие id возвращают 404.

Параметры пути
ПараметрГдеПравила
idpathbookId, полученный из POST. Должен быть UUID. Видны только книги владельца ключа API.
Опрос статуса

Генерация асинхронная — опрашивайте GET /v1/stories/{bookId}, пока data.status не станет completed или failed. Полное тело ответа 200 приведено в разделе Ответ. cURL и TypeScript ниже — один и тот же запрос, переключайте вкладки.

cURL — проверить статус
bash
curl https://api.childrenbooks.online/v1/stories/<bookId> \
  -H "x-api-key: cbk_live_XXXXXXXXXXXX"

Ответ

Примеры и справочник полей для успешных ответов и ошибок. Порядок полей может меняться; null может быть указан явно или опущен.

GET /v1/stories/{id} — 200 OK (пример тела, например во время генерации)
json
{
  "ok": true,
  "requestId": "efa24798-b66a-405a-b3c9-956893531fe3",
  "data": {
    "id": "4cf184ed-0a29-4860-a257-0f8998357121",
    "title": "Finn's Carrot Patch",
    "slug": "finns-carrot-patch",
    "coverImage": "https://3fyspdsbp21eloyx.public.blob.vercel-storage.com/stories/4cf184ed-0a29-4860-a257-0f8998357121/storybook-4cf184ed0a294860a2570f8998357121-cover-uHWi4JpCATyXGczHi4uAJa1m24i62q.webp",
    "summary": "A little fox named Finn discovers that sharing his bountiful carrot harvest with his hungry forest friends makes him feel even happier than keeping them all for himself.",
    "storyIdea": "A little fox who learns to share carrots with forest friends.",
    "ageRange": "4-7",
    "style": "watercolor",
    "pageCount": 8,
    "tone": "heartwarming",
    "language": "english",
    "source": "api",
    "storageProvider": null,
    "createdAt": "2026-04-19T11:47:16.327Z",
    "updatedAt": "2026-04-19T11:58:15.877Z",
    "status": "completed",
    "progress": 100,
    "errorMessage": null,
    "completedAt": "2026-04-19T11:48:20.894Z",
    "pages": [
      {
        "index": 0,
        "title": null,
        "content": "In a sun-dappled corner of Whispering Woods, a little fox named Finn had the most wonderful carrot patch. He watered it every day, and the carrots grew big, orange, and crunchy. One morning, Finn pulled up the very last, perfect carrot. \"My carrots!\" he said proudly, piling them into a big basket. He planned to eat them all himself. Just then, he heard a soft sniffle. His friend Thumper the Rabbit was nearby, looking sadly at his own garden, which was just dry dirt. \"My seeds didn't grow,\" Thumper sighed, his tummy rumbling.",
        "imageUrl": "https://3fyspdsbp21eloyx.public.blob.vercel-storage.com/stories/4cf184ed-0a29-4860-a257-0f8998357121/storybook-4cf184ed0a294860a2570f8998357121-0-g8dJ8dzaQbBVfhl5zGc4X74YBwGQqC.webp"
      },
      {
        "index": 1,
        "title": null,
        "content": "Finn looked at his huge basket and then at his hungry friend. He didn't want to share his special carrots. They were *his* prize. But Thumper's sad eyes made his own heart feel funny. \"Well,\" Finn said slowly, scratching his ear. \"Maybe... maybe one carrot wouldn't be missed.\" He picked out a nice, medium-sized carrot and held it out. Thumper's eyes grew wide. \"For me?\" he squeaked. He took the carrot and munched happily. \"Oh, thank you, Finn! This is the best carrot ever!\" Seeing Thumper's joy made a warm, fizzy feeling bubble up in Finn's chest. It felt even better than crunching the carrot himself!",
        "imageUrl": "https://3fyspdsbp21eloyx.public.blob.vercel-storage.com/stories/4cf184ed-0a29-4860-a257-0f8998357121/storybook-4cf184ed0a294860a2570f8998357121-1-HKXNIJm9pHRjGcnJfvlmU5jHFHrb0s.webp"
      },
      {
        "index": 2,
        "title": null,
        "content": "The warm, fizzy feeling was so nice that Finn wanted to feel it again. He saw Bella the Deer walking slowly. \"Are you okay, Bella?\" Finn asked. \"I'm just a little tired from looking for berries,\" she said. Finn didn't hesitate this time. He picked two more carrots from his basket. \"Here, these will give you energy!\" Bella nuzzled him gratefully. \"You are so kind, Finn.\" Next, Oliver the Owl landed on a branch. \"Ahem, long night of studying the stars,\" he said, yawning. Finn offered him a carrot too. \"For your wisdom!\" Oliver hooted happily. Finn's basket was getting lighter, but his heart felt wonderfully full.",
        "imageUrl": "https://3fyspdsbp21eloyx.public.blob.vercel-storage.com/stories/4cf184ed-0a29-4860-a257-0f8998357121/storybook-4cf184ed0a294860a2570f8998357121-2-1qtunfUGjYz83GaofvzvrBin6HiHsB.webp"
      },
      {
        "index": 3,
        "title": null,
        "content": "Soon, Finn's basket was empty, but he was surrounded by happy friends. Thumper was bouncing, Bella was strong again, and Oliver was wide awake. \"Let's have a picnic!\" suggested Thumper. They all agreed. Finn thought his carrots were gone, but then his friends brought things to share! Thumper found sweet clover, Bella brought juicy blackberries, and Oliver shared shiny nuts. They had the best feast ever, laughing and talking. Finn realized something wonderful. Sharing his carrots didn't mean he had less; it meant he had more—more smiles, more laughter, and the best friends in the whole forest.",
        "imageUrl": "https://3fyspdsbp21eloyx.public.blob.vercel-storage.com/stories/4cf184ed-0a29-4860-a257-0f8998357121/storybook-4cf184ed0a294860a2570f8998357121-3-6vOoqqtHK3eyV6VJ3njHaipkGrS1az.webp"
      }
    ]
  }
}
Ошибка — 400 / 401 / 429 / … (тело)
json
{
  "ok": false,
  "requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "fields": {
      "pageCount": "Expected number between 6 and 15"
    }
  }
}
Таблицы полей — тело POST 202 (taskId, bookId, status)· развернуть
ПолеТипОписание
okbooleanВ этом ответе всегда true.
requestIdstringИдентификатор корреляции (эхо X-Request-Id или сгенерированный сервером).
data.taskIdstring (uuid)Идентификатор фоновой задачи генерации (для связи с очередью).
data.bookIdstring (uuid)Идентификатор книжки — используйте как параметр пути в GET /v1/stories/{id}.
data.statusstringНачальный статус задачи, сразу после приёма обычно pending. Значения: pending, processing, completed, failed.
Таблицы полей — объект data в GET 200, элементы pages[] и поля страницы· развернуть
ПолеТипОписание
idstring (uuid)Идентификатор книги (совпадает с id в пути).
titlestring | nullСгенерированное или отредактированное название.
slugstring | nullURL-slug книги на сайте, если есть.
coverImagestring | nullURL обложки.
summarystring | nullКраткое содержание.
storyIdeastring | nullИдея истории, сохранённая в книге.
ageRangestring | nullЭхо значения из запроса (например, 4-7).
stylestring | nullКлюч стиля иллюстраций.
pageCountinteger | nullЦелевое число страниц (с обложкой).
tonestring | nullКлюч настроения / жанра.
languagestring | nullКлюч языка истории.
sourcestring | nullГде создана книга: web, api, hf (или null).
storageProviderstring | nullИдентификатор хранилища файлов, если применимо.
createdAtstring | nullВремя создания записи книги в формате ISO 8601.
updatedAtstring | nullВремя последнего изменения записи книги в формате ISO 8601.
statusstringСтатус последней задачи генерации: pending, processing, completed, failed, unknown. unknown, если задачи ещё нет.
progressintegerПримерный процент выполнения 0–100 последней задачи (по умолчанию 0).
errorMessagestring | nullПонятная причина сбоя, когда status равен failed.
completedAtstring | nullВремя завершения генерации в формате ISO 8601, если есть.
pagesarrayУпорядоченный список страниц (см. следующую таблицу). Пополняется по мере записи иллюстраций и текста.

data.pages[] — каждый элемент

ПолеТипОписание
indexintegerПорядковый индекс страницы (по возрастанию вместе с остальными).
titlestring | nullЗаголовок страницы.
contentstring | nullТекст страницы.
imageUrlstring | nullURL иллюстрации этой страницы.

Тело ошибки

Для логики используйте error.code; error.message — только для показа.

Таблица полей — объект error· развернуть
ПолеТипОписание
okbooleanВсегда false.
requestIdstringТот же идентификатор корреляции, что и в успешных ответах.
error.codestringМашиночитаемый код ошибки (см. список ниже).
error.messagestringПонятное сообщение (не стройте логику на точной формулировке).
error.fieldsobject | undefinedНеобязательное соответствие «поле → сообщение валидации» (обычно при VALIDATION_ERROR).
error.metaobject | undefinedНеобязательный дополнительный контекст от сервера (структура может меняться).

Возможные значения error.code: UNAUTHORIZED, INVALID_API_KEY, PLAN_REQUIRED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, ALREADY_EXISTS, RATE_LIMIT_EXCEEDED, DAILY_CAP_EXCEEDED, INSUFFICIENT_CREDITS, EXTERNAL_SERVICE_ERROR, INTERNAL_ERROR, BAD_REQUEST, METHOD_NOT_ALLOWED

Лимиты

ТарифВ минутуВ день (книг)Месячная квота
Pro60 запросов50 книгОбщая с кредитами тарифа
Premium200 запросов200 книгОбщая с кредитами тарифа

При достижении лимита API возвращает 429 с retry-after в секундах. Каждый ответ также содержит x-ratelimit-remaining, чтобы клиент мог заранее снизить частоту.

Правила использования

  • • Ключ API принадлежит одному пользователю. Не передавайте его между аккаунтами.
  • • Не создавайте контент, нарушающий наши Условия использования, включая сексуальный контент с участием несовершеннолетних, реальное насилие и персонажей, защищённых авторским правом.
  • • Храните секреты в серверных переменных окружения. Никогда не встраивайте ключ API в код для браузера.
  • • При признаках злоупотребления (резкие всплески трафика, смена IP между континентами за минуты) мы можем заменить или отозвать ключ и связаться с вами по электронной почте.
  • • Переход на бесплатный тариф сразу отзывает ключ.

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

Войдите, активируйте ключ API в панели управления — и запустите первую интеграцию книжек меньше чем за 10 минут.

API для разработчиков ChildrenBooks – создавайте книжки с ИИ из кода | ChildrenBooks