Genera libri illustrati con l'IA dal tuo codice.
Un'API REST per gli abbonati Pro e Premium. Avvia una generazione, controlla lo stato e il libro finito compare automaticamente nella tua libreria ChildrenBooks, accanto a tutto ciò che hai creato dalla dashboard.
Sicuro per impostazione predefinita
Le chiavi API vengono mostrate una sola volta e salvate con hash SHA-256. Rotazione e revoca immediata dalla dashboard. Tutte le richieste richiedono TLS.
Limiti di utilizzo e protezione dagli abusi
I limiti al minuto, al giorno e al mese proteggono la tua quota in caso di fuga della chiave. Le risposte includono le intestazioni x-ratelimit-* così gli SDK possono rallentare in modo corretto.
Una libreria, una quota
I libri generati via API compaiono nella stessa libreria di quelli creati dalla dashboard. La quota è condivisa con il tuo piano Pro o Premium.
Guida rapida e riferimento API
Ottieni una chiave Pro o Premium dalla dashboard, poi esegui gli esempi. I corpi non validi restituiscono 400 / VALIDATION_ERROR; gli enum devono corrispondere esattamente (maiuscole e minuscole contano). Le risposte usano ok, requestId opzionale e data oppure error. Rispetta x-ratelimit-* e retry-after in caso di 429.
Prerequisiti
- 1. Passa a Pro o Premium. I piani gratuiti non possono generare chiavi API. Vedi i prezzi.
- 2. Apri la dashboard e fai clic su
Generate API key. Copiala subito: non verrà più mostrata. - 3. Invia la tua prima richiesta. Sostituisci
cbk_live_XXXcon la tua chiave:
Richiesta
POST /v1/stories
Crea un job asincrono che genera un libro illustrato per bambini. Il server mette il lavoro in coda e risponde subito con 202 Accepted; il corpo restituisce taskId e bookId per controllare l'avanzamento con GET /v1/stories/{bookId}. Ogni pagina (copertina inclusa) consuma un credito della quota del tuo piano.
Intestazioni
Autenticazione: x-api-key: cbk_live_… (consigliata) oppure Authorization: Bearer cbk_live_….
| Intestazione | Obbligatoria | Descrizione |
|---|---|---|
| content-type | Sì | Deve essere application/json. |
| Idempotency-Key | No | Chiave univoca opzionale per ogni creazione logica (es. un UUID). La stessa chiave entro 24 h con lo stesso corpo JSON restituisce i taskId / bookId originali (nessun secondo libro). La stessa chiave con un corpo diverso restituisce 409 / IDEMPOTENCY_CONFLICT. Lunghezza massima 128. Richiede Redis lato API; se Redis non è disponibile, la deduplicazione viene saltata. |
| X-Request-Id | No | Se impostato, viene restituito nelle risposte e nei log per il tracciamento. Lunghezza massima 64; altrimenti lo genera il server. |
Corpo JSON
| Campo | Tipo | Vincoli | Dettagli e valori ammessi |
|---|---|---|---|
| storyIdea | string | Obbligatorio. Lunghezza 10–8000 caratteri. | Descrizione del libro in linguaggio semplice (trama, personaggi, ambientazione). Non è un modello di prompt: scrivi di cosa vuoi che parli la storia. |
| ageRange | string (enum) | Obbligatorio. Deve corrispondere esattamente a un valore ammesso (maiuscole e minuscole contano). | Fascia d'età di lettura (lessico e temi): 0-3, 4-7, 8-12 |
| style | string (enum) | Obbligatorio. Un valore dell'enum. Maiuscole e minuscole contano: usa 3d, non "3D". | Stile artistico delle illustrazioni.
|
| pageCount | integer | Obbligatorio. Intero 6–15 inclusi. 1 credito per pagina. | Numero totale di pagine, copertina inclusa. Ogni pagina viene conteggiata nei crediti mensili del piano. |
| tone | string (enum) | Obbligatorio. Enum in snake_case: invia la stringa esattamente come definita. | Atmosfera / genere del racconto.
|
| language | string (enum) | Obbligatorio. Solo chiavi inglesi in minuscolo (es. english, non en). | Lingua del testo generato: english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian |
Chiamata minima con le intestazioni e i campi JSON sopra (sostituisci la chiave con la tua). cURL e TypeScript sono la stessa richiesta: scegli una scheda. Conserva la chiave in una variabile d'ambiente lato server; non esporla mai nel codice del browser.
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"
}'Risposta
Restituita con 202 Accepted quando il job è in coda, con la stessa struttura ok / data delle altre risposte di successo. Payload di esempio; le tabelle dei campi espandibili (POST 202 e altro) si trovano in Risposta.
{
"ok": true,
"requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"bookId": "660e8400-e29b-41d4-a716-446655440001",
"status": "pending"
}
}GET /v1/stories/{id}
Recupera i metadati di un libro, lo stato della generazione, l'avanzamento e le pagine già scritte. Usa il bookId di POST /v1/stories. Ricevi solo i libri dell'utente proprietario della chiave API; id inesistenti o di altri utenti restituiscono 404.
Parametri di percorso
| Parametro | Posizione | Regole |
|---|---|---|
| id | path | Il bookId restituito da POST. Deve essere un UUID. Vedi solo i libri del proprietario della chiave API. |
Polling
La generazione è asincrona: interroga GET /v1/stories/{bookId} finché data.status non diventa completed o failed. Il corpo JSON 200 completo è riportato in Risposta. Il cURL e il TypeScript qui sotto sono la stessa richiesta: cambia scheda.
curl https://api.childrenbooks.online/v1/stories/<bookId> \
-H "x-api-key: cbk_live_XXXXXXXXXXXX"Risposta
Esempi e riferimento dei campi per risposte di successo e di errore. L'ordine dei campi può variare; null può essere esplicito o omesso.
{
"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"
}
}
}Tabelle dei campi — corpo POST 202 (taskId, bookId, status)· espandi
| Campo | Tipo | Descrizione |
|---|---|---|
| ok | boolean | Sempre true per questa risposta. |
| requestId | string | Id di correlazione (eco di X-Request-Id o generato dal server). |
| data.taskId | string (uuid) | Id del task di generazione in background (correlazione con la coda). |
| data.bookId | string (uuid) | Id del libro: usalo come parametro di percorso in GET /v1/stories/{id}. |
| data.status | string | Stato iniziale del job, di solito pending subito dopo l'accettazione. Valori: pending, processing, completed, failed. |
Tabelle dei campi — oggetto data di GET 200, elementi di pages[] e campi pagina· espandi
| Campo | Tipo | Descrizione |
|---|---|---|
| id | string (uuid) | Id del libro (uguale all'id del percorso). |
| title | string | null | Titolo generato o modificato. |
| slug | string | null | Slug dell'URL del libro sul sito, se presente. |
| coverImage | string | null | URL della copertina. |
| summary | string | null | Breve sinossi. |
| storyIdea | string | null | L'idea della storia salvata nel libro. |
| ageRange | string | null | Eco del valore inviato (es. 4-7). |
| style | string | null | Chiave dello stile di illustrazione. |
| pageCount | integer | null | Numero di pagine previsto (copertina inclusa). |
| tone | string | null | Chiave di atmosfera / genere. |
| language | string | null | Chiave della lingua della storia. |
| source | string | null | Dove è stato creato il libro: web, api, hf (oppure null). |
| storageProvider | string | null | Identificativo dello storage dei file, se applicabile. |
| createdAt | string | null | Timestamp ISO 8601 di creazione del record del libro. |
| updatedAt | string | null | Timestamp ISO 8601 dell'ultimo aggiornamento del libro. |
| status | string | Stato dell'ultimo task di generazione: pending, processing, completed, failed, unknown. unknown se non esiste ancora alcun task. |
| progress | integer | Percentuale approssimativa 0–100 dell'ultimo task (predefinito 0). |
| errorMessage | string | null | Motivo leggibile dell'errore quando status è failed. |
| completedAt | string | null | Timestamp ISO 8601 di fine generazione, se presente. |
| pages | array | Elenco ordinato delle pagine (vedi la tabella successiva). Cresce man mano che illustrazioni e testi vengono scritti. |
data.pages[] — ogni elemento
| Campo | Tipo | Descrizione |
|---|---|---|
| index | integer | Indice di ordinamento della pagina (crescente insieme alle altre). |
| title | string | null | Titolo della pagina. |
| content | string | null | Testo della pagina. |
| imageUrl | string | null | URL dell'illustrazione di questa pagina. |
Corpo di errore
Usa error.code per la logica; error.message serve solo per la visualizzazione.
Tabella dei campi — oggetto error· espandi
| Campo | Tipo | Descrizione |
|---|---|---|
| ok | boolean | Sempre false. |
| requestId | string | Stesso id di correlazione delle risposte di successo. |
| error.code | string | Codice di errore leggibile dalla macchina (vedi l'elenco sotto). |
| error.message | string | Messaggio leggibile (non basare la logica sul testo esatto). |
| error.fields | object | undefined | Mappa opzionale nome campo → messaggio di validazione (frequente con VALIDATION_ERROR). |
| error.meta | object | undefined | Contesto aggiuntivo opzionale dal server (la struttura può variare). |
Valori di 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
Limiti
| Piano | Al minuto | Al giorno (libri) | Quota mensile |
|---|---|---|---|
| Pro | 60 richieste | 50 libri | Condivisa con i crediti del piano |
| Premium | 200 richieste | 200 libri | Condivisa con i crediti del piano |
Quando si raggiunge un limite, l'API restituisce 429 con retry-after in secondi. Ogni risposta include anche x-ratelimit-remaining, così il client può rallentare in anticipo.
Regole di utilizzo
- • Le chiavi API appartengono a un solo utente. Non condividerle tra account.
- • Non generare contenuti che violino i nostri Termini di servizio, inclusi contenuti sessuali che coinvolgono minori, violenza reale o personaggi protetti da copyright.
- • Conserva i segreti in variabili d'ambiente lato server. Non inserire mai una chiave API nel codice del browser.
- • In caso di utilizzo abusivo (picchi di traffico, cambi di IP tra continenti in pochi minuti) possiamo ruotare o revocare una chiave e contattarti via email.
- • Il passaggio al piano gratuito revoca subito la chiave.
Pronto a iniziare?
Accedi, attiva la tua chiave API dalla dashboard e pubblica la tua prima integrazione in meno di 10 minuti.