Developer API · v1

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. 1. Passa a Pro o Premium. I piani gratuiti non possono generare chiavi API. Vedi i prezzi.
  2. 2. Apri la dashboard e fai clic su Generate API key. Copiala subito: non verrà più mostrata.
  3. 3. Invia la tua prima richiesta. Sostituisci cbk_live_XXX con 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_….

IntestazioneObbligatoriaDescrizione
content-typeSìDeve essere application/json.
Idempotency-KeyNoChiave 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-IdNoSe impostato, viene restituito nelle risposte e nei log per il tracciamento. Lunghezza massima 64; altrimenti lo genera il server.
Corpo JSON
CampoTipoVincoliDettagli e valori ammessi
storyIdeastringObbligatorio. 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.
ageRangestring (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
stylestring (enum)Obbligatorio. Un valore dell'enum. Maiuscole e minuscole contano: usa 3d, non "3D".

Stile artistico delle illustrazioni.

  • watercolor — Illustrazione delicata ad acquerello.
  • oil_painting — Texture e pennellate da pittura a olio.
  • 3d — Resa 3D / CGI stilizzata (invia la stringa 3d).
  • comic_style — Vignette e chine da fumetto o graphic novel.
  • crayon — Tratti a pastello a cera, aria da disegno di bambino.
  • colored_pencil — Texture e tratteggi a matite colorate.
  • paper_cut — Carta ritagliata / sagome a strati.
pageCountintegerObbligatorio. Intero 6–15 inclusi. 1 credito per pagina.Numero totale di pagine, copertina inclusa. Ogni pagina viene conteggiata nei crediti mensili del piano.
tonestring (enum)Obbligatorio. Enum in snake_case: invia la stringa esattamente come definita.

Atmosfera / genere del racconto.

  • playful_funny — Umorismo leggero e buffo.
  • fantasy_magic — Fiabe, magia, mondi immaginari.
  • animal — Personaggi animali e trame legate alla natura.
  • heartwarming — Emozioni delicate, empatia e gentilezza.
  • sci_fi — Spazio, robot, tecnologia del futuro semplice (adatta ai bambini).
  • daily_life_basics — Routine quotidiane, famiglia, scuola, emozioni.
  • adventurous — Esplorazione, missioni, leggera suspense.
  • educational — Taglio educativo leggero (numeri, abitudini, abilità sociali).
languagestring (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 — crea un libro
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"
  }'

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.

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}

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
ParametroPosizioneRegole
idpathIl 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 — controlla lo stato
bash
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.

GET /v1/stories/{id} — 200 OK (corpo di esempio, ad es. durante l'elaborazione)
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"
      }
    ]
  }
}
Errore — 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"
    }
  }
}
Tabelle dei campi — corpo POST 202 (taskId, bookId, status)· espandi
CampoTipoDescrizione
okbooleanSempre true per questa risposta.
requestIdstringId di correlazione (eco di X-Request-Id o generato dal server).
data.taskIdstring (uuid)Id del task di generazione in background (correlazione con la coda).
data.bookIdstring (uuid)Id del libro: usalo come parametro di percorso in GET /v1/stories/{id}.
data.statusstringStato 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
CampoTipoDescrizione
idstring (uuid)Id del libro (uguale all'id del percorso).
titlestring | nullTitolo generato o modificato.
slugstring | nullSlug dell'URL del libro sul sito, se presente.
coverImagestring | nullURL della copertina.
summarystring | nullBreve sinossi.
storyIdeastring | nullL'idea della storia salvata nel libro.
ageRangestring | nullEco del valore inviato (es. 4-7).
stylestring | nullChiave dello stile di illustrazione.
pageCountinteger | nullNumero di pagine previsto (copertina inclusa).
tonestring | nullChiave di atmosfera / genere.
languagestring | nullChiave della lingua della storia.
sourcestring | nullDove è stato creato il libro: web, api, hf (oppure null).
storageProviderstring | nullIdentificativo dello storage dei file, se applicabile.
createdAtstring | nullTimestamp ISO 8601 di creazione del record del libro.
updatedAtstring | nullTimestamp ISO 8601 dell'ultimo aggiornamento del libro.
statusstringStato dell'ultimo task di generazione: pending, processing, completed, failed, unknown. unknown se non esiste ancora alcun task.
progressintegerPercentuale approssimativa 0–100 dell'ultimo task (predefinito 0).
errorMessagestring | nullMotivo leggibile dell'errore quando status è failed.
completedAtstring | nullTimestamp ISO 8601 di fine generazione, se presente.
pagesarrayElenco ordinato delle pagine (vedi la tabella successiva). Cresce man mano che illustrazioni e testi vengono scritti.

data.pages[] — ogni elemento

CampoTipoDescrizione
indexintegerIndice di ordinamento della pagina (crescente insieme alle altre).
titlestring | nullTitolo della pagina.
contentstring | nullTesto della pagina.
imageUrlstring | nullURL 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
CampoTipoDescrizione
okbooleanSempre false.
requestIdstringStesso id di correlazione delle risposte di successo.
error.codestringCodice di errore leggibile dalla macchina (vedi l'elenco sotto).
error.messagestringMessaggio leggibile (non basare la logica sul testo esatto).
error.fieldsobject | undefinedMappa opzionale nome campo → messaggio di validazione (frequente con VALIDATION_ERROR).
error.metaobject | undefinedContesto 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

PianoAl minutoAl giorno (libri)Quota mensile
Pro60 richieste50 libriCondivisa con i crediti del piano
Premium200 richieste200 libriCondivisa 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.

API per sviluppatori ChildrenBooks – Genera libri illustrati con l'IA dal tuo codice | ChildrenBooks