Skip to main content
POST
Image Customizer

Authorizations

Authorization
string
header
required

Organisation API key, sent as Authorization: Bearer chk_live_….

  • chk_live_… — production inference, live credits, livemode: true, is_staging: false.
  • chk_stg_… — real inference classified as staging, the same live credits, livemode: true, is_staging: true.
  • chk_test_… — identical pipeline against the fixture backend, test credits, livemode: false.

Keys are stored hashed; only the prefix (chk_live_a1b2…) is ever displayed again. A key may be scoped to a subset of endpoint families — calling outside its scopes is a 403.

Headers

Idempotency-Key
string

Client-generated key (a UUID is ideal) making this POST safe to retry. The first request is executed and its response stored for 24 h; any replay with the same key returns that stored response with Idempotent-Replayed: true and bills nothing. Reusing a key with a different payload is a 409 idempotency_key_reuse.

Required string length: 8 - 255
X-Carhub-Test-Scenario
string

Steers the fixture backend. Ignored by live keys, 400 test_scenario_not_supported if the scenario is unknown to the endpoint. Common catalogue:

Some endpoints add their own scenarios; unsupported common scenarios (for example empty_result on a generation endpoint) are rejected rather than silently ignored.

Examples:

"empty_result"

"low_confidence"

"model_error"

"slow"

"insufficient_credits"

Body

image
file
required

One JPEG, PNG, or WebP image up to 20 MiB.

prompt
string
required

Describe the final photograph you want. Only explicitly requested modifications should affect the vehicle.

Required string length: 1 - 4000
Pattern: \S
Examples:

"Wash the car. Keep its current paint color, wheels, equipment, and background."

"Change the paint color to metallic blue while preserving the wheels, trim, and vehicle condition."

"Place the car in a modern outdoor dealership courtyard with coherent daylight and reflections."

Response

Existing job returned by an idempotent replay.

The unit of work of the API. Every inference call creates one, and every result is read back from one — synchronously through wait=true, or later through GET /v1/jobs/{id} or a webhook.

result is populated only in succeeded, error only in failed / expired.

is_staging
boolean
default:false
required

Staging classification. Requires live mode and uses the organisation's shared live credits.

id
string
required

Job identifier — job_ followed by a base58 string.

Pattern: ^job_[1-9A-HJ-NP-Za-km-z]{8,32}$
Example:

"job_3ZxK9pQr7TnW"

object
string
required
Allowed value: "job"
endpoint
enum<string>
required

Dotted slug of a CarHub endpoint, the identifier used for jobs and usage.

Available options:
vehicle.pose,
vehicle.segment,
vehicle.identify,
vin.read,
driver_license.read,
plate.read,
document.read,
dashboard.read,
engine.detect,
damage.detect,
damage.severity,
tire.read,
tire.detect,
parts.recognize,
parts.segment,
parts.decompose,
pricing.vehicle,
pricing.repair,
render.background,
render.enhance,
render.plate,
render.360,
render.video,
render.hotspots
status
enum<string>
required

Lifecycle of a job. queued → processing → one of succeeded | partial | failed; expired when it was never picked up in time, canceled when it was cancelled before starting. Every state after processing is terminal.

Available options:
queued,
processing,
succeeded,
partial,
failed,
expired,
canceled
livemode
boolean
required

false when the job was created with a chk_test_ key: fixture result, test credits.

created
integer<int64>
required

Epoch seconds, UTC.

Example:

1755300000

started_at
integer<int64> | null
required

When the job left the queue. Null while queued.

Example:

1755300000

completed_at
integer<int64> | null
required

When the job settled. Null until then.

Example:

1755300000

model_version
string | null
required

Exact model build that produced the result, as <model>@<release date>. Null until the job starts. Pin your regression tests to it.

Example:

"plate-reader@2026-08-27"

credits
object
required

Credit accounting for the job. One thousand credits equal one USD. reserved is held at admission and charged is the real cost after settlement; unused credits are released.

result
object | null
required

Endpoint-specific payload, null until the job succeeds. See each endpoint's 200 / 202 schema for its exact shape.

error
object | null
required

Populated when status is failed or expired, null otherwise.

test_scenario
string

The X-Carhub-Test-Scenario that produced this job. Present on test-mode jobs that were steered by one, absent otherwise — a live job never carries it.

Example:

"low_confidence"