API ColoringBookify

Démarrage rapide

Exportez votre clé API dans une variable d'environnement et vérifiez-la avec l'endpoint du compte.

URL de 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

Authentification

Créez une clé pour le compte depuis la section API, puis envoyez-la dans l'en-tête Authorization comme jeton Bearer. Les cookies de session du navigateur n'authentifient pas les requêtes API.

Crédits et en-têtes de réponse

Chaque réponse authentifiée indique le solde après la requête et les crédits réellement consommés par cet appel HTTP. Le tableau des endpoints et le champ OpenAPI x-credit-cost déclarent les coûts avant utilisation.

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

Une répétition idempotente indique zéro crédit consommé, car elle ne facture pas de nouveau, tandis que l'opération conserve le montant initialement facturé.

De l'idée au livre imprimable

Les plans restent côté client. Cela évite les brouillons serveur obsolètes et garde l'utilisateur aux commandes avant toute dépense de crédits.

1. Créez un plan non persistant avec POST /book_plans et affichez les scènes ainsi que l'estimation exacte des crédits.
2. Laissez l'utilisateur vérifier ou modifier generation_request, puis envoyez-la à POST /books avec une nouvelle clé d'idempotence.
3. Interrogez l'opération jusqu'à son état final. Importez ou remplacez une illustration corrigée à l'extérieur si nécessaire.
4. Appelez GET /print_formats, puis téléchargez le livre complet depuis GET /books/{id}/pdf.

Génération, nouvelles tentatives et opérations

Envoyez un en-tête Idempotency-Key unique avec chaque requête de génération. Réessayer la même méthode, le même chemin et le même contenu avec la même clé renvoie la réponse initiale sans nouvelle génération ni facturation ; la réutiliser pour une autre requête renvoie 409.

La génération renvoie 202 avec une ressource et une opération. Interrogez l'URL de l'opération jusqu'à l'état succeeded, partially_succeeded ou failed. Les réponses non terminales incluent Retry-After.

Proportions de page et formats PDF

Appelez GET /api/v1/print_formats au lieu de coder les tailles en dur. Le format PDF doit correspondre à la proportion du livre ; les images importées sont normalisées sans recadrage lorsqu'un léger ajustement suffit.

Endpoints

Consulter, créer, modifier, générer, organiser et supprimer les ressources du compte authentifié.

Pagination

Les endpoints de liste acceptent une limite de 1 à 100, 25 par défaut, et un curseur after opaque renvoyé dans meta.next_cursor. Traitez les identifiants de ressources et les curseurs comme des chaînes opaques.

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

Réponses et erreurs

Les erreurs JSON utilisent une enveloppe stable avec un code lisible par machine, un message sûr et l'identifiant de la requête. Les réponses incluent la version de l'API et ne sont jamais mises en cache publiquement.

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

400

Pagination ou paramètres de requête non valides.

401

Le jeton Bearer est absent ou non valide.

402

Le compte ne dispose pas d'assez de crédits pour la génération.

403

Le compte ne dispose pas actuellement d'un forfait Business actif.

404

La ressource n'existe pas ou n'appartient pas au compte.

409

La clé d'idempotence est en conflit avec une autre requête ou une génération est déjà active.

422

La requête échoue à la validation ou une limite du compte est atteinte.

429

Trop de requêtes de planification ont été effectuées en peu de temps.

503

La planification de livres est temporairement indisponible.

Sécurité et portée actuelle

• Toutes les réponses API utilisent Cache-Control private, no-store.
• La propriété est vérifiée à nouveau à chaque téléchargement d'image.
• Les images sources et les URL de stockage permanentes ne sont jamais exposées.
• Les détails d'exception du fournisseur et les URL internes sont omis des erreurs.

Les endpoints de génération exigent des clés d'idempotence, enregistrent des transactions de crédits immuables et n'exposent que des erreurs d'opération sûres.