Developer API · v1

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. 1. Auf Pro oder Premium upgraden. Kostenlose Tarife können keine API-Schlüssel erstellen. Preise ansehen.
  2. 2. Dashboard öffnen und auf Generate API key klicken. Sofort kopieren – er wird nicht noch einmal angezeigt.
  3. 3. Erste Anfrage senden. Ersetze cbk_live_XXX durch 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_….

HeaderPflichtBeschreibung
content-typeJaMuss application/json sein.
Idempotency-KeyNeinOptionaler 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-IdNeinFalls gesetzt, wird er in Antworten und Logs zur Nachverfolgung zurückgegeben. Maximal 64 Zeichen; sonst erzeugt der Server einen.
JSON-Body
FeldTypVorgabenDetails & erlaubte Werte
storyIdeastringPflicht. 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.
ageRangestring (enum)Pflicht. Muss genau einem erlaubten Wert entsprechen (Groß-/Kleinschreibung beachten).Ziel-Altersgruppe (Wortschatz & Themen): 0-3, 4-7, 8-12
stylestring (enum)Pflicht. Ein Enum-Wert. Groß-/Kleinschreibung beachten – 3d, nicht „3D“.

Zeichenstil der Illustrationen.

  • watercolor — Sanfter Aquarell-Look.
  • oil_painting — Ölgemälde-Textur und Pinselstriche.
  • 3d — 3D-gerenderter / stilisierter CGI-Look (den String 3d senden).
  • comic_style — Comic- oder Graphic-Novel-Panels und Tusche.
  • crayon — Wachsmalstriche, verspielter Kinderzeichnungs-Look.
  • colored_pencil — Buntstift-Textur und Schraffuren.
  • paper_cut — Scherenschnitt / geschichtete Silhouetten.
pageCountintegerPflicht. Ganzzahl 6–15 (einschließlich). 1 Guthaben pro Seite.Seitenzahl inklusive Cover. Jede Seite wird auf das monatliche Guthaben deines Tarifs angerechnet.
tonestring (enum)Pflicht. Enum in snake_case – den String genau wie definiert senden.

Stimmung / Genre der Geschichte.

  • playful_funny — Humorvoll, leicht und albern.
  • fantasy_magic — Märchen, Magie, Fantasiewelten.
  • animal — Tierfiguren und naturbezogene Handlungen.
  • heartwarming — Sanfte Gefühle, Empathie und Freundlichkeit.
  • sci_fi — Weltraum, Roboter, einfache Zukunftstechnik (kindgerecht).
  • daily_life_basics — Alltagsroutinen, Familie, Schule, Gefühle.
  • adventurous — Erkundung, Abenteuer, leichte Spannung.
  • educational — Sanfter Lernaspekt (Zahlen, Gewohnheiten, soziale Fähigkeiten).
languagestring (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 — Bilderbuch erstellen
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"
  }'

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.

POST /v1/stories — 202 Accepted (Body)
json
{
  "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
ParameterOrtRegeln
idpathDie 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 — Status abfragen
bash
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.

GET /v1/stories/{id} — 200 OK (Beispiel-Body, z. B. während der Verarbeitung)
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"
      }
    ]
  }
}
Fehler — 400 / 401 / 429 / … (Body)
json
{
  "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
FeldTypBeschreibung
okbooleanBei dieser Antwort immer true.
requestIdstringKorrelations-ID (Echo von X-Request-Id oder vom Server erzeugt).
data.taskIdstring (uuid)ID des Hintergrund-Generierungsauftrags (Warteschlangen-Korrelation).
data.bookIdstring (uuid)Bilderbuch-ID – als Pfadparameter für GET /v1/stories/{id} verwenden.
data.statusstringAnfangsstatus des Auftrags, direkt nach Annahme meist pending. Werte: pending, processing, completed, failed.
Feldtabellen — data-Objekt von GET 200, pages[]-Einträge und Seitenfelder· aufklappen
FeldTypBeschreibung
idstring (uuid)Buch-ID (identisch mit der id im Pfad).
titlestring | nullErzeugter oder bearbeiteter Titel.
slugstring | nullURL-Slug des Buchs auf der Website, falls vorhanden.
coverImagestring | nullURL des Covers.
summarystring | nullKurze Inhaltsangabe.
storyIdeastring | nullDie beim Buch gespeicherte Geschichtsidee.
ageRangestring | nullEcho des Anfragewerts (z. B. 4-7).
stylestring | nullSchlüssel des Illustrationsstils.
pageCountinteger | nullZiel-Seitenzahl (inklusive Cover).
tonestring | nullSchlüssel für Stimmung / Genre.
languagestring | nullSprachschlüssel der Geschichte.
sourcestring | nullWo das Buch erstellt wurde: web, api, hf (oder null).
storageProviderstring | nullKennung des Speicher-Backends für die Dateien, falls zutreffend.
createdAtstring | nullISO-8601-Zeitstempel der Erstellung des Buchdatensatzes.
updatedAtstring | nullISO-8601-Zeitstempel der letzten Änderung am Buch.
statusstringStatus des letzten Generierungsauftrags: pending, processing, completed, failed, unknown. unknown, wenn noch kein Auftrag existiert.
progressintegerUngefährer Fortschritt 0–100 des letzten Auftrags (Standard 0).
errorMessagestring | nullLesbarer Fehlergrund, wenn status failed ist.
completedAtstring | nullISO-8601-Zeitstempel des Generierungsendes, falls gesetzt.
pagesarrayGeordnete Liste der Seitenobjekte (siehe nächste Tabelle). Wächst, während Illustrationen und Texte geschrieben werden.

data.pages[] — jedes Element

FeldTypBeschreibung
indexintegerReihenfolge-Index der Seite (aufsteigend sortiert).
titlestring | nullSeitentitel oder Überschrift.
contentstring | nullSeitentext.
imageUrlstring | nullURL der Illustration dieser Seite.

Fehler-Body

Verwende error.code für die Logik; error.message dient nur der Anzeige.

Feldtabelle — error-Objekt· aufklappen
FeldTypBeschreibung
okbooleanImmer false.
requestIdstringGleiche Korrelations-ID wie bei Erfolgsantworten.
error.codestringMaschinenlesbarer Fehlercode (siehe Liste unten).
error.messagestringLesbare Meldung (Logik nicht vom genauen Wortlaut abhängig machen).
error.fieldsobject | undefinedOptionale Zuordnung Feldname → Validierungsmeldung (häufig bei VALIDATION_ERROR).
error.metaobject | undefinedOptionaler 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

TarifPro MinutePro Tag (Bücher)Monatskontingent
Pro60 Anfragen50 BücherGeteilt mit dem Guthaben deines Tarifs
Premium200 Anfragen200 BücherGeteilt 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.

ChildrenBooks Entwickler-API – KI-Bilderbücher per Code erstellen | ChildrenBooks