The AutoBackgrounding API v1 lets you replace car photo backgrounds programmatically. All endpoints are served from a single base URL and run on our purpose-built automotive pipeline.

https://app.autobackgrounding.com

All input image and background URLs must live on our storage (from /api/v1/presigned-urls or /api/v1/generate-background) — external URLs are rejected.

Every request needs an API key, sent either way. Create keys from the API dashboard.

Authorization: Bearer <API_KEY>
# or
x-api-key: <API_KEY>

Missing, invalid, or revoked key → 401

{ "error": "Invalid or missing API key" }

• 1K / 2K output = 1 credit per image, 4K = 2 credits
• Credits are charged upfront when a job is accepted — bulk jobs refund automatically if the request fails before processing starts
• Not enough credits → 402
• Check your balance any time with GET /api/v1/credit-usage

{ "error": "Not enough credits", "required": 2, "remaining": 1 }

Get signed upload URLs for your input images. Free — no credits.

{
  "bucket": "api-images",
  "uploads": [
    {
      "path": "uploads/<keyId>/<uuid>",
      "token": "...",
      "presignedUrl": "https://....supabase.co/storage/...",
      "publicUrl": "https://....supabase.co/storage/..."
    }
  ]
}

Then upload each file with PUT <presignedUrl> and the raw image bytes as the body (Content-Type: image/jpeg or image/png). Use the matching publicUrl in the endpoints below.

Create one background scene (no car). Synchronous — the image is generated during the request (~10–60s). Costs credits by quality.

{
  "id": "uuid",
  "status": "completed",
  "backgroundUrl": "https://....jpeg",
  "creditsCharged": 1,
  "savedBackgroundId": "uuid-or-null"
}

savedBackgroundId only appears when save: true. Generation failure → 502 (credits refunded automatically).

Submit up to 20 car photos for background replacement. Asynchronous — returns a batchId immediately; poll for results below.

{
  "prompt": "luxury garage interior with ambient lighting",
  "shotType": "exterior",
  "quality": "1K",
  "aspectRatio": "16:9",
  "images": [
    { "url": "https://..." },
    { "url": "https://...", "quality": "2K", "aspectRatio": "1:1" },
    { "url": "https://...", "backgroundId": "uuid" },
    { "url": "https://...", "backgroundUrl": null }
  ]
}

{ "batchId": "uuid", "totalImages": 4, "creditsCharged": 5, "status": "processing" }

shotType controls how each photo is treated: exterior (default) places the car into the new scene, interior keeps the cabin unchanged and replaces only the view through the windows, specific-part is for close-up shots of a specific part of the car (grille, headlight, wheel) — the crop is kept as framed and only the background behind the part is replaced. Applies to the whole batch.

Background resolution order (job level): backgroundUrl → backgroundId → the key's default saved background → none (prompt-only). Default prompts: with a background, "According to the background image"; without, "clean white studio background, soft even lighting".

{
  "batch": {
    "id": "uuid",
    "status": "pending | processing | completed",
    "total_count": 4,
    "completed_count": 3,
    "error_count": 1,
    "progress": 100,
    "credits_charged": 5,
    "created_at": "...",
    "finished_at": "..."
  },
  "images": [
    {
      "id": "uuid",
      "original_url": "https://...",
      "processed_url": "https://...-or-null",
      "status": "pending | processing | completed | error",
      "credit_cost": 1,
      "error_message": null,
      "processed_at": "..."
    }
  ]
}

images[].processed_url is the final result per image. Poll every few seconds until batch.status is completed.

List this key's batches, newest first. Returns { batches: [...], total, limit, offset }.

Save a background once, reuse it across bulk jobs by backgroundId — no re-upload per job. Max 50 saved backgrounds per key. At most one can be the default: it is used automatically by bulk jobs that specify no background.

{ "url": "https://... (our storage)", "name": "My showroom", "isDefault": false }

PATCH accepts { "name": "..." } and/or { "isDefault": true } — setting a new default automatically clears the previous one. DELETE removes the saved reference only — past results and in-flight jobs keep working.