API reference

Authentication, endpoints, request options, outputs, limits, and signed bulk webhooks.

Base URL: https://app.colorbliss.com. Read the quickstart for a first request or request API access.

Authentication and access

Use Authorization: Bearer YOUR_API_KEY on every submit and poll request. Submit JSON with Content-Type: application/json.

API access is available on Business after approval. Ultra is also eligible. Existing approved partners retain access. New legacy or custom plans require a partner arrangement with ColorBliss. An eligible plan is required to request approval and create new keys, except for approved partners.

Keys created in account settings include photo:submit and bulk:submit. Prompt endpoints accept either scope. Photo endpoints require photo:submit; bulk submission requires bulk:submit. Keys and jobs belong to the account that created the key. You cannot poll another account’s jobs or use its folders.

The Bearer secret is shown once. The key’s UUID is also shown for webhook verification. Save both securely. You can revoke a key in settings. Revocation stops future requests with that key.

Completed jobs use the key owner’s existing credits. There is no separate API allowance. Credit cost depends on the operation and quality.

Endpoints

These endpoints create individual pages and convert photo batches. The public API does not assemble a book interior or cover, convert drawings, generate character sheets, or accept a batch of text prompts.

Text prompts

POST /api/v1/prompt/submit

Prompt style tokens, with exact casing:

default, ghibli, simple, intricate, zentangle, mandala, person, realisticPerson, pencilSketch, cozy.

Submission returns HTTP 202 with job_id, status, prompt, style, quality, created_at, folder_id, and folder_name. improved_prompt appears when the prompt improver changed the prompt.

Poll GET /api/v1/prompt/jobs/{id} every 2 to 5 seconds. A completed response includes image_url. The response also includes the prompt, style, quality, timestamps, and error_message. Stop polling when the status is failed and inspect the error. Use an integration timeout of about 5 minutes.

Single photos

POST /api/v1/photo/submit

{
  "image": "https://your-site.example/pet.jpg",
  "style": "default",
  "quality": "standard"
}

Photo and bulk photo style tokens:

default, ghibli, cartoon, zentangle, zendoodle, detailed, minimalist, manga, cozy, pencil-sketch.

Prompt styles and photo styles use different tokens. For example, prompts use pencilSketch; photos use pencil-sketch.

Submission returns HTTP 202 with job_id, status, style, quality, created_at, folder_id, and folder_name.

Poll GET /api/v1/photo/jobs/{id} every 2 to 3 seconds. The response includes status, style, quality, caption, error_message, and timestamps. Download image_url when status is completed.

Single photo submission is limited to 500 jobs per hour per key owner. A 429 response includes Retry-After. Multiple keys for one account share this limit.

Aspect ratios and folders

Aspect ratio tokens for all submissions: square, portrait, landscape, widescreen, vertical.

Use either folder_name or folder_id, never both. folder_name creates a new folder each time you submit, even if a folder with that name already exists. To reuse one folder, save its folder_id from the submit response and send that ID on later requests. Leave both fields out to save pages without specifying a folder.

Image outputs and expiry

Individual prompt and photo jobs return a signed image URL valid for 24 hours. Download and store the result while the URL is valid. Polling a completed job again generates a fresh signed URL. Finished pages are also saved in the key owner’s ColorBliss library.

Image URLs appear only after a job completes. A 202 response means the job was accepted, not that the image is ready.

Bulk photo conversion

POST /api/v1/bulk/submit

{
  "images": [
    "https://your-site.example/photo-1.jpg",
    "https://your-site.example/photo-2.jpg"
  ],
  "style": "default",
  "folder_name": "Customer photos",
  "callback_url": "https://your-site.example/webhooks/colorbliss"
}

Each source photo must be a JPEG, PNG, or WebP of at most 10 MB. A batch must total at most 250 MB. URLs must be reachable without your browser session or private authentication headers. The API fetches all photos before submission. If any URL fails validation or download, the entire request returns 400. Allow about 60 seconds for this step.

Submission returns HTTP 202 with job_id, total_photos, status, created_at, folder_id, folder_name, and callback_signed.

Poll GET /api/v1/bulk/jobs/{id} for status, total_photos, completed_photos, failed_photos, pending_photos, style, quality, and timestamps. The results array contains each photo_job_id, status, original_filename, caption, and error_message.

The export is a ZIP of individual PDFs. It is emailed to the key owner’s account email. If you supplied callback_url, a webhook also delivers its download_url after the export is ready. Bulk polling does not return a download URL. Processing can show completed before the ZIP is ready. Use the webhook or email for export delivery.

Bulk webhooks

The callback includes the download URL, job details, and expires_at. Use expires_at to decide when the download expires. Do not assume image URL expiry applies to ZIP downloads.

ColorBliss signs callbacks with:

• Header: X-Colorbliss-Signature: sha256=<hex digest>
• Algorithm: HMAC-SHA256 over the exact raw request body
• Signing secret: the API key’s UUID, shown next to your key in settings. This is different from the cb_live_… Bearer secret.

Verify the signature with a constant-time comparison before parsing or accepting JSON. In Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyColorBlissWebhook(rawBody, signature, keyId) {
  if (!keyId || typeof signature !== "string" ||
      !/^sha256=[a-f0-9]{64}$/.test(signature)) return false;

  const expected = createHmac("sha256", keyId).update(rawBody).digest();
  const supplied = Buffer.from(signature.slice(7), "hex");
  return timingSafeEqual(expected, supplied);
}

// rawBody must be the original bytes, before any JSON middleware.
// After verification succeeds, parse rawBody and process the callback.

Use a public HTTPS receiver and respond promptly with a successful HTTP status. Handle duplicate callbacks without duplicating your own fulfillment. Treat the webhook as export delivery, not as a guarantee that every source photo succeeded; inspect job results for failures.

Errors and retries

Error responses include an error message and may include additional validation or queue details.

Queue validation can also return a credit or account error. Keep enough credits in the key owner’s balance for the requested work.

Submissions do not support an idempotency key. If a submission times out after ColorBliss receives it, sending it again can create a second job. Store accepted job IDs. Use bounded polling and backoff for temporary errors.

Start with a working request, explore the API, or open API settings.