ColoringBookify

Inicio rápido

Exporta tu clave de API a una variable de entorno y verifícala contra el endpoint de la cuenta.

URL base

https://coloringbookify.com/api/v1

export COLORINGBOOKIFY_API_KEY="cbf_your_api_key"

curl --fail-with-body \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  https://coloringbookify.com/api/v1/me

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: page-$(uuidgen)" \
  --data '{"page":{"title":"A fox exploring a mushroom village"}}' \
  https://coloringbookify.com/api/v1/pages

MCP para agentes de IA

MCP

Usa MCP cuando un agente de IA deba planificar, generar, organizar y descargar un libro para colorear imprimible completo para la cuenta con sesión iniciada. Usa la API REST para integraciones directas de aplicaciones.

URL del servidor MCP

https://coloringbookify.com/mcp

Configúralo como un servidor HTTP Streamable. Los clientes compatibles descubren automáticamente los metadatos OAuth de ColoringBookify.

Conectar con Codex CLI

codex mcp add coloringbookify \
  --url https://coloringbookify.com/mcp
codex mcp login coloringbookify

El navegador abre ColoringBookify para el inicio de sesión y el consentimiento. MCP usa OAuth en lugar de claves de API y requiere un plan Business activo.

Los clientes usan tools/list para descubrir los nombres de herramientas actuales, esquemas de entrada y descripciones. El catálogo cubre cuentas, formatos de impresión, planes de libros, libros, personajes, páginas, operaciones, importaciones de arte externo, imágenes y PDF finales.

Las herramientas de solo lectura cuestan 0 créditos. Las herramientas de generación declaran su costo exacto y requieren que el agente confirme ese monto antes de gastar créditos. MCP usa el mismo saldo de cuenta que la API REST.

Las herramientas de imagen y PDF devuelven URL de descarga autorizadas de corta duración para que los agentes puedan recuperar archivos binarios sin transportar grandes cargas útiles en base64.

Ejemplo de solicitud para un agente

Crea un libro para colorear de 8.5 × 11 pulgadas sobre animales del océano. Muéstrame el plan propuesto y el costo exacto en créditos antes de generarlo, luego construye el libro y descarga el PDF final.

Autenticación

Crea una clave a nivel de cuenta desde la sección de API en tu cuenta, luego envíala en el encabezado Authorization como token Bearer. Las cookies de sesión del navegador no autentican solicitudes de API.

La clave completa se muestra solo después de su creación o rotación. Guárdala de forma segura y nunca la pongas en URL, código del lado del navegador, registros o control de versiones.

Créditos y encabezados de respuesta

Cada respuesta autenticada informa el saldo después de la solicitud y los créditos realmente consumidos por esa llamada HTTP. La tabla de endpoints y el campo x-credit-cost de OpenAPI declaran los costos antes de su uso.

X-ColoringBookify-Credits-Available: 247
X-ColoringBookify-Credits-Consumed: 1

Una reproducción idempotente informa cero consumido porque no cobra nuevamente, mientras que el cuerpo de la operación conserva su monto cobrado original.

De la idea al libro imprimible

Los planes permanecen en manos del cliente. Esto evita borradores obsoletos en el servidor mientras mantiene al usuario en control antes de cualquier generación que cambie créditos.

1. Crea un plan sin estado con POST /book_plans y muestra sus conceptos de página y la estimación exacta de créditos.
2. Deja que el usuario revise o edite el generation_request devuelto, luego envíalo a POST /books con una nueva clave de idempotencia.
3. Consulta la operación devuelta hasta que sea terminal. Importa o reemplaza arte externo reparado cuando sea necesario.
4. Llama a GET /print_formats, luego descarga el libro completo desde GET /books/{id}/pdf.

Generación, reintentos y operaciones

Envía un encabezado Idempotency-Key único con cada solicitud de generación. Reintentar el mismo método, ruta y carga útil con la misma clave devuelve la respuesta original sin generar ni cobrar nuevamente; reutilizarla para una solicitud diferente devuelve 409.

La generación devuelve 202 con un recurso y una operación. Consulta la URL de la operación hasta que su estado sea succeeded, partially_succeeded o failed. Las respuestas no terminales incluyen Retry-After.

Aspectos de página y tamaños de PDF

Llama a GET /api/v1/print_formats en lugar de codificar tamaños fijos. Los formatos PDF deben coincidir con el aspecto del libro; las imágenes importadas se normalizan sin recortar cuando solo se necesita un pequeño ajuste.

Aspecto del libro	Píxeles de imagen recomendados	Formatos PDF recomendados
square (1:1)	1024 × 1024	square, small_square
portrait (3:4)	1152 × 1536	us_letter, a4
landscape (4:3)	1536 × 1152	us_letter_landscape, a4_landscape

Endpoints

Lee, crea, actualiza, genera, organiza y elimina recursos propiedad de la cuenta autenticada.

