API quickstart

Submit your first coloring page, check its status, and download the result.

The ColorBliss API generates coloring pages from text prompts and photos. It also converts up to 50 photo URLs in a batch. All requests use the base URL https://app.colorbliss.com.

1. Request access and create a key

API access is available on Business after approval. Sign in to request access. Customers on a lower plan will see an upgrade prompt with Business selected. Once approved, create a key in account settings.

Copy the cb_live_… secret when you create it. It is shown only once. Store it in a server environment variable. Never put it in browser code or a public repository.

Completed jobs use credits from the account that owns the key. They share your existing balance with work created in the app.

2. Submit a text prompt

Set COLORBLISS_API_KEY to your key in your server environment, then run:

curl --fail-with-body https://app.colorbliss.com/api/v1/prompt/submit \
  -H "Authorization: Bearer $COLORBLISS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A cozy cabin beside a lake","style":"cozy"}'

A successful submission returns HTTP 202 with a job_id and status: "pending". Save the ID. Generation happens in the background.

The default quality is standard. The default aspect ratio is square. Prompt improvement is enabled by default. See all prompt options.

3. Poll for your page

Replace JOB_ID with the ID returned by submission:

curl --fail-with-body "https://app.colorbliss.com/api/v1/prompt/jobs/JOB_ID" \
  -H "Authorization: Bearer $COLORBLISS_API_KEY"

Poll every 2 to 5 seconds. When status is completed, download the image_url. If status is failed, check error_message and stop polling. Use a timeout of about 5 minutes in your integration so a delayed job does not keep it waiting indefinitely.

Signed image URLs last 24 hours. Download the image while the URL is valid. You can poll a completed job again for a fresh URL. The page is also saved in the key owner’s ColorBliss library.

Convert a single photo

Use a publicly reachable JPEG, PNG, or WebP URL, up to 10 MB:

curl --fail-with-body https://app.colorbliss.com/api/v1/photo/submit \
  -H "Authorization: Bearer $COLORBLISS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-site.example/pet.jpg","style":"default"}'

Poll GET /api/v1/photo/jobs/JOB_ID every 2 to 3 seconds with the same Bearer header. Download image_url when the job completes. Omit aspect_ratio to detect it from the photo.

The example photo URL is a placeholder. Replace it with a real image URL your server can share with ColorBliss.

Convert a batch of photos

curl --fail-with-body https://app.colorbliss.com/api/v1/bulk/submit \
  -H "Authorization: Bearer $COLORBLISS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://your-site.example/photo-1.jpg",
      "https://your-site.example/photo-2.jpg"
    ],
    "folder_name": "Photo gifts",
    "style": "default",
    "callback_url": "https://your-site.example/webhooks/colorbliss"
  }'

Replace the placeholder photo and callback URLs. Omit callback_url if you only want email delivery. The API fetches all source images before accepting the batch, so allow about 60 seconds for submission. Any invalid photo URL rejects the entire batch.

Poll GET /api/v1/bulk/jobs/JOB_ID to check progress. The API emails a ZIP of individual PDFs to the key owner’s account email. An optional signed webhook also delivers the download URL after export is ready. A completed processing status can appear before the ZIP is ready, and the poll response does not contain a ZIP download URL.

Read the webhook verification example before accepting a callback.

Prepare your integration for errors

• 400: Fix the request fields or source URLs before retrying.
• 401: Check the Bearer key and whether it was revoked.
• 403: Check the scopes assigned to your key.
• 404: Check the job or folder ID and its owner.
• 429: Wait for the Retry-After interval before trying again.
• 5xx: Check status before submitting another job if the original request might have reached ColorBliss.

Submissions do not accept an idempotency key. Retrying a request after an ambiguous network failure can create another job and spend credits again. Save accepted job IDs and poll them instead of resubmitting.

Read the full API reference for styles, quality, folders, limits, outputs, and webhook signatures. Return to the API overview.