Developer API · v1

Gere livros ilustrados com IA a partir do seu código.

Uma API REST para assinantes Pro e Premium. Inicie uma geração, consulte o status, e o livro pronto aparece automaticamente na sua biblioteca ChildrenBooks, junto com tudo o que você criou pelo painel.

Seguro por padrão

As chaves de API são exibidas uma única vez e armazenadas com hash SHA-256. Rotação e revogação imediata pelo painel. Todas as requisições exigem TLS.

Com limites e resistente a abusos

Limites por minuto, por dia e por mês protegem sua cota em caso de vazamento. As respostas incluem cabeçalhos x-ratelimit-* para que os SDKs reduzam o ritmo com elegância.

Uma biblioteca, uma cota

Os livros gerados pela API aparecem na mesma biblioteca dos criados pelo painel. A cota é compartilhada com seu plano Pro ou Premium.

Início rápido e referência da API

Obtenha uma chave Pro ou Premium no painel e execute os exemplos. Corpos inválidos retornam 400 / VALIDATION_ERROR; os enums precisam corresponder exatamente (diferenciando maiúsculas). As respostas usam ok, requestId opcional e data ou error. Respeite x-ratelimit-* e retry-after ao receber 429.

Pré-requisitos

  1. 1. Mude para Pro ou Premium. Planos gratuitos não podem emitir chaves de API. Ver preços.
  2. 2. Abra o painel e clique em Generate API key. Copie-a — ela não será exibida novamente.
  3. 3. Envie sua primeira requisição. Substitua cbk_live_XXX pela sua chave:

Requisição

POST /v1/stories

Cria uma tarefa assíncrona que gera um livro infantil ilustrado. O servidor coloca o trabalho na fila e responde na hora com 202 Accepted; o corpo retorna taskId e bookId para você acompanhar o progresso com GET /v1/stories/{bookId}. Cada página (capa incluída) consome um crédito da cota do seu plano.

Cabeçalhos

Autenticação: x-api-key: cbk_live_… (recomendado) ou Authorization: Bearer cbk_live_….

CabeçalhoObrigatórioDescrição
content-typeSimDeve ser application/json.
Idempotency-KeyNãoChave única opcional por criação lógica (ex.: UUID). A mesma chave em até 24 h com o mesmo corpo JSON retorna o taskId / bookId original (nenhum segundo livro). A mesma chave com outro corpo retorna 409 / IDEMPOTENCY_CONFLICT. Tamanho máximo 128. Requer Redis no lado da API; se o Redis estiver fora do ar, a deduplicação é ignorada.
X-Request-IdNãoSe informado, é devolvido nas respostas e nos logs para rastreamento. Tamanho máximo 64; caso contrário, o servidor gera um.
Corpo JSON
CampoTipoRestriçõesDetalhes e valores permitidos
storyIdeastringObrigatório. Comprimento de 10–8000 caracteres.Descrição do livro em linguagem simples (enredo, personagens, cenário). Não é um modelo de prompt — escreva sobre o que você quer que a história seja.
ageRangestring (enum)Obrigatório. Deve corresponder exatamente a um valor permitido (diferencia maiúsculas).Faixa etária de leitura (vocabulário e temas): 0-3, 4-7, 8-12
stylestring (enum)Obrigatório. Um valor do enum. Diferencia maiúsculas — use 3d, não "3D".

Estilo artístico das ilustrações.

  • watercolor — Ilustração suave em aquarela.
  • oil_painting — Textura e pinceladas de pintura a óleo.
  • 3d — Visual 3D / CGI estilizado (envie a string 3d).
  • comic_style — Quadros e traços de quadrinhos ou graphic novel.
  • crayon — Traços de giz de cera, com jeito de desenho infantil.
  • colored_pencil — Textura e hachuras de lápis de cor.
  • paper_cut — Papel recortado / silhuetas em camadas.
pageCountintegerObrigatório. Inteiro de 6–15, inclusive. 1 crédito por página.Total de páginas incluindo a capa. Cada página conta nos créditos mensais do seu plano.
tonestring (enum)Obrigatório. Enum em snake_case — envie a string exatamente como definida.

Clima / gênero da narrativa.

  • playful_funny — Humor leve e divertido.
  • fantasy_magic — Contos de fadas, magia, mundos imaginários.
  • animal — Personagens animais e enredos ligados à natureza.
  • heartwarming — Emoções suaves, empatia e gentileza.
  • sci_fi — Espaço, robôs, tecnologia do futuro simples (adequada a crianças).
  • daily_life_basics — Rotinas, família, escola, sentimentos.
  • adventurous — Exploração, missões, suspense leve.
  • educational — Abordagem didática suave (números, hábitos, habilidades sociais).
languagestring (enum)Obrigatório. Apenas chaves em inglês e minúsculas (ex.: english, não en).

Idioma do texto gerado:

english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian

Chamada mínima com os cabeçalhos e campos JSON acima (troque a chave pela sua). cURL e TypeScript são a mesma requisição — escolha uma aba. Guarde a chave em uma variável de ambiente no servidor; nunca a exponha no código do navegador.

cURL — criar um livro
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"
  }'

Resposta

Retornada com 202 Accepted quando a tarefa entra na fila — mesmo envelope ok / data das outras respostas de sucesso. Exemplo de conteúdo; as tabelas de campos recolhíveis (POST 202 e mais) estão em Resposta.

POST /v1/stories — 202 Accepted (corpo)
json
{
  "ok": true,
  "requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "bookId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "pending"
  }
}

