AI Services

Printcart offers pay-per-token AI services that you can call directly from the REST API:

• Background Removal — remove the background from an image with AI.
• Preflight AI — check a print file's quality (DPI rating, bleed, colour, fonts) before production.
• Image Upscale & Auto-fix — increase image resolution and apply print fixes (bleed, sharpen, flatten) via AI fix jobs.

These endpoints live under the /v1/services/* prefix and are billed from your token wallet — there is no fixed fee, you only pay tokens when you use them.

Authentication & billing

All AI Services endpoints use account-level JWT auth (the same Bearer token as /account):

Authorization: Bearer <access_token>
Content-Type: application/json

If your wallet balance is too low, the API responds with HTTP 402:

{
  "error": "INSUFFICIENT_TOKENS",
  "balance": 50,
  "shortfall": 100,
  "top_up_url": "https://app.printcart.com/payment?tab=buy"
}

Top up tokens from Dashboard → Wallet & Billing → Buy tokens.

Background Removal

Removes the background from an image and returns a transparent (or white) PNG.

Create a job — POST /v1/services/bg-remove

Background removal runs asynchronously to avoid request timeouts. Submitting a job returns immediately with status: "processing"; you then poll the job until it is completed.

Request body

curl -X POST https://api.printcart.com/v1/services/bg-remove \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "subject_type": "product",
    "output_background": "transparent"
  }'

Response — `202 Accepted`

{
  "job_id": "JgSluQxRQ_mkvwpsGIOny",
  "status": "processing",
  "output_url": null,
  "tokens_deducted": 150,
  "wallet_transaction_id": "TX-00011",
  "provider": "self_hosted",
  "created_at": "2026-06-05T04:02:44.611Z"
}

Get a job — GET /v1/services/bg-remove/{jobId}

Poll this endpoint (e.g. every 2–3 seconds) until status is completed or failed. The output_url is a presigned link valid for 24 hours.

curl https://api.printcart.com/v1/services/bg-remove/JgSluQxRQ_mkvwpsGIOny \
  -H "Authorization: Bearer <access_token>"

Response — `200 OK`

{
  "job_id": "JgSluQxRQ_mkvwpsGIOny",
  "status": "completed",
  "subject_type": "product",
  "edge_softness": 3,
  "high_detail_mode": false,
  "output_background": "transparent",
  "output_url": "https://.../output.png?X-Amz-...",
  "tokens_deducted": 150,
  "wallet_transaction_id": "TX-00011",
  "created_at": "2026-06-05T04:02:44.611Z",
  "completed_at": "2026-06-05T04:04:00.532Z",
  "error_message": null
}

status values: pending → processing → completed | failed.

Preflight AI

Validates a print file and returns DPI quality plus any issues found.

Quick DPI score — POST /v1/services/preflight/dpi-score

A fast, file-free rating based on pixel dimensions and the selected canvas size. Fields are camelCase.

curl -X POST https://api.printcart.com/v1/services/preflight/dpi-score \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "widthPx": 4000,
    "heightPx": 3000,
    "canvasWidthInches": 30,
    "canvasHeightInches": 20,
    "productType": "photo_on_canvas"
  }'

Response — `200 OK`

{
  "data": {
    "stars": 4,
    "label": "Good",
    "effectivePpi": 133,
    "minPpi": 100,
    "productType": "photo_on_canvas"
  }
}

Full preflight check — POST /v1/services/preflight/checks

Runs a complete check on a file. Fields are camelCase.

curl -X POST https://api.printcart.com/v1/services/preflight/checks \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "designId": "design_12345",
    "fileUrl": "https://example.com/artwork.pdf",
    "fileType": "pdf",
    "productProfile": { "requiredDpi": 300, "requiredColorMode": "cmyk", "bleedMm": 3 }
  }'

Response — `201 Created` returns a report object containing the resolved status and a list of issues.

Other preflight endpoints

Image Upscale & AI Auto-fix

AI fixes run as jobs created from a preflight report. The most common use is upscaling a low-resolution raster image so it prints sharp.

1. Create a report for the image

curl -X POST https://api.printcart.com/v1/services/preflight/checks \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{ "designId": "upscale-001", "fileUrl": "https://example.com/photo.jpg", "fileType": "jpeg" }'
# → { "data": { "reportId": "report_..." , ... } }

2. Create an AI fix job — POST /v1/services/preflight/ai-jobs

curl -X POST https://api.printcart.com/v1/services/preflight/ai-jobs \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{
    "preflightReportId": "report_...",
    "options": { "fixTypes": ["upscale_resolution_2x"], "targetDpi": 300 }
  }'

An AI fix job is priced flat per job (not per fix): a raster job = 200 tokens, a PDF job (bleed) = 150 tokens. fixTypes (auto-derived from the report's issues if omitted):

Response — `202 Accepted`

{ "data": { "jobId": "job_...", "status": "analyzing", "estimatedTokenCost": { "min": 200, "max": 200 } } }

Tokens are deducted when the job is created (refunded automatically if the job fails).

3. Poll the job — GET /v1/services/preflight/ai-jobs/{jobId}

{
  "data": {
    "jobId": "job_...",
    "status": "completed",
    "correctedFileUrl": "https://.../output.png?X-Amz-...",
    "tokensDeducted": 30,
    "completedAt": "2026-06-10T10:01:30.000Z"
  }
}

status: analyzing → applying → completed | failed. correctedFileUrl is a presigned URL valid for 24 hours.

Using it from the dashboard

You can try every service without writing code in Dashboard → API Services:

• Background Removal — paste an image URL, choose options, and run.
• Preflight AI — enter dimensions (Quick DPI) or a file URL (Full check).
• Image Upscale — paste an image URL, choose 2× or 4×, and run.

Token usage and history are shown on the API Services overview and in Wallet & Billing → Transactions.