코드로 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. Pro 또는 Premium으로 업그레이드하세요. 무료 요금제는 API 키를 발급할 수 없습니다. 요금 보기.
- 2. 대시보드를 열고
Generate API key를 클릭하세요. 바로 복사해 두세요. 다시 표시되지 않습니다. - 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 본문
| 필드 | 타입 | 제약 | 설명 및 허용 값 |
|---|---|---|---|
| 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) | 필수. snake_case enum. 정의된 문자열 그대로 보내세요. | 이야기의 분위기 / 장르.
|
| language | string (enum) | 필수. 소문자 영어 키만 허용(예: en이 아니라 english). | 생성할 이야기 텍스트의 언어: 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}
그림책의 메타데이터, 생성 상태, 진행률, 지금까지 작성된 페이지를 가져옵니다. POST /v1/stories가 반환한 bookId를 사용하세요. API 키 소유자의 책만 받을 수 있으며, 없는 ID나 다른 사용자의 ID는 404를 반환합니다.
경로 매개변수
| 매개변수 | 위치 | 규칙 |
|---|---|---|
| id | path | POST가 반환한 bookId. UUID여야 합니다. API 키 소유자의 책만 볼 수 있습니다. |
폴링
생성은 비동기로 진행됩니다. data.status가 completed 또는 failed가 될 때까지 GET /v1/stories/{bookId}를 폴링하세요. 전체 200 JSON 본문은 응답 섹션에 있습니다. 아래 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 | 상관관계 ID(X-Request-Id를 그대로 반환하거나 서버가 생성). |
| data.taskId | string (uuid) | 백그라운드 생성 작업 ID(대기열 연결용). |
| data.bookId | string (uuid) | 그림책 ID. GET /v1/stories/{id}의 경로 매개변수로 사용합니다. |
| data.status | string | 작업의 초기 상태. 접수 직후에는 보통 pending. 값: pending, processing, completed, failed. |
필드 표 — GET 200 data 객체, pages[] 항목 및 페이지 필드· 펼치기
| 필드 | 타입 | 설명 |
|---|---|---|
| id | string (uuid) | 책 ID(경로의 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 | 성공 응답과 같은 상관관계 ID. |
| 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분 안에 첫 그림책 연동을 출시할 수 있습니다.