Создавайте книжки с ИИ прямо из кода.
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. Перейдите на Pro или Premium. На бесплатном тарифе нельзя создать ключ API. Посмотреть цены.
- 2. Откройте панель управления и нажмите
Generate API key. Сразу скопируйте ключ — повторно он не показывается. - 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
| Поле | Тип | Ограничения | Подробности и допустимые значения |
|---|---|---|---|
| storyIdea | string | Обязательно. Длина 10–8000 символов. | Описание книжки обычными словами (сюжет, персонажи, место действия). Это не шаблон промпта — просто напишите, о чём должна быть история. |
| ageRange | string (enum) | Обязательно. Должно точно совпадать с одним из допустимых значений (с учётом регистра). | Целевой возраст читателя (лексика и темы): 0-3, 4-7, 8-12 |
| style | string (enum) | Обязательно. Одно значение enum. С учётом регистра — 3d, а не «3D». | Художественный стиль иллюстраций.
|
| pageCount | integer | Обязательно. Целое число 6–15 включительно. 1 кредит за страницу. | Общее число страниц с обложкой. Каждая страница списывается с месячных кредитов тарифа. |
| tone | string (enum) | Обязательно. Enum в snake_case — отправляйте строку точно как задано. | Настроение / жанр истории.
|
| language | string (enum) | Обязательно. Только английские ключи в нижнем регистре (например, english, а не en). | Язык текста истории: english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian |
Минимальный вызов с заголовками и полями JSON выше (замените ключ своим). cURL и TypeScript — один и тот же запрос, выберите вкладку. Храните ключ в серверной переменной окружения; никогда не встраивайте его в код для браузера.
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 и другие) — в разделе Ответ.
{
"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.
Параметры пути
| Параметр | Где | Правила |
|---|---|---|
| id | path | bookId, полученный из POST. Должен быть UUID. Видны только книги владельца ключа API. |
Опрос статуса
Генерация асинхронная — опрашивайте GET /v1/stories/{bookId}, пока data.status не станет completed или failed. Полное тело ответа 200 приведено в разделе Ответ. cURL и TypeScript ниже — один и тот же запрос, переключайте вкладки.
curl https://api.childrenbooks.online/v1/stories/<bookId> \
-H "x-api-key: cbk_live_XXXXXXXXXXXX"Ответ
Примеры и справочник полей для успешных ответов и ошибок. Порядок полей может меняться; null может быть указан явно или опущен.
{
"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"
}
]
}
}{
"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)· развернуть
| Поле | Тип | Описание |
|---|---|---|
| ok | boolean | В этом ответе всегда true. |
| requestId | string | Идентификатор корреляции (эхо X-Request-Id или сгенерированный сервером). |
| data.taskId | string (uuid) | Идентификатор фоновой задачи генерации (для связи с очередью). |
| data.bookId | string (uuid) | Идентификатор книжки — используйте как параметр пути в GET /v1/stories/{id}. |
| data.status | string | Начальный статус задачи, сразу после приёма обычно pending. Значения: pending, processing, completed, failed. |
Таблицы полей — объект data в GET 200, элементы pages[] и поля страницы· развернуть
| Поле | Тип | Описание |
|---|---|---|
| id | string (uuid) | Идентификатор книги (совпадает с id в пути). |
| title | string | null | Сгенерированное или отредактированное название. |
| slug | string | null | URL-slug книги на сайте, если есть. |
| coverImage | string | null | URL обложки. |
| summary | string | null | Краткое содержание. |
| storyIdea | string | null | Идея истории, сохранённая в книге. |
| ageRange | string | null | Эхо значения из запроса (например, 4-7). |
| style | string | null | Ключ стиля иллюстраций. |
| pageCount | integer | null | Целевое число страниц (с обложкой). |
| tone | string | null | Ключ настроения / жанра. |
| language | string | null | Ключ языка истории. |
| source | string | null | Где создана книга: web, api, hf (или null). |
| storageProvider | string | null | Идентификатор хранилища файлов, если применимо. |
| createdAt | string | null | Время создания записи книги в формате ISO 8601. |
| updatedAt | string | null | Время последнего изменения записи книги в формате ISO 8601. |
| status | string | Статус последней задачи генерации: pending, processing, completed, failed, unknown. unknown, если задачи ещё нет. |
| progress | integer | Примерный процент выполнения 0–100 последней задачи (по умолчанию 0). |
| errorMessage | string | null | Понятная причина сбоя, когда status равен failed. |
| completedAt | string | null | Время завершения генерации в формате ISO 8601, если есть. |
| pages | array | Упорядоченный список страниц (см. следующую таблицу). Пополняется по мере записи иллюстраций и текста. |
data.pages[] — каждый элемент
| Поле | Тип | Описание |
|---|---|---|
| index | integer | Порядковый индекс страницы (по возрастанию вместе с остальными). |
| title | string | null | Заголовок страницы. |
| content | string | null | Текст страницы. |
| imageUrl | string | null | URL иллюстрации этой страницы. |
Тело ошибки
Для логики используйте error.code; error.message — только для показа.
Таблица полей — объект error· развернуть
| Поле | Тип | Описание |
|---|---|---|
| ok | boolean | Всегда false. |
| requestId | string | Тот же идентификатор корреляции, что и в успешных ответах. |
| error.code | string | Машиночитаемый код ошибки (см. список ниже). |
| error.message | string | Понятное сообщение (не стройте логику на точной формулировке). |
| error.fields | object | undefined | Необязательное соответствие «поле → сообщение валидации» (обычно при VALIDATION_ERROR). |
| error.meta | object | 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
Лимиты
| Тариф | В минуту | В день (книг) | Месячная квота |
|---|---|---|---|
| Pro | 60 запросов | 50 книг | Общая с кредитами тарифа |
| Premium | 200 запросов | 200 книг | Общая с кредитами тарифа |
При достижении лимита API возвращает 429 с retry-after в секундах. Каждый ответ также содержит x-ratelimit-remaining, чтобы клиент мог заранее снизить частоту.
Правила использования
- • Ключ API принадлежит одному пользователю. Не передавайте его между аккаунтами.
- • Не создавайте контент, нарушающий наши Условия использования, включая сексуальный контент с участием несовершеннолетних, реальное насилие и персонажей, защищённых авторским правом.
- • Храните секреты в серверных переменных окружения. Никогда не встраивайте ключ API в код для браузера.
- • При признаках злоупотребления (резкие всплески трафика, смена IP между континентами за минуты) мы можем заменить или отозвать ключ и связаться с вами по электронной почте.
- • Переход на бесплатный тариф сразу отзывает ключ.
Готовы начать?
Войдите, активируйте ключ API в панели управления — и запустите первую интеграцию книжек меньше чем за 10 минут.