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. Mude para Pro ou Premium. Planos gratuitos não podem emitir chaves de API. Ver preços.
- 2. Abra o painel e clique em
Generate API key. Copie-a — ela não será exibida novamente. - 3. Envie sua primeira requisição. Substitua
cbk_live_XXXpela 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çalho | Obrigatório | Descrição |
|---|---|---|
| content-type | Sim | Deve ser application/json. |
| Idempotency-Key | Não | Chave ú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-Id | Não | Se informado, é devolvido nas respostas e nos logs para rastreamento. Tamanho máximo 64; caso contrário, o servidor gera um. |
Corpo JSON
| Campo | Tipo | Restrições | Detalhes e valores permitidos |
|---|---|---|---|
| storyIdea | string | Obrigató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. |
| ageRange | string (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 |
| style | string (enum) | Obrigatório. Um valor do enum. Diferencia maiúsculas — use 3d, não "3D". | Estilo artístico das ilustrações.
|
| pageCount | integer | Obrigató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. |
| tone | string (enum) | Obrigatório. Enum em snake_case — envie a string exatamente como definida. | Clima / gênero da narrativa.
|
| language | string (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 -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.
{
"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âmetro | Local | Regras |
|---|---|---|
| id | path | O 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 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.
{
"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"
}
}
}Tabelas de campos — corpo do POST 202 (taskId, bookId, status)· expandir
| Campo | Tipo | Descrição |
|---|---|---|
| ok | boolean | Sempre true nesta resposta. |
| requestId | string | Id de correlação (eco de X-Request-Id ou gerado pelo servidor). |
| data.taskId | string (uuid) | Id da tarefa de geração em segundo plano (correlação de fila). |
| data.bookId | string (uuid) | Id do livro — use como parâmetro de caminho em GET /v1/stories/{id}. |
| data.status | string | Status 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
| Campo | Tipo | Descrição |
|---|---|---|
| id | string (uuid) | Id do livro (igual ao id do caminho). |
| title | string | null | Título gerado ou editado. |
| slug | string | null | Slug da URL do livro no site, quando houver. |
| coverImage | string | null | URL da capa. |
| summary | string | null | Sinopse curta. |
| storyIdea | string | null | A ideia da história salva no livro. |
| ageRange | string | null | Eco do valor enviado (ex.: 4-7). |
| style | string | null | Chave do estilo de ilustração. |
| pageCount | integer | null | Número de páginas desejado (inclui a capa). |
| tone | string | null | Chave de clima / gênero. |
| language | string | null | Chave do idioma da história. |
| source | string | null | Onde o livro foi criado: web, api, hf (ou null). |
| storageProvider | string | null | Identificador do armazenamento dos arquivos, quando aplicável. |
| createdAt | string | null | Data ISO 8601 de criação do registro do livro. |
| updatedAt | string | null | Data ISO 8601 da última atualização do livro. |
| status | string | Status da última tarefa de geração: pending, processing, completed, failed, unknown. unknown se ainda não houver tarefa. |
| progress | integer | Percentual aproximado 0–100 da última tarefa (padrão 0). |
| errorMessage | string | null | Motivo legível da falha quando status é failed. |
| completedAt | string | null | Data ISO 8601 de conclusão da geração, quando houver. |
| pages | array | Lista ordenada de páginas (veja a próxima tabela). Cresce conforme ilustrações e textos são gravados. |
data.pages[] — cada elemento
| Campo | Tipo | Descrição |
|---|---|---|
| index | integer | Índice de ordem da página (ordenado de forma crescente). |
| title | string | null | Título da página. |
| content | string | null | Texto da página. |
| imageUrl | string | null | URL 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
| Campo | Tipo | Descrição |
|---|---|---|
| ok | boolean | Sempre false. |
| requestId | string | Mesmo id de correlação das respostas de sucesso. |
| error.code | string | Código de erro legível por máquina (veja a lista abaixo). |
| error.message | string | Mensagem legível (não dependa do texto exato na lógica). |
| error.fields | object | undefined | Mapa opcional campo → mensagem de validação (comum com VALIDATION_ERROR). |
| error.meta | object | undefined | Contexto 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
| Plano | Por minuto | Por dia (livros) | Cota mensal |
|---|---|---|---|
| Pro | 60 requisições | 50 livros | Compartilhada com os créditos do plano |
| Premium | 200 requisições | 200 livros | Compartilhada 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.