Developer API · v1

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. 1. Pasa a Pro o Premium. Los planes gratuitos no pueden emitir claves de API. Ver precios.
  2. 2. Abre el panel y haz clic en Generate API key. Cópiala: no volverás a verla.
  3. 3. Envía tu primera solicitud. Sustituye cbk_live_XXX por 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_….

CabeceraObligatoriaDescripción
content-typeSíDebe ser application/json.
Idempotency-KeyNoClave ú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-IdNoSi se indica, se devuelve en las respuestas y los registros para trazabilidad. Longitud máxima 64; si no, el servidor genera uno.
Cuerpo JSON
CampoTipoRestriccionesDetalles y valores permitidos
storyIdeastringObligatorio. 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.
ageRangestring (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
stylestring (enum)Obligatorio. Un valor del enum. Distingue mayúsculas: usa 3d, no "3D".

Estilo artístico de las ilustraciones.

  • watercolor — Ilustración suave en acuarela.
  • oil_painting — Textura y pinceladas de óleo.
  • 3d — Aspecto 3D / CGI estilizado (envía la cadena 3d).
  • comic_style — Viñetas y entintado de cómic o novela gráfica.
  • crayon — Trazos de cera, aire de dibujo infantil.
  • colored_pencil — Textura y sombreado de lápices de colores.
  • paper_cut — Papel recortado / siluetas en capas.
pageCountintegerObligatorio. 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.
tonestring (enum)Obligatorio. Enum en snake_case: envía la cadena tal como está definida.

Tono o género narrativo.

  • playful_funny — Humor ligero y divertido.
  • fantasy_magic — Cuentos de hadas, magia, mundos imaginarios.
  • animal — Personajes animales y tramas de naturaleza.
  • heartwarming — Emociones suaves, empatía y amabilidad.
  • sci_fi — Espacio, robots, tecnología futura sencilla (apta para niños).
  • daily_life_basics — Rutinas diarias, familia, escuela, emociones.
  • adventurous — Exploración, misiones, suspense ligero.
  • educational — Enfoque didáctico suave (números, hábitos, habilidades sociales).
languagestring (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 — crear un cuento
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"
  }'

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.

POST /v1/stories — 202 Accepted (cuerpo)
json
{
  "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ámetroUbicaciónReglas
idpathEl 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 — consultar el estado
bash
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.

GET /v1/stories/{id} — 200 OK (cuerpo de ejemplo, p. ej. durante el proceso)
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"
      }
    ]
  }
}
Error — 400 / 401 / 429 / … (cuerpo)
json
{
  "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
CampoTipoDescripción
okbooleanSiempre true en esta respuesta.
requestIdstringId de correlación (eco de X-Request-Id o generado por el servidor).
data.taskIdstring (uuid)Id de la tarea de generación en segundo plano (correlación de cola).
data.bookIdstring (uuid)Id del cuento: úsalo como parámetro de ruta en GET /v1/stories/{id}.
data.statusstringEstado 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
CampoTipoDescripción
idstring (uuid)Id del libro (igual al id de la ruta).
titlestring | nullTítulo generado o editado.
slugstring | nullSlug de la URL del libro en el sitio web, si existe.
coverImagestring | nullURL de la portada.
summarystring | nullSinopsis breve.
storyIdeastring | nullLa idea de la historia guardada en el libro.
ageRangestring | nullEco del valor enviado (p. ej. 4-7).
stylestring | nullClave del estilo de ilustración.
pageCountinteger | nullNúmero de páginas objetivo (incluye la portada).
tonestring | nullClave de tono o género.
languagestring | nullClave del idioma de la historia.
sourcestring | nullDónde se creó el libro: web, api, hf (o null).
storageProviderstring | nullIdentificador del almacenamiento de los recursos, si aplica.
createdAtstring | nullFecha ISO 8601 de creación del registro del libro.
updatedAtstring | nullFecha ISO 8601 de la última actualización del libro.
statusstringEstado de la última tarea de generación: pending, processing, completed, failed, unknown. unknown si aún no hay tarea.
progressintegerPorcentaje aproximado 0–100 de la última tarea (por defecto 0).
errorMessagestring | nullMotivo legible del fallo cuando status es failed.
completedAtstring | nullFecha ISO 8601 de finalización de la generación, si existe.
pagesarrayLista ordenada de páginas (ver tabla siguiente). Crece a medida que se escriben ilustraciones y textos.

data.pages[] — cada elemento

CampoTipoDescripción
indexintegerÍndice de orden de la página (orden ascendente con las demás).
titlestring | nullTítulo o encabezado de la página.
contentstring | nullTexto de la página.
imageUrlstring | nullURL 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
CampoTipoDescripción
okbooleanSiempre false.
requestIdstringMismo id de correlación que en las respuestas correctas.
error.codestringCódigo de error legible por máquina (ver lista abajo).
error.messagestringMensaje legible (no dependas del texto exacto en tu lógica).
error.fieldsobject | undefinedMapa opcional de campo → mensaje de validación (habitual con VALIDATION_ERROR).
error.metaobject | undefinedContexto 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

PlanPor minutoPor día (libros)Cuota mensual
Pro60 solicitudes50 librosCompartida con los créditos de tu plan
Premium200 solicitudes200 librosCompartida 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.

API para desarrolladores de ChildrenBooks – Genera cuentos con IA desde tu código | ChildrenBooks