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;枚举值必须完全一致(区分大小写)。响应统一包含 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 个点数。

请求头

认证方式:x-api-key: cbk_live_…(推荐)或 Authorization: Bearer cbk_live_…。

请求头必填说明
content-type是必须为 application/json。
Idempotency-Key否可选,每次逻辑上的创建使用一个唯一键(例如 UUID)。24 小时内用同一个键、相同的 JSON 请求体再次请求,会返回原来的 taskId / bookId(不会生成第二本书)。同一个键配不同的请求体会返回 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)必填。 取一个枚举值,区分大小写——要用 3d,不是 "3D"。

插图的画风。

  • watercolor — 柔和的水彩插画风格。
  • oil_painting — 油画质感和笔触。
  • 3d — 3D 渲染 / 风格化 CGI 效果(传字符串 3d)。
  • comic_style — 漫画或图像小说式的分格与线条。
  • crayon — 蜡笔笔触,带孩子画作的童趣。
  • colored_pencil — 彩色铅笔的质感和排线。
  • paper_cut — 剪纸 / 层叠剪影风格。
pageCountinteger必填。 整数,6–15(含)。每页消耗 1 个点数。包含封面在内的总页数。每一页都计入套餐的每月额度。
tonestring (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}

获取一本绘本的元数据、生成状态、进度,以及目前已写入的页面。使用 POST /v1/stories 返回的 bookId。只能获取属于该 API 密钥所属用户的绘本;不存在的 id 或其他用户的 id 都返回 404。

路径参数
参数位置规则
idpathPOST 返回的 bookId,必须是 UUID。只能看到该 API 密钥所属用户的绘本。
轮询

生成是异步的——用 GET /v1/stories/{bookId} 轮询,直到 data.status 变为 completed 或 failed。完整的 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 slug(如有)。
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

限额

套餐每分钟每天(本)每月额度
Pro60 次请求50 本与套餐点数共享
Premium200 次请求200 本与套餐点数共享

触发限额时,API 返回 429 并附带 retry-after(秒)。每个响应还包含 x-ratelimit-remaining,客户端可以提前放慢请求。

使用规范

  • • API 密钥只属于一个用户,不要在多个账号之间共用。
  • • 不得生成违反我们服务条款的内容,包括涉及未成年人的色情内容、现实暴力或受版权保护的角色。
  • • 把密钥保存在服务端环境变量中,绝不要嵌入浏览器端代码。
  • • 如发现滥用行为(突发流量、几分钟内跨大洲的 IP 跳变等),我们可能会轮换或吊销密钥,并通过邮件联系你。
  • • 降级到免费套餐会立即吊销密钥。

准备好开始了吗?

登录后在控制台启用 API 密钥,10 分钟内就能完成你的第一个绘本集成。

ChildrenBooks 开发者 API – 用代码批量生成 AI 绘本 | ChildrenBooks