Background Removal pre-flight endpoint

This article shows you how to call POST /api/v1/photos/process to remove a photo's background once, before any render, so every downstream render and design group reuses the result instead of repeating the work.

Why pre-flight a photo?

When a Zap or API workflow sends the same photo into several templates — a name plaque, a trophy card, and a team roster sheet all at once — each render would independently run Background Removal on that photo. Pre-flighting calls Background Removal a single time and caches the result. Every subsequent render that references the same photo skips the processing step entirely: faster renders, and you are charged the Background Removal surcharge only once, not once per render.

Authentication and access

The endpoint requires an API key sent as a Bearer token. Background Removal must be enabled for your organization. If it is not enabled, the endpoint returns 403. Contact your account owner or see Managing your organization.

Authorization: Bearer YOUR_API_KEY

Submit a photo-process job

Send a POST to /api/v1/photos/process with a JSON body:

POST /api/v1/photos/process
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "image_url": "https://example.com/photos/player-42.jpg",
  "remove_background": true,
  "correction": false,
  "webhook_url": "https://yourserver.com/callbacks/photo-process"
}

Request fields

Field	Type	Required	Description
`image_url`	string	Yes	HTTPS URL of the source photo. Must be publicly accessible at the time of processing.
`remove_background`	boolean	No	Default `true`. Removes the photo's background and outputs a transparent image. Set to `false` to skip background removal and run only face detection.
`correction`	boolean	No	Default `false`. When `true`, applies automatic color and exposure correction to the photo.
`webhook_url`	string	No	HTTPS URL to receive a `POST` when processing completes. Recommended for production workflows. If omitted, poll the `poll_url` returned in the 202 response.

202 response — job accepted

{
  "job_id": "clx_photo123",
  "status": "queued",
  "poll_url": "/api/v1/photos/process/clx_photo123"
}

The job is processed asynchronously. Background Removal typically completes in 10–17 seconds for a standard camera JPEG.

Wait for completion

You have two options: receive a webhook callback, or poll the status endpoint.

Option A — webhook (recommended)

When processing finishes, Templified sends a POST to your webhook_url with the same body shape as the poll response below. Verify the request comes from Templified by checking it against your API key's expected origin or by using a signed secret if your framework supports it.

Option B — poll

GET /api/v1/photos/process/{job_id}
Authorization: Bearer YOUR_API_KEY

Poll every few seconds until status is complete or failed. There is no long-polling support; use a short interval (3–5 seconds) rather than a tight loop.

Completed response

{
  "job_id": "clx_photo123",
  "status": "complete",
  "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "extracted_url": "https://cdn.templified.io/uploads/org123/extracted.png",
  "face_bbox": "1086, 1074, 1385, 1473",
  "content_bbox": "0, 50, 1200, 1800",
  "has_glasses": false,
  "num_faces": 1,
  "completed_at": "2026-04-29T01:00:00.000Z"
}

Response fields

Field	Description
`status`	`queued`, `processing`, `complete`, or `failed`.
`content_hash`	A hash of the source image bytes. This is how downstream renders identify a cached result — if you pass the same photo URL, Templified matches on content hash.
`extracted_url`	URL of the processed (background-removed) image. Pass this as the photo URL in your subsequent render calls.
`face_bbox`	Comma-separated pixel coordinates of the detected face region (`left, top, right, bottom`). Used automatically by renders that have face placement enabled on a photo layer.
`content_bbox`	Comma-separated pixel coordinates of the full subject/content region. Used together with `face_bbox` by face placement to scale and position the subject correctly.
`has_glasses`	Whether glasses were detected on the subject.
`num_faces`	Number of faces detected in the photo.

Use the result in downstream renders

Pass the extracted_url from the completed job as the photo URL in a subsequent render or design-group call. Templified looks up the cached result by content hash, skips the Background Removal step, and charges no surcharge for that render.

POST /api/v1/create
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "template_id": "clx_tmpl456",
  "fields": {
    "Photo": "https://cdn.templified.io/uploads/org123/extracted.png"
  }
}

The same cached result is reused for every template in a design group. A photo pre-flighted once flows through all templates in the group without any additional Background Removal processing or charges.

Error responses

Status	Meaning
`400`	A required field is missing or a field value is invalid. The response body names the problem field.
`402`	Your trial allowance is exhausted or the account is suspended. Add a card and fund your balance to continue. Insufficient balance on a funded account surfaces as a `failed` job (not a 402) because the charge is evaluated after the cache check.
`403`	Background Removal is not enabled for your organization.
`429`	Your organization has exceeded the hourly photo-processing rate limit. Retry after a short pause.

Zapier — "Background Removal" action

If you use Zapier, the Background Removal action in the Templified app wraps this endpoint. It submits the job, waits up to ~25 seconds for a fast result, and — if processing takes longer — resumes automatically when the result arrives. The action's output fields (Extracted Image URL, Face BBox, Content BBox) map directly to the inputs of a following Create Image or Create Editable Design step.

Recommended Zap structure for batch workflows:

Trigger — one record per photo (folder watcher, spreadsheet row, order webhook, etc.).
Background Removal — submit and wait for the processed photo.
Create Image (or Create Editable Design) — use the Extracted Image URL from step 2 as the photo field. Add as many Create Image steps as you need templates; each one reuses the same cached result at no extra Background Removal charge.

Billing summary

Background Removal is charged once per unique source photo, at the point the vendor pipeline is actually invoked. Cache hits — any render that finds an already-processed result — are free. The 10¢ Background Removal surcharge does not stack when one processed photo is used across multiple templates or design groups.