Developer API · v1

コードから AI 絵本を生成。

Pro・Premium 会員向けの REST API です。生成ジョブを開始してステータスをポーリングすると、完成した絵本はダッシュボードで作った絵本と同じ 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} で進捗をポーリングできます。1 ページ(表紙を含む)ごとにプランのクォータから 1 クレジットを消費します。

ヘッダー

認証:x-api-key: cbk_live_…(推奨)または Authorization: Bearer cbk_live_…。

ヘッダー必須説明
content-typeはいapplication/json である必要があります。
Idempotency-Keyいいえ論理的な作成 1 回ごとの任意の一意キー(例:UUID)。24 時間以内に同じキーと同じ JSON ボディで送ると、元の taskId / bookId が返ります(2 冊目は作られません)。同じキーで異なるボディを送ると 409 / IDEMPOTENCY_CONFLICT になります。最大 128 文字。API 側の Redis が必要で、Redis が停止している場合は重複排除をスキップします。
X-Request-Idいいえ指定するとレスポンスとログにそのまま返され、追跡に使えます。最大 64 文字。未指定の場合はサーバーが生成します。
JSON ボディ
フィールド型制約詳細と使用可能な値
storyIdeastring必須。 10〜8000 文字。絵本の内容(あらすじ、登場人物、舞台)をふつうの言葉で書いてください。プロンプトのテンプレートではなく、物語のテーマを書けば十分です。
ageRangestring (enum)必須。 使用可能な値のいずれかと完全一致(大文字・小文字を区別)。対象年齢(語彙とテーマに影響): 0-3, 4-7, 8-12
stylestring (enum)必須。 enum の値を 1 つ。大文字・小文字を区別します。"3D" ではなく 3d を使用。

イラストの画風。

  • watercolor — やわらかな水彩イラスト。
  • oil_painting — 油絵の質感と筆づかい。
  • 3d — 3D レンダリング / デフォルメした CGI 風(文字列 3d を送信)。
  • comic_style — マンガやグラフィックノベル風のコマ割りと線。
  • crayon — クレヨンのタッチで、子どもの絵のような楽しさ。
  • colored_pencil — 色鉛筆の質感と線の重ね。
  • paper_cut — 切り絵 / 重ねたシルエット風。
pageCountinteger必須。 6〜15 の整数。1 ページにつき 1 クレジット。表紙を含む総ページ数。各ページがプランの月間クレジットにカウントされます。
tonestring (enum)必須。 snake_case の enum。定義どおりの文字列を送信してください。

物語の雰囲気・ジャンル。

  • playful_funny — ユーモア中心の、軽くておかしな話。
  • fantasy_magic — おとぎ話、魔法、空想の世界。
  • animal — 動物のキャラクターと自然が中心の物語。
  • heartwarming — やさしい感情、共感、思いやり。
  • sci_fi — 宇宙、ロボット、身近な未来技術(子ども向け)。
  • daily_life_basics — 毎日の習慣、家族、学校、気持ち。
  • adventurous — 探検、冒険、ほどよいドキドキ。
  • educational — さりげない学び(数字、生活習慣、社会性)。
languagestring (enum)必須。 小文字の英語キーのみ(例:en ではなく english)。

生成する本文の言語:

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}

絵本のメタデータ、生成ステータス、進捗、これまでに書き込まれたページを取得します。POST /v1/stories が返した bookId を使用してください。取得できるのは API キーの所有ユーザーの絵本のみで、存在しない ID や他のユーザーの ID には 404 を返します。

パスパラメーター
パラメーター場所ルール
idpathPOST が返した bookId。UUID である必要があります。API キーの所有ユーザーの絵本だけが表示されます。
ポーリング

生成は非同期です。data.status が completed または failed になるまで GET /v1/stories/{bookId} をポーリングしてください。200 の JSON ボディ全体はレスポンスに掲載しています。下の 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相関 ID(X-Request-Id をそのまま返すか、サーバーが生成)。
data.taskIdstring (uuid)バックグラウンド生成タスクの ID(キューとの対応付け用)。
data.bookIdstring (uuid)絵本 ID。GET /v1/stories/{id} のパスパラメーターに使います。
data.statusstringジョブの初期ステータス。受理直後は通常 pending。値:pending、processing、completed、failed。
フィールド表 — GET 200 の data オブジェクト、pages[] の要素とページのフィールド· 開く
フィールド型説明
idstring (uuid)絵本 ID(パスの id と同じ)。
titlestring | null生成または編集されたタイトル。
slugstring | nullウェブサイト上の絵本の URL スラッグ(ある場合)。
coverImagestring | null表紙画像の URL。
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 | nullstatus が failed のときの、人が読める失敗理由。
completedAtstring | null生成完了日時(ISO 8601、ある場合)。
pagesarray順番に並んだページオブジェクト(次の表を参照)。イラストと本文が書き込まれるにつれて増えます。

data.pages[] — 各要素

フィールド型説明
indexintegerページの並び順インデックス(ほかのページと昇順に並びます)。
titlestring | nullページのタイトル・見出し。
contentstring | nullページの本文。
imageUrlstring | nullこのページのイラスト URL。

エラーボディ

処理の分岐には error.code を使ってください。error.message は表示専用です。

フィールド表 — error オブジェクト· 開く
フィールド型説明
okboolean常に false。
requestIdstring成功レスポンスと同じ相関 ID。
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

上限

プラン1 分あたり1 日あたり(冊)月間クォータ
Pro60 リクエスト50 冊プランのクレジットと共有
Premium200 リクエスト200 冊プランのクレジットと共有

上限に達すると API は 429 と retry-after(秒)を返します。すべてのレスポンスに x-ratelimit-remaining が含まれるので、クライアント側で事前にペースを落とせます。

利用ポリシー

  • • API キーは 1 人のユーザーに紐づきます。複数のアカウントで共有しないでください。
  • • 利用規約に反するコンテンツを生成しないでください。未成年者が関わる性的表現、現実の暴力、著作権で保護されたキャラクターなどが含まれます。
  • • シークレットはサーバー側の環境変数に保存し、API キーをブラウザ向けコードに埋め込まないでください。
  • • 不正な利用パターン(急激なトラフィック、数分以内の大陸をまたぐ IP の変化など)が見られた場合、キーをローテーションまたは無効化し、メールでご連絡することがあります。
  • • 無料プランにダウングレードすると、キーはただちに無効になります。

始める準備はできましたか?

ログインしてダッシュボードで API キーを有効にすれば、10 分以内に最初の絵本連携をリリースできます。

ChildrenBooks 開発者 API – コードから AI 絵本を生成 | ChildrenBooks