KI-Bilderbücher direkt aus deinem Code.
Eine REST-API für Pro- und Premium-Abonnenten. Starte einen Generierungsauftrag, frage den Status ab, und das fertige Buch erscheint automatisch in deiner ChildrenBooks-Bibliothek – neben allem, was du im Dashboard erstellt hast.
Standardmäßig sicher
API-Schlüssel werden nur einmal angezeigt und als SHA-256-Hash gespeichert. Rotation und sofortiger Widerruf im Dashboard. Alle Anfragen erfordern TLS.
Ratenbegrenzt und missbrauchssicher
Limits pro Minute, Tag und Monat schützen dein Kontingent bei einem Leak. Antworten enthalten x-ratelimit-*-Header, damit SDKs sauber drosseln können.
Eine Bibliothek, ein Kontingent
Per API erstellte Bücher erscheinen in derselben Bibliothek wie im Dashboard erstellte. Das Kontingent wird mit deinem Pro- oder Premium-Tarif geteilt.
Schnellstart & API-Referenz
Hol dir im Dashboard einen Pro- oder Premium-Schlüssel und führe die Beispiele aus. Ungültige Bodys liefern 400 / VALIDATION_ERROR; Enums müssen exakt übereinstimmen (Groß-/Kleinschreibung beachten). Antworten enthalten ok, optional requestId sowie data oder error. Beachte bei 429 die Header x-ratelimit-* und retry-after.
Voraussetzungen
- 1. Auf Pro oder Premium upgraden. Kostenlose Tarife können keine API-Schlüssel erstellen. Preise ansehen.
- 2. Dashboard öffnen und auf
Generate API keyklicken. Sofort kopieren – er wird nicht noch einmal angezeigt. - 3. Erste Anfrage senden. Ersetze
cbk_live_XXXdurch deinen Schlüssel:
Anfrage
POST /v1/stories
Legt einen asynchronen Auftrag für ein illustriertes Kinderbuch an. Der Server stellt die Arbeit in die Warteschlange und antwortet sofort mit 202 Accepted; der Body enthält taskId und bookId, damit du den Fortschritt über GET /v1/stories/{bookId} abfragen kannst. Jede Seite (inklusive Cover) verbraucht ein Guthaben aus deinem Tarifkontingent.
Header
Authentifizierung: x-api-key: cbk_live_… (empfohlen) oder Authorization: Bearer cbk_live_….
| Header | Pflicht | Beschreibung |
|---|---|---|
| content-type | Ja | Muss application/json sein. |
| Idempotency-Key | Nein | Optionaler eindeutiger Schlüssel pro logischer Erstellung (z. B. UUID). Derselbe Schlüssel innerhalb von 24 h mit gleichem JSON-Body liefert die ursprüngliche taskId / bookId (kein zweites Buch). Derselbe Schlüssel mit anderem Body liefert 409 / IDEMPOTENCY_CONFLICT. Maximal 128 Zeichen. Benötigt Redis auf API-Seite; ist Redis nicht erreichbar, entfällt die Deduplizierung. |
| X-Request-Id | Nein | Falls gesetzt, wird er in Antworten und Logs zur Nachverfolgung zurückgegeben. Maximal 64 Zeichen; sonst erzeugt der Server einen. |
JSON-Body
| Feld | Typ | Vorgaben | Details & erlaubte Werte |
|---|---|---|---|
| storyIdea | string | Pflicht. Länge 10–8000 Zeichen. | Beschreibung des Buchs in einfachen Worten (Handlung, Figuren, Schauplatz). Keine Prompt-Vorlage – schreib einfach, worum es in der Geschichte gehen soll. |
| ageRange | string (enum) | Pflicht. Muss genau einem erlaubten Wert entsprechen (Groß-/Kleinschreibung beachten). | Ziel-Altersgruppe (Wortschatz & Themen): 0-3, 4-7, 8-12 |
| style | string (enum) | Pflicht. Ein Enum-Wert. Groß-/Kleinschreibung beachten – 3d, nicht „3D“. | Zeichenstil der Illustrationen.
|
| pageCount | integer | Pflicht. Ganzzahl 6–15 (einschließlich). 1 Guthaben pro Seite. | Seitenzahl inklusive Cover. Jede Seite wird auf das monatliche Guthaben deines Tarifs angerechnet. |
| tone | string (enum) | Pflicht. Enum in snake_case – den String genau wie definiert senden. | Stimmung / Genre der Geschichte.
|
| language | string (enum) | Pflicht. Nur englische Schlüssel in Kleinbuchstaben (z. B. english, nicht en). | Sprache des erzeugten Textes: english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian |
Minimaler Aufruf mit den obigen Headern und JSON-Feldern (Schlüssel durch deinen ersetzen). cURL und TypeScript sind dieselbe Anfrage – wähle einen Tab. Bewahre den Schlüssel in einer serverseitigen Umgebungsvariable auf; nie im Browser-Code.
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"
}'Antwort
Wird mit 202 Accepted zurückgegeben, sobald der Auftrag in der Warteschlange ist – mit demselben ok / data-Umschlag wie andere Erfolgsantworten. Beispiel-Payload; ausklappbare Feldtabellen (POST 202 und mehr) findest du unter Antwort.
{
"ok": true,
"requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"bookId": "660e8400-e29b-41d4-a716-446655440001",
"status": "pending"
}
}GET /v1/stories/{id}
Liefert Metadaten, Generierungsstatus, Fortschritt und bisher geschriebene Seiten eines Bilderbuchs. Verwende die bookId aus POST /v1/stories. Du erhältst nur Bücher des Nutzers, dem der API-Schlüssel gehört; unbekannte oder fremde IDs liefern 404.
Pfadparameter
| Parameter | Ort | Regeln |
|---|---|---|
| id | path | Die von POST zurückgegebene bookId. Muss eine UUID sein. Du siehst nur Bücher des Schlüsselinhabers. |
Abfragen (Polling)
Die Generierung läuft asynchron – frage GET /v1/stories/{bookId} ab, bis data.status completed oder failed ist. Der vollständige 200-JSON-Body steht unter Antwort. cURL und TypeScript unten sind dieselbe Abfrage – per Tab wechseln.
curl https://api.childrenbooks.online/v1/stories/<bookId> \
-H "x-api-key: cbk_live_XXXXXXXXXXXX"Antwort
Beispiele und Feldreferenz für Erfolgs- und Fehlerantworten. Die Feldreihenfolge kann variieren; null kann explizit stehen oder fehlen.
{
"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"
}
}
}Feldtabellen — POST-202-Body (taskId, bookId, status)· aufklappen
| Feld | Typ | Beschreibung |
|---|---|---|
| ok | boolean | Bei dieser Antwort immer true. |
| requestId | string | Korrelations-ID (Echo von X-Request-Id oder vom Server erzeugt). |
| data.taskId | string (uuid) | ID des Hintergrund-Generierungsauftrags (Warteschlangen-Korrelation). |
| data.bookId | string (uuid) | Bilderbuch-ID – als Pfadparameter für GET /v1/stories/{id} verwenden. |
| data.status | string | Anfangsstatus des Auftrags, direkt nach Annahme meist pending. Werte: pending, processing, completed, failed. |
Feldtabellen — data-Objekt von GET 200, pages[]-Einträge und Seitenfelder· aufklappen
| Feld | Typ | Beschreibung |
|---|---|---|
| id | string (uuid) | Buch-ID (identisch mit der id im Pfad). |
| title | string | null | Erzeugter oder bearbeiteter Titel. |
| slug | string | null | URL-Slug des Buchs auf der Website, falls vorhanden. |
| coverImage | string | null | URL des Covers. |
| summary | string | null | Kurze Inhaltsangabe. |
| storyIdea | string | null | Die beim Buch gespeicherte Geschichtsidee. |
| ageRange | string | null | Echo des Anfragewerts (z. B. 4-7). |
| style | string | null | Schlüssel des Illustrationsstils. |
| pageCount | integer | null | Ziel-Seitenzahl (inklusive Cover). |
| tone | string | null | Schlüssel für Stimmung / Genre. |
| language | string | null | Sprachschlüssel der Geschichte. |
| source | string | null | Wo das Buch erstellt wurde: web, api, hf (oder null). |
| storageProvider | string | null | Kennung des Speicher-Backends für die Dateien, falls zutreffend. |
| createdAt | string | null | ISO-8601-Zeitstempel der Erstellung des Buchdatensatzes. |
| updatedAt | string | null | ISO-8601-Zeitstempel der letzten Änderung am Buch. |
| status | string | Status des letzten Generierungsauftrags: pending, processing, completed, failed, unknown. unknown, wenn noch kein Auftrag existiert. |
| progress | integer | Ungefährer Fortschritt 0–100 des letzten Auftrags (Standard 0). |
| errorMessage | string | null | Lesbarer Fehlergrund, wenn status failed ist. |
| completedAt | string | null | ISO-8601-Zeitstempel des Generierungsendes, falls gesetzt. |
| pages | array | Geordnete Liste der Seitenobjekte (siehe nächste Tabelle). Wächst, während Illustrationen und Texte geschrieben werden. |
data.pages[] — jedes Element
| Feld | Typ | Beschreibung |
|---|---|---|
| index | integer | Reihenfolge-Index der Seite (aufsteigend sortiert). |
| title | string | null | Seitentitel oder Überschrift. |
| content | string | null | Seitentext. |
| imageUrl | string | null | URL der Illustration dieser Seite. |
Fehler-Body
Verwende error.code für die Logik; error.message dient nur der Anzeige.
Feldtabelle — error-Objekt· aufklappen
| Feld | Typ | Beschreibung |
|---|---|---|
| ok | boolean | Immer false. |
| requestId | string | Gleiche Korrelations-ID wie bei Erfolgsantworten. |
| error.code | string | Maschinenlesbarer Fehlercode (siehe Liste unten). |
| error.message | string | Lesbare Meldung (Logik nicht vom genauen Wortlaut abhängig machen). |
| error.fields | object | undefined | Optionale Zuordnung Feldname → Validierungsmeldung (häufig bei VALIDATION_ERROR). |
| error.meta | object | undefined | Optionaler zusätzlicher Kontext vom Server (Struktur kann variieren). |
Mögliche Werte für 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
Limits
| Tarif | Pro Minute | Pro Tag (Bücher) | Monatskontingent |
|---|---|---|---|
| Pro | 60 Anfragen | 50 Bücher | Geteilt mit dem Guthaben deines Tarifs |
| Premium | 200 Anfragen | 200 Bücher | Geteilt mit dem Guthaben deines Tarifs |
Wird ein Limit erreicht, antwortet die API mit 429 und retry-after in Sekunden. Jede Antwort enthält außerdem x-ratelimit-remaining, damit dein Client rechtzeitig drosseln kann.
Nutzungsrichtlinien
- • API-Schlüssel gehören zu genau einem Nutzer. Teile sie nicht zwischen Konten.
- • Erstelle keine Inhalte, die gegen unsere Nutzungsbedingungen verstoßen – etwa sexuelle Inhalte mit Minderjährigen, reale Gewalt oder urheberrechtlich geschützte Figuren.
- • Bewahre Geheimnisse in serverseitigen Umgebungsvariablen auf. Bette niemals einen API-Schlüssel in Browser-Code ein.
- • Bei missbräuchlichem Verhalten (Lastspitzen, IP-Wechsel über Kontinente hinweg innerhalb von Minuten) können wir einen Schlüssel rotieren oder widerrufen und dich per E-Mail kontaktieren.
- • Ein Wechsel zum kostenlosen Tarif widerruft den Schlüssel sofort.
Bereit loszulegen?
Melde dich an, aktiviere deinen API-Schlüssel im Dashboard und liefere deine erste Bilderbuch-Integration in unter 10 Minuten aus.