Método	Ruta	Créditos	Descripción
GET	/api/v1/me	0	Obtén el plan de la cuenta, créditos y capacidades de API.
GET	/api/v1/print_formats	0	Lista los tamaños de PDF compatibles, aspectos compatibles y dimensiones de imagen recomendadas.
POST	/api/v1/book_plans	0	Crea un plan de libro editable sin estado, estimación exacta de créditos y carga útil de generación lista para enviar.
GET	/api/v1/operations	0	Lista las operaciones de generación asíncrona de la cuenta.
GET	/api/v1/operations/{id}	0	Consulta el estado actual, progreso y resultado de créditos de una operación.
GET	/api/v1/characters	0	Lista los personajes reutilizables activos propiedad de la cuenta.
POST	/api/v1/characters	1	Crea y genera asíncronamente un personaje reutilizable.
GET	/api/v1/characters/{id}	0	Obtén un personaje reutilizable activo propiedad de la cuenta.
PATCH	/api/v1/characters/{id}	0	Actualiza el nombre de un personaje o su configuración de vista previa pública.
PUT	/api/v1/characters/{id}	0	Actualiza el nombre de un personaje o su configuración de vista previa pública.
DELETE	/api/v1/characters/{id}	0	Archiva un personaje reutilizable propiedad de la cuenta.
GET	/api/v1/characters/{id}/reference_image	0	Descarga la imagen de referencia generada autorizada del personaje.
POST	/api/v1/characters/{id}/regenerate	1	Regenera asíncronamente un personaje reutilizable.
POST	/api/v1/characters/{id}/restore	0	Restaura un personaje reutilizable archivado.
GET	/api/v1/books	0	Lista los libros propiedad de la cuenta.
POST	/api/v1/books	1 por página de contenido generada	Crea un libro y genera asíncronamente sus páginas y portada.
GET	/api/v1/books/{id}	0	Obtén un libro propiedad de la cuenta con sus resúmenes de páginas ordenados.
PATCH	/api/v1/books/{id}	0	Actualiza metadatos del libro y personajes reutilizables.
PUT	/api/v1/books/{id}	0	Actualiza metadatos del libro y personajes reutilizables.
DELETE	/api/v1/books/{id}	0	Elimina un libro propiedad de la cuenta.
GET	/api/v1/books/{id}/pdf	0	Genera y descarga un PDF final estándar después de que cada página incluida esté lista.
POST	/api/v1/books/{book_id}/pages	0 adjuntar / 1 generar	Genera una nueva página o adjunta una página existente lista a un libro.
DELETE	/api/v1/books/{book_id}/pages/{id}	0	Desvincula una página de un libro sin eliminar la página.
PATCH	/api/v1/books/{id}/pages/order	0	Reemplaza la lista ordenada de páginas en un libro.
GET	/api/v1/pages	0	Lista las páginas propiedad de la cuenta.
POST	/api/v1/pages	1	Crea y genera asíncronamente una página independiente.
POST	/api/v1/pages/import	0	Importa arte externo terminado como página independiente lista.
GET	/api/v1/pages/{id}	0	Obtén una página propiedad de la cuenta.
PATCH	/api/v1/pages/{id}	0	Actualiza metadatos de página y personajes reutilizables.
PUT	/api/v1/pages/{id}	0	Actualiza metadatos de página y personajes reutilizables.
DELETE	/api/v1/pages/{id}	0	Elimina una página propiedad de la cuenta.
GET	/api/v1/pages/{id}/image	0	Descarga la imagen generada autorizada de la página.
PUT	/api/v1/pages/{id}/image	0	Reemplaza una imagen de página con arte externo terminado sin generación de IA.
POST	/api/v1/pages/{id}/regenerate	1	Regenera asíncronamente una página propiedad de la cuenta.

Paginación

Los endpoints de listado aceptan limit de 1 a 100, con valor predeterminado de 25, y un cursor after opaco devuelto como meta.next_cursor. Trata tanto los ID de recursos como los cursores como cadenas opacas.

curl --get https://coloringbookify.com/api/v1/pages \
  --header "Authorization: Bearer $COLORINGBOOKIFY_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=next_cursor_value"

Respuestas y errores

Los errores JSON usan un envoltorio estable con un código legible por máquina, un mensaje seguro y el ID de solicitud. Las respuestas incluyen el encabezado de versión de API y nunca se almacenan en caché públicamente.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "request-id"
  }
}

400

Parámetros de paginación o solicitud no válidos.

401

El token Bearer falta o no es válido.

402

La cuenta no tiene suficientes créditos para la generación.

403

La cuenta no tiene actualmente un plan Business activo.

404

El recurso no existe o no es propiedad de la cuenta.

409

La clave de idempotencia entra en conflicto con otra solicitud o la generación ya está activa.

422

La solicitud falló la validación o se alcanzó un límite de cuenta.

429

Se realizaron demasiadas solicitudes de planificación en un período corto.

503

La planificación de libros no está disponible temporalmente.

Seguridad y alcance actual

• Todas las respuestas de API usan Cache-Control private, no-store.
• Las descargas de imágenes vuelven a verificar la propiedad en cada solicitud.
• Las imágenes de origen y las URL de almacenamiento permanente nunca se exponen.
• Los detalles de excepciones del proveedor y las URL internas se omiten de los errores.

Los endpoints de generación requieren claves de idempotencia, registran transacciones de crédito de solo agregar y exponen solo errores de operación seguros.