GET /v1/stories/{id}

Retorna os metadados de um livro, o status da geração, o progresso e as páginas já gravadas. Use o bookId de POST /v1/stories. Você só recebe livros do mesmo usuário da chave de API; ids inexistentes ou de outros usuários retornam 404.

Parâmetros de caminho
ParâmetroLocalRegras
idpathO bookId retornado por POST. Deve ser um UUID. Você só vê livros do dono da chave de API.
Consulta periódica

A geração é assíncrona — consulte GET /v1/stories/{bookId} até que data.status seja completed ou failed. O corpo JSON 200 completo aparece em Resposta. O cURL e o TypeScript abaixo são a mesma consulta — troque de aba.

cURL — consultar status
bash
curl https://api.childrenbooks.online/v1/stories/<bookId> \
  -H "x-api-key: cbk_live_XXXXXXXXXXXX"

Resposta

Exemplos e referência de campos para respostas de sucesso e de erro. A ordem dos campos pode variar; null pode aparecer explicitamente ou ser omitido.

GET /v1/stories/{id} — 200 OK (corpo de exemplo, ex.: durante o processamento)
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"
      }
    ]
  }
}
Erro — 400 / 401 / 429 / … (corpo)
json
{
  "ok": false,
  "requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "fields": {
      "pageCount": "Expected number between 6 and 15"
    }
  }
}
Tabelas de campos — corpo do POST 202 (taskId, bookId, status)· expandir
CampoTipoDescrição
okbooleanSempre true nesta resposta.
requestIdstringId de correlação (eco de X-Request-Id ou gerado pelo servidor).
data.taskIdstring (uuid)Id da tarefa de geração em segundo plano (correlação de fila).
data.bookIdstring (uuid)Id do livro — use como parâmetro de caminho em GET /v1/stories/{id}.
data.statusstringStatus inicial da tarefa. Normalmente pending logo após o aceite. Valores: pending, processing, completed, failed.
Tabelas de campos — objeto data do GET 200, itens de pages[] e campos de página· expandir
CampoTipoDescrição
idstring (uuid)Id do livro (igual ao id do caminho).
titlestring | nullTítulo gerado ou editado.
slugstring | nullSlug da URL do livro no site, quando houver.
coverImagestring | nullURL da capa.
summarystring | nullSinopse curta.
storyIdeastring | nullA ideia da história salva no livro.
ageRangestring | nullEco do valor enviado (ex.: 4-7).
stylestring | nullChave do estilo de ilustração.
pageCountinteger | nullNúmero de páginas desejado (inclui a capa).
tonestring | nullChave de clima / gênero.
languagestring | nullChave do idioma da história.
sourcestring | nullOnde o livro foi criado: web, api, hf (ou null).
storageProviderstring | nullIdentificador do armazenamento dos arquivos, quando aplicável.
createdAtstring | nullData ISO 8601 de criação do registro do livro.
updatedAtstring | nullData ISO 8601 da última atualização do livro.
statusstringStatus da última tarefa de geração: pending, processing, completed, failed, unknown. unknown se ainda não houver tarefa.
progressintegerPercentual aproximado 0–100 da última tarefa (padrão 0).
errorMessagestring | nullMotivo legível da falha quando status é failed.
completedAtstring | nullData ISO 8601 de conclusão da geração, quando houver.
pagesarrayLista ordenada de páginas (veja a próxima tabela). Cresce conforme ilustrações e textos são gravados.

data.pages[] — cada elemento

CampoTipoDescrição
indexintegerÍndice de ordem da página (ordenado de forma crescente).
titlestring | nullTítulo da página.
contentstring | nullTexto da página.
imageUrlstring | nullURL da ilustração desta página.

Corpo de erro

Use error.code na lógica; error.message serve apenas para exibição.

Tabela de campos — objeto error· expandir
CampoTipoDescrição
okbooleanSempre false.
requestIdstringMesmo id de correlação das respostas de sucesso.
error.codestringCódigo de erro legível por máquina (veja a lista abaixo).
error.messagestringMensagem legível (não dependa do texto exato na lógica).
error.fieldsobject | undefinedMapa opcional campo → mensagem de validação (comum com VALIDATION_ERROR).
error.metaobject | undefinedContexto extra opcional do servidor (a estrutura pode variar).

Valores de 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

Limites

PlanoPor minutoPor dia (livros)Cota mensal
Pro60 requisições50 livrosCompartilhada com os créditos do plano
Premium200 requisições200 livrosCompartilhada com os créditos do plano

Ao atingir um limite, a API retorna 429 com retry-after em segundos. Toda resposta também inclui x-ratelimit-remaining para que seu cliente desacelere antes.

Política de uso

  • • Chaves de API pertencem a um único usuário. Não as compartilhe entre contas.
  • • Não gere conteúdo que viole nossos Termos de Serviço, incluindo conteúdo sexual envolvendo menores, violência real ou personagens protegidos por direitos autorais.
  • • Guarde segredos em variáveis de ambiente no servidor. Nunca inclua uma chave de API no código do navegador.
  • • Podemos trocar ou revogar uma chave diante de padrões abusivos (picos de tráfego, saltos de IP entre continentes em minutos) e entraremos em contato por e-mail.
  • • Voltar ao plano gratuito revoga a chave na hora.

Pronto para começar?

Entre, ative sua chave de API no painel e publique sua primeira integração de livros em menos de 10 minutos.

API para desenvolvedores ChildrenBooks – Gere livros com IA a partir do seu código | ChildrenBooks