AutoClip Engine - getting started

The Engine takes a car photo and gives you back a finished photo with a clean background. You send one photo at a time. This page is the short version; the full technical reference (every field, every error) is at /docs.

What you get

You send a photo (and say which backdrop to use).
We look at it. Is it a whole-car shot that needs editing? A close-up that does not?
If it needs editing, we edit it and check the result.
You get back the finished photo - or your original photo if it did not need editing or the edit did not pass our checks.

What you are billed for

You are billed only for photos we edited and delivered to you.

Photo did not need editing (for example a close-up) - returned unedited, not billed.
The edit failed our quality check - we return your original, not billed.
We could not run our quality check on the edit - we return your original, not billed.
The photo failed for any other reason - not billed.
Sending the same photo twice with the same Idempotency-Key - billed once. A photo that already finished (even if we returned your original) is not redone; but if the earlier attempt failed - and a failed photo is never billed - sending the same request again with the same key simply starts a new photo.

Your usage (by key, by dealer reference, by month, exterior vs interior) is always available at GET /v1/usage.

1. Your key

We give you an API key that looks like ac_k7f3a9b2_.... It is shown once, so save it somewhere safe. Send it on every call:

Authorization: Bearer ac_k7f3a9b2_your_secret_here

If a key leaks, tell us - we can switch it off immediately and give you a new one.

2. Upload a backdrop (once)

curl -X POST https://api.autoclip.co/v1/backdrops \
  -H "Authorization: Bearer $KEY" \
  -F file=@my-lot.jpg -F name="Main lot"

The first backdrop you upload becomes your default. You can upload several and choose per photo. GET /v1/backdrops lists them; DELETE /v1/backdrops/{id} removes one.

3. Send a photo

Upload the file:

curl -X POST https://api.autoclip.co/v1/photos \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: car-1042-photo-3" \
  -F file=@car.jpg \
  -F dealer_ref="store-12" \
  -F external_id="car-1042-photo-3"

or give us a public https link instead of a file: -F image_url="https://example.com/car.jpg".

Field	Required	What it is
`file` or `image_url`	one of them	The photo. JPEG, PNG or WEBP, up to 15 MB. Links must be public `https` addresses.
`backdrop_id`	no	Which of your backdrops. Omit to use your default.
`dealer_ref`	no	Your label for the dealership. It appears in your usage so you can split the bill per dealer.
`external_id`	no	Your id for the photo. We send it back.
`callback_url`	no	An `https` address we call when the photo is finished (see below).
`Idempotency-Key` (header)	strongly recommended	Any unique text for this photo. If your request times out, send it again with the same key - you will get the same photo back and will not be billed twice. If that photo had failed, the same request with the same key starts a new photo instead (a failed photo was never billed). Reusing a key for a different request is refused (409).

You get back 202 Accepted with an id.

4. Get the result

curl https://api.autoclip.co/v1/photos/ph_... -H "Authorization: Bearer $KEY"

status goes queued then processing then done (or failed). When it is done:

outcome is edited or returned_original
outcome_reason tells you, in plain words, why (for example why the original was returned)
billable is true only when an edited photo was delivered
result_url is where to download the picture

Download it (your key is required - the link does not work in a browser tab without it):

curl https://api.autoclip.co/v1/photos/ph_.../result -H "Authorization: Bearer $KEY" -o finished.jpg

Most photos finish in under two minutes. Check every few seconds, or use a callback.

Callbacks (optional)

Give a callback_url and we will POST a small JSON message to it when the photo is finished. It is signed so you can be sure it came from us. The header looks like:

X-AutoClip-Signature: t=1767225600,v1=3b1f...

To verify: take the number after t=, join it with a dot and the raw request body ("<t>.<body>"), compute an HMAC-SHA256 with your webhook secret (shown once when your key was created), and compare it with v1. Reject messages older than a few minutes. If your server is down we retry a few times over about three hours; you can always fall back to GET /v1/photos/{id}.

Limits and errors

Every error looks like {"error": {"code": "...", "message": "..."}} - the message is written for people.
401 - the key is missing, wrong or switched off.
402 monthly_limit_reached - you have used your monthly photo allowance. Contact us to raise it.
402 daily_limit_reached - your account hit its daily limit on edits. Nothing is billed; try again tomorrow or contact us.
503 storage_unavailable - we are not accepting uploads for a short while. Nothing is billed; retry later with the same Idempotency-Key.
429 - too many requests per minute; wait and retry (see the Retry-After header).
503 - we are briefly unavailable; nothing was billed. Retry with the same Idempotency-Key.
Photos are kept for 7 days, then deleted - download your results before then.

Exterior and interior photos

Whole-car outside shots (front/back, three-quarter and side) are edited. Interior shots are sorted and reported separately in your usage; interior editing is not available yet, so they come back unedited and are not billed. Close-ups and detail shots are returned unedited.