ColoringBookify

Início rápido

Exporte sua chave de API para uma variável de ambiente e verifique-a no endpoint da conta.

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

Use MCP quando um agente de IA deve planejar, gerar, organizar e baixar um livro de colorir completo e imprimível para a conta conectada. Use a API REST para integrações diretas de aplicativos.

URL do servidor MCP

https://coloringbookify.com/mcp

Configure isso como um servidor HTTP Streamable. Clientes compatíveis descobrem os metadados OAuth do ColoringBookify automaticamente.

Conectar com Codex CLI

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

O navegador abre o ColoringBookify para login e consentimento. O MCP usa OAuth em vez de chaves de API e requer um plano Business ativo.

Os clientes usam tools/list para descobrir os nomes atuais das ferramentas, esquemas de entrada e descrições. O catálogo abrange contas, formatos de impressão, planos de livros, livros, personagens, páginas, operações, importações de arte externa, imagens e PDFs finais.

Ferramentas somente leitura custam 0 créditos. Ferramentas de geração declaram seu custo exato e exigem que o agente confirme esse valor antes de gastar créditos. O MCP usa o mesmo saldo de conta que a API REST.

Ferramentas de imagem e PDF retornam URLs de download autorizadas e de curta duração, permitindo que agentes recuperem arquivos binários sem transportar grandes payloads em base64.

Exemplo de solicitação para um agente

Crie um livro de colorir de 8,5 × 11 polegadas sobre animais do oceano. Mostre-me o plano proposto e o custo exato em créditos antes de gerar, depois construa o livro e baixe o PDF final.

Autenticação

Crie uma chave de nível de conta na seção de API da sua conta e envie-a no cabeçalho Authorization como um token Bearer. Cookies de sessão do navegador não autenticam solicitações de API.

A chave completa é exibida apenas após a criação ou rotação. Armazene-a com segurança e nunca a coloque em URLs, código no lado do navegador, logs ou controle de versão.

Créditos e cabeçalhos de resposta

Toda resposta autenticada informa o saldo após a solicitação e os créditos efetivamente consumidos por essa chamada HTTP. A tabela de endpoints e o campo OpenAPI x-credit-cost declaram os custos antes do uso.

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

Uma repetição idempotente informa zero consumido porque não cobra novamente, enquanto o corpo da operação mantém o valor original cobrado.

Da ideia ao livro imprimível

Os planos permanecem mantidos pelo cliente. Isso evita rascunhos desatualizados no servidor, mantendo o usuário no controle antes de qualquer geração que altere créditos.

1. Crie um plano sem estado com POST /book_plans e exiba seus conceitos de página e a estimativa exata de créditos.
2. Deixe o usuário revisar ou editar o generation_request retornado e envie-o para POST /books com uma nova chave de idempotência.
3. Consulte a operação retornada até o estado terminal. Importe ou substitua arte externa reparada quando necessário.
4. Chame GET /print_formats e baixe o livro completo de GET /books/{id}/pdf.

Geração, tentativas e operações

Envie um cabeçalho Idempotency-Key exclusivo com cada solicitação de geração. Repetir o mesmo método, caminho e payload com a mesma chave retorna a resposta original sem gerar ou cobrar novamente; reutilizá-la para uma solicitação diferente retorna 409.

A geração retorna 202 com um recurso e uma operação. Consulte a URL da operação até que seu status seja succeeded, partially_succeeded ou failed. Respostas não terminais incluem Retry-After.

Proporções de página e tamanhos de PDF

Chame GET /api/v1/print_formats em vez de codificar tamanhos fixos. Os formatos de PDF devem corresponder à proporção do livro; imagens importadas são normalizadas sem corte quando apenas um pequeno ajuste é necessário.

Proporção do livro	Pixels recomendados da imagem	Formatos de 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

Leia, crie, atualize, gere, organize e remova recursos pertencentes à conta autenticada.

