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. Passez à Pro ou Premium. Les offres gratuites ne peuvent pas créer de clé API. Voir les tarifs.
- 2. Ouvrez le tableau de bord et cliquez sur
Generate API key. Copiez-la : elle ne sera plus affichée. - 3. Envoyez votre première requête. Remplacez
cbk_live_XXXpar 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ête | Obligatoire | Description |
|---|---|---|
| content-type | Oui | Doit valoir application/json. |
| Idempotency-Key | Non | Clé 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-Id | Non | Si 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
| Champ | Type | Contraintes | Détails et valeurs autorisées |
|---|---|---|---|
| storyIdea | string | Obligatoire. 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. |
| ageRange | string (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 |
| style | string (enum) | Obligatoire. Une valeur de l'enum. Sensible à la casse : utilisez 3d, pas « 3D ». | Style graphique des illustrations.
|
| pageCount | integer | Obligatoire. 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. |
| tone | string (enum) | Obligatoire. Enum en snake_case : envoyez la chaîne exactement telle que définie. | Ambiance / genre du récit.
|
| language | string (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 -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.
{
"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ètre | Emplacement | Règles |
|---|---|---|
| id | path | Le 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 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.
{
"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"
}
}
}Tables de champs — corps POST 202 (taskId, bookId, status)· déplier
| Champ | Type | Description |
|---|---|---|
| ok | boolean | Toujours true pour cette réponse. |
| requestId | string | Identifiant de corrélation (écho de X-Request-Id ou généré par le serveur). |
| data.taskId | string (uuid) | Identifiant de la tâche de génération en arrière-plan (corrélation de file). |
| data.bookId | string (uuid) | Identifiant de l'album, à utiliser comme paramètre de chemin de GET /v1/stories/{id}. |
| data.status | string | Statut 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
| Champ | Type | Description |
|---|---|---|
| id | string (uuid) | Identifiant du livre (identique à l'id du chemin). |
| title | string | null | Titre généré ou modifié. |
| slug | string | null | Slug d'URL du livre sur le site, le cas échéant. |
| coverImage | string | null | URL de la couverture. |
| summary | string | null | Court résumé. |
| storyIdea | string | null | L'idée d'histoire enregistrée sur le livre. |
| ageRange | string | null | Écho de la valeur envoyée (ex. 4-7). |
| style | string | null | Clé du style d'illustration. |
| pageCount | integer | null | Nombre de pages visé (couverture comprise). |
| tone | string | null | Clé d'ambiance / de genre. |
| language | string | null | Clé de langue de l'histoire. |
| source | string | null | Origine du livre : web, api, hf (ou null). |
| storageProvider | string | null | Identifiant du stockage des ressources, le cas échéant. |
| createdAt | string | null | Horodatage ISO 8601 de création du livre. |
| updatedAt | string | null | Horodatage ISO 8601 de la dernière mise à jour du livre. |
| status | string | Statut de la dernière tâche : pending, processing, completed, failed, unknown. unknown s'il n'existe encore aucune tâche. |
| progress | integer | Pourcentage approximatif 0–100 de la dernière tâche (0 par défaut). |
| errorMessage | string | null | Raison lisible de l'échec quand status vaut failed. |
| completedAt | string | null | Horodatage ISO 8601 de fin de génération, le cas échéant. |
| pages | array | Liste ordonnée des pages (voir table suivante). Elle s'allonge à mesure que les illustrations et les textes sont écrits. |
data.pages[] — chaque élément
| Champ | Type | Description |
|---|---|---|
| index | integer | Index d'ordre de la page (tri croissant avec les autres pages). |
| title | string | null | Titre de la page. |
| content | string | null | Texte de la page. |
| imageUrl | string | null | URL 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
| Champ | Type | Description |
|---|---|---|
| ok | boolean | Toujours false. |
| requestId | string | Même identifiant de corrélation que pour les succès. |
| error.code | string | Code d'erreur lisible par machine (voir la liste ci-dessous). |
| error.message | string | Message lisible (ne vous fiez pas au libellé exact dans votre logique). |
| error.fields | object | undefined | Correspondance facultative champ → message de validation (fréquent avec VALIDATION_ERROR). |
| error.meta | object | undefined | Contexte 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
| Offre | Par minute | Par jour (livres) | Quota mensuel |
|---|---|---|---|
| Pro | 60 requêtes | 50 livres | Partagé avec les crédits de votre offre |
| Premium | 200 requêtes | 200 livres | Partagé 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.