Production REST API · v1

Photo Processing REST API

Active Professional and Business dealerships can create API keys from Dashboard → API access. The v1 contract accepts one private upload or a bounded batch of 1–10 HTTPS vehicle-photo sources, creates an asynchronous job per accepted image, and returns completed images through authenticated result routes.

Authentication and limits

Bearer credentials are dealership-scoped, expiring, revocable, displayed once, and intended for server-side use only.
Eligible dealerships may keep up to two active API keys. REST processing credentials do not grant MCP transport access.
Processing requires photo:processing:create; status and result access require separate read scopes.
The single-photo route accepts one JPG, PNG, or WebP source of no more than 4 MB and 24 megapixels.
The bulk route accepts 1–10 public HTTPS image sources, validates redirects and network destinations, and submits at most three items concurrently.
Each newly accepted job debits one existing CarPixAI processing credit.
An Idempotency-Key of 8–128 safe characters is required. Replaying the same bytes returns the same job without another debit; changed bytes return a conflict.

Endpoints

Method	Path	Purpose
GET	/api/v1/capabilities	Confirm the active key's intended REST scopes.
POST	/api/v1/photos/process	Upload one source photo and queue one credit-backed processing job.
POST	/api/v1/photos/process-batch	Queue 1–10 HTTPS sources with ordered per-item outcomes.
GET	/api/v1/photos/{imageId}	Read tenant-scoped status without storage URLs or provider details.
GET	/api/v1/photos/{imageId}/result	Download the authorized canonical presentation after completion.

Create a processing job

curl --request POST https://carpixai.com/api/v1/photos/process \
  --header "Authorization: Bearer $CARPIXAI_API_KEY" \
  --header "Idempotency-Key: dealer-stock-123-front-v1" \
  --header "Content-Type: image/jpeg" \
  --data-binary @vehicle.jpg

{
  "imageId": "api_img_...",
  "jobId": "...",
  "status": "QUEUED",
  "replayed": false,
  "creditsRemaining": 49,
  "statusUrl": "/api/v1/photos/api_img_...",
  "resultUrl": "/api/v1/photos/api_img_.../result"
}

Create a bounded bulk job

The batch receipt preserves input order and reports accepted or failed outcomes per item. Accepted images process independently; receipt order does not imply completion order.

curl --request POST https://carpixai.com/api/v1/photos/process-batch \
  --header "Authorization: Bearer $CARPIXAI_API_KEY" \
  --header "Idempotency-Key: dealer-stock-123-batch-v1" \
  --header "Content-Type: application/json" \
  --data '{
    "confirmCreditUse": true,
    "items": [
      {"itemId":"front", "sourceImageUrl":"https://cdn.example/stock-123-front.jpg"},
      {"itemId":"rear", "sourceImageUrl":"https://cdn.example/stock-123-rear.jpg"}
    ]
  }'

Deliberate v1 boundaries

Bulk URL ingestion is limited to 1–10 HTTPS images per request. There is no local-folder read, arbitrary prompt or model control, webhook, OAuth, customer SDK, CLI, direct DMS import, marketplace publishing, synchronous wait, or separate public API price sheet in v1. MCP remains a separate transport with separate credentials.

Production checklist

Keep the key in a server-side environment variable and never expose it in browser code.
Generate one stable idempotency identity for each source-photo operation.
Persist the returned image ID and poll the status route with bounded backoff.
Retrieve the result only after completion and preserve the original source.
Compare the result with the source vehicle before approval or downstream publishing.

Open API access API overview and plan fit Read-only MCP documentation