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개가 차감됩니다.

헤더

인증: 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)필수. 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 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 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 키는 한 명의 사용자에게 귀속됩니다. 여러 계정에서 공유하지 마세요.
  • • 미성년자가 관련된 성적 콘텐츠, 실제 폭력, 저작권이 있는 캐릭터 등 서비스 약관을 위반하는 콘텐츠를 생성하지 마세요.
  • • 비밀 값은 서버의 환경 변수에 보관하세요. API 키를 브라우저 코드에 넣지 마세요.
  • • 남용 패턴(급격한 트래픽, 몇 분 사이 대륙을 넘나드는 IP 변경 등)이 감지되면 키를 교체하거나 폐기하고 이메일로 연락드릴 수 있습니다.
  • • 무료 요금제로 변경하면 키가 즉시 폐기됩니다.

시작할 준비가 되셨나요?

로그인하고 대시보드에서 API 키를 활성화하면 10분 안에 첫 그림책 연동을 출시할 수 있습니다.

ChildrenBooks 개발자 API – 코드로 AI 그림책 생성 | ChildrenBooks