Método	Caminho	Créditos	Descrição
GET	/api/v1/me	0	Obtenha o plano da conta, créditos e capacidades da API.
GET	/api/v1/print_formats	0	Liste tamanhos de PDF suportados, proporções compatíveis e dimensões recomendadas de imagem.
POST	/api/v1/book_plans	0	Crie um plano de livro editável sem estado, estimativa exata de créditos e payload de geração pronto para envio.
GET	/api/v1/operations	0	Liste operações de geração assíncrona da conta.
GET	/api/v1/operations/{id}	0	Consulte o status atual, progresso e resultado de créditos de uma operação.
GET	/api/v1/characters	0	Liste personagens reutilizáveis ativos pertencentes à conta.
POST	/api/v1/characters	1	Crie e gere assincronamente um personagem reutilizável.
GET	/api/v1/characters/{id}	0	Obtenha um personagem reutilizável ativo pertencente à conta.
PATCH	/api/v1/characters/{id}	0	Atualize o nome de um personagem ou a configuração de pré-visualização pública.
PUT	/api/v1/characters/{id}	0	Atualize o nome de um personagem ou a configuração de pré-visualização pública.
DELETE	/api/v1/characters/{id}	0	Arquive um personagem reutilizável pertencente à conta.
GET	/api/v1/characters/{id}/reference_image	0	Baixe a imagem de referência gerada e autorizada do personagem.
POST	/api/v1/characters/{id}/regenerate	1	Regere assincronamente um personagem reutilizável.
POST	/api/v1/characters/{id}/restore	0	Restaure um personagem reutilizável arquivado.
GET	/api/v1/books	0	Liste livros pertencentes à conta.
POST	/api/v1/books	1 por página de conteúdo gerada	Crie um livro e gere assincronamente suas páginas e capa.
GET	/api/v1/books/{id}	0	Obtenha um livro pertencente à conta com seus resumos de páginas ordenados.
PATCH	/api/v1/books/{id}	0	Atualize metadados do livro e personagens reutilizáveis.
PUT	/api/v1/books/{id}	0	Atualize metadados do livro e personagens reutilizáveis.
DELETE	/api/v1/books/{id}	0	Exclua um livro pertencente à conta.
GET	/api/v1/books/{id}/pdf	0	Gere e baixe um PDF final padrão após cada página incluída estar pronta.
POST	/api/v1/books/{book_id}/pages	0 anexar / 1 gerar	Gere uma nova página ou anexe uma página pronta existente a um livro.
DELETE	/api/v1/books/{book_id}/pages/{id}	0	Desanexe uma página de um livro sem excluir a página.
PATCH	/api/v1/books/{id}/pages/order	0	Substitua a lista ordenada de páginas em um livro.
GET	/api/v1/pages	0	Liste páginas pertencentes à conta.
POST	/api/v1/pages	1	Crie e gere assincronamente uma página independente.
POST	/api/v1/pages/import	0	Importe arte externa finalizada como uma página independente pronta.
GET	/api/v1/pages/{id}	0	Obtenha uma página pertencente à conta.
PATCH	/api/v1/pages/{id}	0	Atualize metadados da página e personagens reutilizáveis.
PUT	/api/v1/pages/{id}	0	Atualize metadados da página e personagens reutilizáveis.
DELETE	/api/v1/pages/{id}	0	Exclua uma página pertencente à conta.
GET	/api/v1/pages/{id}/image	0	Baixe a imagem gerada e autorizada da página.
PUT	/api/v1/pages/{id}/image	0	Substitua a imagem de uma página por arte externa finalizada sem geração de IA.
POST	/api/v1/pages/{id}/regenerate	1	Regere assincronamente uma página pertencente à conta.

Paginação

Endpoints de listagem aceitam limit de 1 a 100, com padrão de 25, e um cursor opaco after retornado como meta.next_cursor. Trate IDs de recursos e cursores como strings 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"

Respostas e erros

Erros JSON usam um envelope estável com um código legível por máquina, uma mensagem segura e o ID da solicitação. As respostas incluem o cabeçalho de versão da API e nunca são armazenadas em cache publicamente.

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

400

Parâmetros de paginação ou solicitação inválidos.

401

O token Bearer está ausente ou é inválido.

402

A conta não tem créditos suficientes para a geração.

403

A conta não possui atualmente um plano Business ativo.

404

O recurso não existe ou não pertence à conta.

409

A chave de idempotência conflita com outra solicitação ou a geração já está ativa.

422

A solicitação falhou na validação ou um limite da conta foi atingido.

429

Muitas solicitações de planejamento foram feitas em um curto período.

503

O planejamento de livros está temporariamente indisponível.

Segurança e escopo atual

• Todas as respostas da API usam Cache-Control private, no-store.
• Downloads de imagens revalidam a propriedade em cada solicitação.
• Imagens de origem e URLs de armazenamento permanente nunca são expostas.
• Detalhes de exceções do provedor e URLs internas são omitidos dos erros.

Endpoints de geração exigem chaves de idempotência, registram transações de crédito somente anexação e expõem apenas erros de operação seguros.