Genera cuentos con IA desde tu código.
Una API REST para suscriptores Pro y Premium. Lanza un trabajo de generación, consulta su estado y el libro terminado aparecerá automáticamente en tu biblioteca de ChildrenBooks junto a lo que creaste desde el panel.
Seguro por defecto
Las claves de API se muestran una sola vez y se guardan con hash SHA-256. Rotación y revocación inmediata desde el panel. Todas las solicitudes requieren TLS.
Con límites de uso y resistente al abuso
Los límites por minuto, por día y por mes protegen tu cuota frente a filtraciones. Las respuestas incluyen cabeceras x-ratelimit-* para que los SDK reduzcan el ritmo con elegancia.
Una biblioteca, una cuota
Los libros generados por la API aparecen en la misma biblioteca que los creados desde el panel. La cuota se comparte con tu plan Pro o Premium.
Guía rápida y referencia de la API
Obtén una clave Pro o Premium en el panel y ejecuta los ejemplos. Los cuerpos no válidos devuelven 400 / VALIDATION_ERROR; los enums deben coincidir exactamente (distinguen mayúsculas). Las respuestas usan ok, requestId opcional y data o error. Respeta x-ratelimit-* y retry-after ante un 429.
Requisitos previos
- 1. Pasa a Pro o Premium. Los planes gratuitos no pueden emitir claves de API. Ver precios.
- 2. Abre el panel y haz clic en
Generate API key. Cópiala: no volverás a verla. - 3. Envía tu primera solicitud. Sustituye
cbk_live_XXXpor tu clave:
Solicitud
POST /v1/stories
Crea un trabajo asíncrono que genera un cuento infantil ilustrado. El servidor encola el trabajo y responde de inmediato con 202 Accepted; el cuerpo devuelve taskId y bookId para que consultes el progreso con GET /v1/stories/{bookId}. Cada página (portada incluida) consume un crédito de la cuota de tu plan.
Cabeceras
Autenticación: x-api-key: cbk_live_… (recomendado) o Authorization: Bearer cbk_live_….
| Cabecera | Obligatoria | Descripción |
|---|---|---|
| content-type | Sí | Debe ser application/json. |
| Idempotency-Key | No | Clave única opcional por cada creación lógica (p. ej. un UUID). La misma clave en 24 h con el mismo cuerpo JSON devuelve el taskId / bookId original (no se crea un segundo libro). La misma clave con otro cuerpo devuelve 409 / IDEMPOTENCY_CONFLICT. Longitud máxima 128. Requiere Redis en la API; si Redis no está disponible, se omite la deduplicación. |
| X-Request-Id | No | Si se indica, se devuelve en las respuestas y los registros para trazabilidad. Longitud máxima 64; si no, el servidor genera uno. |
Cuerpo JSON
| Campo | Tipo | Restricciones | Detalles y valores permitidos |
|---|---|---|---|
| storyIdea | string | Obligatorio. Longitud de 10–8000 caracteres. | Descripción en lenguaje natural del libro (trama, personajes, escenario). No es una plantilla de prompt: escribe de qué quieres que trate la historia. |
| ageRange | string (enum) | Obligatorio. Debe coincidir exactamente con un valor permitido (distingue mayúsculas). | Franja de edad lectora (vocabulario y temas): 0-3, 4-7, 8-12 |
| style | string (enum) | Obligatorio. Un valor del enum. Distingue mayúsculas: usa 3d, no "3D". | Estilo artístico de las ilustraciones.
|
| pageCount | integer | Obligatorio. Entero de 6–15, ambos incluidos. 1 crédito por página. | Total de páginas incluida la portada. Cada página cuenta en los créditos mensuales de tu plan. |
| tone | string (enum) | Obligatorio. Enum en snake_case: envía la cadena tal como está definida. | Tono o género narrativo.
|
| language | string (enum) | Obligatorio. Solo claves en inglés y minúsculas (p. ej. english, no en). | Idioma del texto generado: english, spanish, french, german, chinese, japanese, korean, russian, portuguese, italian |
Llamada mínima con las cabeceras y campos JSON anteriores (sustituye la clave por la tuya). cURL y TypeScript son la misma solicitud: elige una pestaña. Guarda la clave en una variable de entorno del servidor; nunca la expongas en el código del navegador.
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"
}'Respuesta
Se devuelve con 202 Accepted cuando el trabajo queda en cola, con el mismo sobre ok / data que otras respuestas correctas. Carga de ejemplo; las tablas de campos desplegables (POST 202 y más) están en Respuesta.
{
"ok": true,
"requestId": "01HZXK3M6Q8EXAMPLE00RVW5T9A",
"data": {
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"bookId": "660e8400-e29b-41d4-a716-446655440001",
"status": "pending"
}
}GET /v1/stories/{id}
Obtiene los metadatos de un cuento, su estado de generación, el progreso y las páginas escritas hasta ahora. Usa el bookId de POST /v1/stories. Solo recibes libros del mismo usuario que la clave de API; los id inexistentes o de otros usuarios devuelven 404.
Parámetros de ruta
| Parámetro | Ubicación | Reglas |
|---|---|---|
| id | path | El bookId devuelto por POST. Debe ser un UUID. Solo ves libros del usuario de la clave de API. |
Consulta periódica
La generación es asíncrona: consulta con GET /v1/stories/{bookId} hasta que data.status sea completed o failed. El cuerpo JSON 200 completo aparece en Respuesta. El cURL y el TypeScript de abajo son la misma consulta: cambia de pestaña.
curl https://api.childrenbooks.online/v1/stories/<bookId> \
-H "x-api-key: cbk_live_XXXXXXXXXXXX"Respuesta
Ejemplos y referencia de campos para respuestas correctas y de error. El orden de los campos puede variar; null puede aparecer explícitamente u omitirse.
{
"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"
}
}
}Tablas de campos — cuerpo POST 202 (taskId, bookId, status)· desplegar
| Campo | Tipo | Descripción |
|---|---|---|
| ok | boolean | Siempre true en esta respuesta. |
| requestId | string | Id de correlación (eco de X-Request-Id o generado por el servidor). |
| data.taskId | string (uuid) | Id de la tarea de generación en segundo plano (correlación de cola). |
| data.bookId | string (uuid) | Id del cuento: úsalo como parámetro de ruta en GET /v1/stories/{id}. |
| data.status | string | Estado inicial del trabajo. Normalmente pending justo después de aceptarlo. Valores: pending, processing, completed, failed. |
Tablas de campos — objeto data de GET 200, elementos de pages[] y campos de página· desplegar
| Campo | Tipo | Descripción |
|---|---|---|
| id | string (uuid) | Id del libro (igual al id de la ruta). |
| title | string | null | Título generado o editado. |
| slug | string | null | Slug de la URL del libro en el sitio web, si existe. |
| coverImage | string | null | URL de la portada. |
| summary | string | null | Sinopsis breve. |
| storyIdea | string | null | La idea de la historia guardada en el libro. |
| ageRange | string | null | Eco del valor enviado (p. ej. 4-7). |
| style | string | null | Clave del estilo de ilustración. |
| pageCount | integer | null | Número de páginas objetivo (incluye la portada). |
| tone | string | null | Clave de tono o género. |
| language | string | null | Clave del idioma de la historia. |
| source | string | null | Dónde se creó el libro: web, api, hf (o null). |
| storageProvider | string | null | Identificador del almacenamiento de los recursos, si aplica. |
| createdAt | string | null | Fecha ISO 8601 de creación del registro del libro. |
| updatedAt | string | null | Fecha ISO 8601 de la última actualización del libro. |
| status | string | Estado de la última tarea de generación: pending, processing, completed, failed, unknown. unknown si aún no hay tarea. |
| progress | integer | Porcentaje aproximado 0–100 de la última tarea (por defecto 0). |
| errorMessage | string | null | Motivo legible del fallo cuando status es failed. |
| completedAt | string | null | Fecha ISO 8601 de finalización de la generación, si existe. |
| pages | array | Lista ordenada de páginas (ver tabla siguiente). Crece a medida que se escriben ilustraciones y textos. |
data.pages[] — cada elemento
| Campo | Tipo | Descripción |
|---|---|---|
| index | integer | Índice de orden de la página (orden ascendente con las demás). |
| title | string | null | Título o encabezado de la página. |
| content | string | null | Texto de la página. |
| imageUrl | string | null | URL de la ilustración de esta página. |
Cuerpo de error
Usa error.code para la lógica; error.message es solo para mostrar.
Tabla de campos — objeto error· desplegar
| Campo | Tipo | Descripción |
|---|---|---|
| ok | boolean | Siempre false. |
| requestId | string | Mismo id de correlación que en las respuestas correctas. |
| error.code | string | Código de error legible por máquina (ver lista abajo). |
| error.message | string | Mensaje legible (no dependas del texto exacto en tu lógica). |
| error.fields | object | undefined | Mapa opcional de campo → mensaje de validación (habitual con VALIDATION_ERROR). |
| error.meta | object | undefined | Contexto adicional opcional del servidor (la estructura puede variar). |
Valores 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
Límites
| Plan | Por minuto | Por día (libros) | Cuota mensual |
|---|---|---|---|
| Pro | 60 solicitudes | 50 libros | Compartida con los créditos de tu plan |
| Premium | 200 solicitudes | 200 libros | Compartida con los créditos de tu plan |
Al alcanzar un límite, la API devuelve 429 con retry-after en segundos. Cada respuesta incluye además x-ratelimit-remaining para que tu cliente frene a tiempo.
Política de uso
- • Las claves de API pertenecen a un solo usuario. No las compartas entre cuentas.
- • No generes contenido que infrinja nuestros Términos del servicio, incluido contenido sexual con menores, violencia real o personajes protegidos por derechos de autor.
- • Guarda los secretos en variables de entorno del servidor. Nunca incluyas una clave de API en el código del navegador.
- • Podemos rotar o revocar una clave ante patrones abusivos (picos de tráfico, saltos de IP entre continentes en minutos) y te avisaremos por correo.
- • Pasar al plan gratuito revoca la clave al instante.
¿Listo para empezar?
Inicia sesión, activa tu clave de API en el panel y publica tu primera integración de cuentos en menos de 10 minutos.