Developer API · v1

Générez des albums IA depuis votre code.

Une API REST pour les abonnés Pro et Premium. Lancez une génération, suivez son statut, et le livre terminé apparaît automatiquement dans votre bibliothèque ChildrenBooks, avec tout ce que vous avez créé depuis le tableau de bord.

Sécurisé par défaut

Les clés API ne sont affichées qu'une fois et stockées hachées en SHA-256. Rotation et révocation immédiate depuis le tableau de bord. Toutes les requêtes exigent TLS.

Limité et protégé contre les abus

Des limites par minute, par jour et par mois protègent votre quota en cas de fuite. Les réponses incluent des en-têtes x-ratelimit-* pour que les SDK ralentissent proprement.

Une bibliothèque, un quota

Les livres générés via l'API apparaissent dans la même bibliothèque que ceux créés depuis le tableau de bord. Le quota est partagé avec votre offre Pro ou Premium.

Démarrage rapide et référence de l'API

Obtenez une clé Pro ou Premium dans le tableau de bord, puis lancez les exemples. Un corps invalide renvoie 400 / VALIDATION_ERROR ; les enums doivent correspondre exactement (sensibles à la casse). Les réponses utilisent ok, requestId facultatif, et data ou error. Respectez x-ratelimit-* et retry-after en cas de 429.

Prérequis

  1. 1. Passez à Pro ou Premium. Les offres gratuites ne peuvent pas créer de clé API. Voir les tarifs.
  2. 2. Ouvrez le tableau de bord et cliquez sur Generate API key. Copiez-la : elle ne sera plus affichée.
  3. 3. Envoyez votre première requête. Remplacez cbk_live_XXX par votre clé :

Requête

POST /v1/stories

Crée une tâche asynchrone qui génère un album jeunesse illustré. Le serveur met la tâche en file et répond aussitôt 202 Accepted ; le corps renvoie taskId et bookId pour suivre la progression via GET /v1/stories/{bookId}. Chaque page (couverture comprise) consomme un crédit du quota de votre offre.

En-têtes

Authentification : x-api-key: cbk_live_… (recommandé) ou Authorization: Bearer cbk_live_….

En-têteObligatoireDescription
content-typeOuiDoit valoir application/json.
Idempotency-KeyNonClé unique facultative par création logique (ex. un UUID). La même clé sous 24 h avec le même corps JSON renvoie les taskId / bookId d'origine (pas de second livre). La même clé avec un autre corps renvoie 409 / IDEMPOTENCY_CONFLICT. Longueur max. 128. Nécessite Redis côté API ; si Redis est indisponible, la déduplication est ignorée.
X-Request-IdNonSi fourni, renvoyé dans les réponses et les journaux pour le traçage. Longueur max. 64 ; sinon le serveur en génère un.
Corps JSON
ChampTypeContraintesDétails et valeurs autorisées
storyIdeastringObligatoire. Longueur de 10 à 8000 caractères.Description en langage courant du livre (intrigue, personnages, décor). Ce n'est pas un modèle de prompt : écrivez simplement de quoi doit parler l'histoire.
ageRangestring (enum)Obligatoire. Doit correspondre exactement à une valeur autorisée (sensible à la casse).Tranche d'âge visée (vocabulaire et thèmes) : 0-3, 4-7, 8-12
stylestring (enum)Obligatoire. Une valeur de l'enum. Sensible à la casse : utilisez 3d, pas « 3D ».

Style graphique des illustrations.

  • watercolor — Illustration douce à l'aquarelle.
  • oil_painting — Texture et touche de peinture à l'huile.
  • 3d — Rendu 3D / CGI stylisé (envoyez la chaîne 3d).
  • comic_style — Cases et encrage de BD ou de roman graphique.
  • crayon — Traits de craie grasse, esprit dessin d'enfant.
  • colored_pencil — Texture et hachures de crayons de couleur.
  • paper_cut — Papier découpé / silhouettes superposées.
pageCountintegerObligatoire. Entier de 6 à 15 inclus. 1 crédit par page.Nombre total de pages, couverture comprise. Chaque page est décomptée des crédits mensuels de votre offre.
tonestring (enum)Obligatoire. Enum en snake_case : envoyez la chaîne exactement telle que définie.

Ambiance / genre du récit.

  • playful_funny — Humour léger et loufoque.
  • fantasy_magic — Contes, magie, mondes imaginaires.
  • animal — Personnages animaux et intrigues centrées sur la nature.
  • heartwarming — Émotions douces, empathie et gentillesse.
  • sci_fi — Espace, robots, technologies futures simples (adaptées aux enfants).
  • daily_life_basics — Routines, famille, école, émotions.
  • adventurous — Exploration, quêtes, léger suspense.
  • educational — Approche pédagogique douce (nombres, habitudes, compétences sociales).
languagestring (enum)Obligatoire. Clés anglaises en minuscules uniquement (ex. english, pas en).

Langue du texte généré :

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

Appel minimal avec les en-têtes et champs JSON ci-dessus (remplacez la clé par la vôtre). cURL et TypeScript font la même requête : choisissez un onglet. Gardez la clé dans une variable d'environnement côté serveur ; ne l'exposez jamais dans le code du navigateur.

cURL — créer un album
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"
  }'

Réponse

Renvoyée avec 202 Accepted une fois la tâche en file, avec la même enveloppe ok / data que les autres succès. Exemple de contenu ; les tables de champs dépliables (POST 202 et plus) se trouvent dans Réponse.

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

GET /v1/stories/{id}

