API do 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

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

Autenticação

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

Créditos e cabeçalhos de resposta

Cada resposta autenticada informa o saldo após a solicitação e os créditos realmente consumidos por essa chamada HTTP. A tabela de endpoints e o campo x-credit-cost do OpenAPI 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 a operação mantém o valor cobrado originalmente.

Da ideia ao livro imprimível

Os planos permanecem no cliente. Isso evita rascunhos obsoletos no servidor e mantém o usuário no controle antes de gastar créditos.

1. Crie um plano não persistente com POST /book_plans e mostre as cenas e a estimativa exata de créditos.
2. Permita que o usuário revise ou edite generation_request e envie-a para POST /books com uma nova chave de idempotência.
3. Consulte a operação até o estado final. Importe ou substitua arte corrigida externamente quando necessário.
4. Consulte GET /print_formats e baixe o livro completo em GET /books/{id}/pdf.

Geração, novas tentativas e operações

Envie um cabeçalho Idempotency-Key exclusivo em cada solicitação de geração. Repetir o mesmo método, caminho e conteúdo com a mesma chave retorna a resposta original sem gerar nem cobrar novamente; reutilizá-la em outra solicitação retorna 409.

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

Proporções de página e tamanhos PDF

Consulte GET /api/v1/print_formats em vez de fixar os tamanhos no código. O formato PDF deve corresponder à proporção do livro; imagens importadas são normalizadas sem corte quando apenas um pequeno ajuste é necessário.

Endpoints

Consulte, crie, atualize, gere, organize e exclua recursos da conta autenticada.

Paginação

Os endpoints de lista aceitam limit de 1 a 100, com padrão 25, e um cursor after opaco 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

Os erros JSON usam um envelope estável com código legível por máquina, mensagem segura e ID da solicitação. As respostas incluem a 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

Paginação ou parâmetros de solicitação inválidos.

401

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

402

A conta não possui 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 entra em conflito com outra solicitação ou uma 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 pouco tempo.

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.
• A propriedade é verificada novamente em cada download de imagem.
• Imagens de origem e URLs permanentes de armazenamento nunca são expostas.
• Detalhes de exceções do provedor e URLs internas são omitidos dos erros.

Os endpoints de geração exigem chaves de idempotência, registram transações de créditos imutáveis e exibem apenas erros seguros da operação.