Récupère les métadonnées d'un album, son statut de génération, sa progression et les pages déjà écrites. Utilisez le bookId renvoyé par POST /v1/stories. Vous ne recevez que les livres de l'utilisateur de la clé API ; un id inexistant ou d'un autre utilisateur renvoie 404.

Paramètres de chemin
ParamètreEmplacementRègles
idpathLe bookId renvoyé par POST. Doit être un UUID. Vous ne voyez que les livres de l'utilisateur de la clé API.
Interrogation

La génération est asynchrone : interrogez GET /v1/stories/{bookId} jusqu'à ce que data.status vaille completed ou failed. Le corps JSON 200 complet figure dans Réponse. Le cURL et le TypeScript ci-dessous font la même requête : changez d'onglet.

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

Réponse

Exemples et référence des champs pour les réponses de succès et d'erreur. L'ordre des champs peut varier ; null peut être explicite ou omis.

GET /v1/stories/{id} — 200 OK (exemple, p. ex. pendant le traitement)
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"
      }
    ]
  }
}
Erreur — 400 / 401 / 429 / … (corps)
json
{
  "ok": false,
  "requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "fields": {
      "pageCount": "Expected number between 6 and 15"
    }
  }
}
Tables de champs — corps POST 202 (taskId, bookId, status)· déplier
ChampTypeDescription
okbooleanToujours true pour cette réponse.
requestIdstringIdentifiant de corrélation (écho de X-Request-Id ou généré par le serveur).
data.taskIdstring (uuid)Identifiant de la tâche de génération en arrière-plan (corrélation de file).
data.bookIdstring (uuid)Identifiant de l'album, à utiliser comme paramètre de chemin de GET /v1/stories/{id}.
data.statusstringStatut initial de la tâche, généralement pending juste après l'acceptation. Valeurs : pending, processing, completed, failed.
Tables de champs — objet data de GET 200, éléments de pages[] et champs de page· déplier
ChampTypeDescription
idstring (uuid)Identifiant du livre (identique à l'id du chemin).
titlestring | nullTitre généré ou modifié.
slugstring | nullSlug d'URL du livre sur le site, le cas échéant.
coverImagestring | nullURL de la couverture.
summarystring | nullCourt résumé.
storyIdeastring | nullL'idée d'histoire enregistrée sur le livre.
ageRangestring | nullÉcho de la valeur envoyée (ex. 4-7).
stylestring | nullClé du style d'illustration.
pageCountinteger | nullNombre de pages visé (couverture comprise).
tonestring | nullClé d'ambiance / de genre.
languagestring | nullClé de langue de l'histoire.
sourcestring | nullOrigine du livre : web, api, hf (ou null).
storageProviderstring | nullIdentifiant du stockage des ressources, le cas échéant.
createdAtstring | nullHorodatage ISO 8601 de création du livre.
updatedAtstring | nullHorodatage ISO 8601 de la dernière mise à jour du livre.
statusstringStatut de la dernière tâche : pending, processing, completed, failed, unknown. unknown s'il n'existe encore aucune tâche.
progressintegerPourcentage approximatif 0–100 de la dernière tâche (0 par défaut).
errorMessagestring | nullRaison lisible de l'échec quand status vaut failed.
completedAtstring | nullHorodatage ISO 8601 de fin de génération, le cas échéant.
pagesarrayListe ordonnée des pages (voir table suivante). Elle s'allonge à mesure que les illustrations et les textes sont écrits.

data.pages[] — chaque élément

ChampTypeDescription
indexintegerIndex d'ordre de la page (tri croissant avec les autres pages).
titlestring | nullTitre de la page.
contentstring | nullTexte de la page.
imageUrlstring | nullURL de l'illustration de cette page.

Corps d'erreur

Basez votre logique sur error.code ; error.message sert uniquement à l'affichage.

Table de champs — objet error· déplier
ChampTypeDescription
okbooleanToujours false.
requestIdstringMême identifiant de corrélation que pour les succès.
error.codestringCode d'erreur lisible par machine (voir la liste ci-dessous).
error.messagestringMessage lisible (ne vous fiez pas au libellé exact dans votre logique).
error.fieldsobject | undefinedCorrespondance facultative champ → message de validation (fréquent avec VALIDATION_ERROR).
error.metaobject | undefinedContexte supplémentaire facultatif fourni par le serveur (structure variable).

Valeurs possibles 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

OffrePar minutePar jour (livres)Quota mensuel
Pro60 requêtes50 livresPartagé avec les crédits de votre offre
Premium200 requêtes200 livresPartagé avec les crédits de votre offre

Quand une limite est atteinte, l'API renvoie 429 avec retry-after en secondes. Chaque réponse inclut aussi x-ratelimit-remaining pour que votre client ralentisse à temps.

Règles d'utilisation

  • • Une clé API appartient à un seul utilisateur. Ne la partagez pas entre comptes.
  • • Ne générez pas de contenu contraire à nos Conditions d'utilisation, notamment du contenu sexuel impliquant des mineurs, de la violence réelle ou des personnages protégés par le droit d'auteur.
  • • Conservez les secrets dans des variables d'environnement côté serveur. N'intégrez jamais une clé API dans le code du navigateur.
  • • Nous pouvons renouveler ou révoquer une clé en cas d'usage abusif (pics de trafic, sauts d'IP entre continents en quelques minutes) et vous contacter par e-mail.
  • • Repasser à l'offre gratuite révoque immédiatement la clé.

Prêt à vous lancer ?

Connectez-vous, activez votre clé API dans le tableau de bord et livrez votre première intégration en moins de 10 minutes.

API développeurs ChildrenBooks – Générez des albums IA depuis votre code | ChildrenBooks