> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycarhub.com/llms.txt > Use this file to discover all available pages before exploring further. # Image Customizer > Customize one vehicle photograph from your prompt for a marketing publication. Invite-only beta: beta access is required for both live and test keys, including the Playground. Accepts exactly one JPEG, PNG, or WebP image up to 20 MiB and 40 megapixels. Produces one 1K PNG with Nano Banana 2.1 (`gemini-nano-banana-2.1`) on Vertex AI, without external search. A prompt such as "Wash the car" produces a clean car, without a washing scene. Explicit modifications are allowed; unaffected vehicle details and source orientation are preserved as closely as possible. Visual fidelity must be evaluated on the generated result. Reserves 400 credits and charges 400 credits only for a successful image. Refusals and invalid image responses fail without a charge. Poll the returned job or use a webhook. Jobs expire after 300 seconds. Result URLs expire after 15 minutes by default, as indicated by `result.image.expires_at`; polling does not renew them. Download the image before expiration. Test keys return a deterministic fixture and never call Vertex AI. Batch inputs, unknown parameters, and conversation history are not accepted. ## OpenAPI ````yaml /openapi.yaml post /v1/render/customize openapi: 3.1.0 info: title: CarHub API version: '2026-10-04' summary: >- Automotive AI as a service — 23 inference endpoints, one asynchronous contract. description: > CarHub exposes automotive computer-vision and pricing models as plain HTTP endpoints. Every model is priced and rate-limited on its own — nothing requires adopting the rest. ## Two API surfaces | Surface | Prefix | Authentication | |---|---|---| | Inference (the product) | `/v1/…` | API key — `Authorization: Bearer chk_live_…` / `chk_stg_…` / `chk_test_…` | | Management (the dashboard) | `/mgmt/v1/…` | Short-lived JWT — `Authorization: Bearer ` | ## Everything is a job Every inference endpoint is `POST` and **asynchronous by default**: it answers `202` with a [`Job`](#/components/schemas/Job) in status `queued`. Collect the result by polling `GET /v1/jobs/{id}` or by subscribing to `job.succeeded`, `job.partial`, and `job.failed` webhooks. Fast endpoints additionally accept `?wait=true`, which holds the connection until the job settles (30 s ceiling) and answers `200` with the same `Job` object in status `succeeded`. Video, 360 and bundle endpoints reject `wait` with `400 wait_not_supported` — their work outlives any reasonable request timeout. ## Inputs Every endpoint accepts two request encodings for the same operation: * `multipart/form-data` — the binary directly in the request (`image`, `audio`, `video` or `images[]` depending on the endpoint). Simplest path, capped at 10 MB per file. * `application/json` — `{"input_ref": "upl_…"}` (or `input_refs` for multi-asset endpoints) referencing an upload created through `POST /v1/uploads`. Required for videos and batches. Endpoint parameters are identical in both encodings. ## Idempotency Send `Idempotency-Key` on any `POST`. A replayed key returns the original response and never bills twice; reusing a key with a different payload is a `409 idempotency_key_reuse`. ## Test mode Keys prefixed `chk_test_` run the entire pipeline — auth, rate limiting, job lifecycle, ledger, signed webhooks — against a fixture backend instead of a GPU. Test jobs carry `livemode: false` and draw on a separate, freely rechargeable test credit balance. Drive the fixture backend per request with `X-Carhub-Test-Scenario`. termsOfService: https://trycarhub.com/terms contact: name: CarHub API support url: https://docs.trycarhub.com email: api@trycarhub.com license: name: Proprietary identifier: LicenseRef-CarHub-Commercial servers: - url: https://api.trycarhub.com description: Production (EU) security: - ApiKeyAuth: [] tags: - name: A — Understand the vehicle description: >- Identity, attributes and a clean capture — everything downstream reads from here. - name: B — Damage & condition description: Find it, then grade it, so your own rules can act on the result. - name: C — Parts description: >- Turns "there is damage" into "there is damage on this component" — what makes every downstream estimate defensible. - name: D — Money description: Valuation and repair cost, computed from what was actually observed. - name: E — Image production description: >- Exposed as raw infrastructure, not a batch retouching service. Call it per asset, in your own pipeline. - name: Jobs description: Status, results and history of asynchronous work. - name: Uploads description: Presigned storage for videos and batches. - name: Assets description: >- Permanent organization artwork and custom background packages in private storage. - name: Management description: >- Organisation, API keys, usage, billing and outgoing webhooks. JWT authenticated. - name: Internal description: Inbound callbacks from the inference plane. Never called by customers. externalDocs: description: CarHub developer documentation url: https://docs.trycarhub.com paths: /v1/render/customize: post: tags: - E — Image production summary: Image Customizer description: > Customize one vehicle photograph from your prompt for a marketing publication. Invite-only beta: beta access is required for both live and test keys, including the Playground. Accepts exactly one JPEG, PNG, or WebP image up to 20 MiB and 40 megapixels. Produces one 1K PNG with Nano Banana 2.1 (`gemini-nano-banana-2.1`) on Vertex AI, without external search. A prompt such as "Wash the car" produces a clean car, without a washing scene. Explicit modifications are allowed; unaffected vehicle details and source orientation are preserved as closely as possible. Visual fidelity must be evaluated on the generated result. Reserves 400 credits and charges 400 credits only for a successful image. Refusals and invalid image responses fail without a charge. Poll the returned job or use a webhook. Jobs expire after 300 seconds. Result URLs expire after 15 minutes by default, as indicated by `result.image.expires_at`; polling does not renew them. Download the image before expiration. Test keys return a deterministic fixture and never call Vertex AI. Batch inputs, unknown parameters, and conversation history are not accepted. operationId: renderCustomize parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TestScenario' requestBody: required: true content: multipart/form-data: schema: type: object additionalProperties: false required: - image - prompt properties: image: type: string format: binary description: One JPEG, PNG, or WebP image up to 20 MiB. prompt: $ref: '#/components/schemas/CustomizePrompt' application/json: schema: type: object additionalProperties: false required: - input_ref - prompt properties: input_ref: type: string description: An available upload reference owned by your organization. prompt: $ref: '#/components/schemas/CustomizePrompt' example: input_ref: upl_example prompt: >- Wash the car. Keep its current paint color, wheels, equipment, and background. responses: '200': description: Existing job returned by an idempotent replay. content: application/json: schema: $ref: '#/components/schemas/RenderCustomizeJob' '202': description: Job accepted, 400 credits reserved, work queued. headers: Request-Id: $ref: '#/components/headers/RequestId' Location: $ref: '#/components/headers/JobLocation' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/RenderCustomizeJob' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: > 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`. schema: type: string minLength: 8 maxLength: 255 examples: uuid: value: 8b1f1c2e-9d3a-4a51-9f0c-1c9a2f6d7b44 TestScenario: name: X-Carhub-Test-Scenario in: header required: false description: > Steers the fixture backend. Ignored by live keys, `400 test_scenario_not_supported` if the scenario is unknown to the endpoint. Common catalogue: | Scenario | Effect | |---|---| | *(absent)* | Deterministic success — the endpoint's `default` fixture. | | `empty_result` | Success with nothing detected: empty lists, null readings. | | `low_confidence` | Success with every confidence below 0.5. | | `model_error` | Job settles `failed`; the reservation is released. | | `slow` | Completion after ~30 s — makes `wait=true` time out. | | `insufficient_credits` | `402` at admission, no job created. | Some endpoints add their own scenarios; unsupported common scenarios (for example `empty_result` on a generation endpoint) are rejected rather than silently ignored. schema: type: string examples: - empty_result - low_confidence - model_error - slow - insufficient_credits schemas: CustomizePrompt: type: string minLength: 1 maxLength: 4000 pattern: \S x-multiline: true description: >- Describe the final photograph you want. Only explicitly requested modifications should affect the vehicle. 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. RenderCustomizeJob: allOf: - $ref: '#/components/schemas/Job' - type: object properties: result: oneOf: - $ref: '#/components/schemas/RenderCustomizeResult' - type: 'null' Job: type: object title: Job description: > 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`. required: - id - object - endpoint - status - livemode - is_staging - created - started_at - completed_at - model_version - credits - result - error properties: is_staging: type: boolean default: false description: >- Staging classification. Requires live mode and uses the organisation's shared live credits. id: $ref: '#/components/schemas/JobIdString' object: type: string const: job endpoint: $ref: '#/components/schemas/EndpointSlug' status: $ref: '#/components/schemas/JobStatus' livemode: type: boolean description: >- `false` when the job was created with a `chk_test_` key: fixture result, test credits. created: $ref: '#/components/schemas/Timestamp' started_at: description: When the job left the queue. Null while `queued`. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' completed_at: description: When the job settled. Null until then. oneOf: - $ref: '#/components/schemas/Timestamp' - type: 'null' model_version: type: - string - 'null' description: >- Exact model build that produced the result, as `@`. Null until the job starts. Pin your regression tests to it. examples: - plate-reader@2026-08-27 credits: $ref: '#/components/schemas/JobCredits' result: description: >- Endpoint-specific payload, null until the job succeeds. See each endpoint's `200` / `202` schema for its exact shape. oneOf: - type: object - type: 'null' error: description: Populated when `status` is `failed` or `expired`, null otherwise. oneOf: - $ref: '#/components/schemas/JobError' - type: 'null' test_scenario: type: string description: >- 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. examples: - low_confidence RenderCustomizeResult: type: object additionalProperties: false required: - image properties: image: allOf: - $ref: '#/components/schemas/RenderedAsset' - type: object required: - url - expires_at - format - width - height - bytes properties: format: type: string enum: - png width: type: integer minimum: 1 height: type: integer minimum: 1 bytes: type: integer minimum: 1 ErrorResponse: type: object title: Error response description: >- The single error envelope of the API. Every non-2xx response on every route group has exactly this shape. required: - error additionalProperties: false properties: error: $ref: '#/components/schemas/Error' JobIdString: type: string description: Job identifier — `job_` followed by a base58 string. pattern: ^job_[1-9A-HJ-NP-Za-km-z]{8,32}$ examples: - job_3ZxK9pQr7TnW EndpointSlug: type: string description: >- Dotted slug of a CarHub endpoint, the identifier used for jobs and usage. enum: - 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 JobStatus: type: string description: > 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. enum: - queued - processing - succeeded - partial - failed - expired - canceled Timestamp: type: integer format: int64 description: Epoch seconds, UTC. examples: - 1755300000 JobCredits: type: object description: > 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. required: - reserved - charged properties: reserved: type: integer minimum: 0 examples: - 20 charged: type: - integer - 'null' minimum: 0 description: Null while the job is unsettled. examples: - 20 JobError: type: object description: Why a job settled in `failed` or `expired`. required: - type - code - message properties: type: type: string enum: - processing_error - invalid_request - internal code: type: string examples: - model_inference_failed - unreadable_input - upstream_timeout - job_expired message: type: string RenderedAsset: type: object title: Rendered asset description: >- A file produced by a generation endpoint, served from a signed URL that expires. Download and re-host anything you intend to keep — the object is also subject to your organisation's storage TTL. required: - url - expires_at - format properties: url: type: string format: uri expires_at: $ref: '#/components/schemas/Timestamp' format: type: string enum: - jpg - png - webp - mp4 - webm width: type: - integer - 'null' minimum: 1 height: type: - integer - 'null' minimum: 1 bytes: type: - integer - 'null' minimum: 0 Error: type: object required: - type - code - message - param - doc_url - request_id properties: type: type: string description: >- Broad class of the failure — enough to branch on without matching codes. enum: - invalid_request - authentication - permission - rate_limit - insufficient_credits - not_found - conflict - processing_error - internal code: type: string description: >- Stable machine-readable identifier, narrower than `type`. New codes may appear; treat an unknown code as its `type`. examples: - missing_input - invalid_api_key - rate_limit_exceeded message: type: string description: >- English, human-readable, safe to log. Never localised, never for end users. param: type: - string - 'null' description: >- The offending field or header, when the failure can be attributed to one. doc_url: type: string format: uri description: Documentation page for this exact code. examples: - https://docs.trycarhub.com/errors/missing_input request_id: type: string description: >- Identifier of the failing request, mirrored in the `Request-Id` header. examples: - req_2Kd8xQmPvL4T quota_bytes: type: integer description: Organisation storage limit for `storage_quota_exceeded`. stored_bytes: type: integer reserved_bytes: type: integer available_bytes: type: integer requested_bytes: type: integer oldest_deletable_ref: type: string oldest_deletable_at: type: string format: date-time headers: RequestId: description: Unique identifier of this request. Quote it in any support conversation. schema: type: string examples: - req_2Kd8xQmPvL4T JobLocation: description: Absolute URL of the created job. schema: type: string format: uri examples: - https://api.trycarhub.com/v1/jobs/job_3ZxK9pQr7TnW IdempotentReplayed: description: >- `true` when this response was replayed from a previous request carrying the same `Idempotency-Key`. Absent when the request was executed for real. schema: type: boolean RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 examples: - 12 RateLimitLimit: description: Requests allowed in the current window for this endpoint and plan. schema: type: integer examples: - 120 RateLimitRemaining: description: Requests left in the current window. schema: type: integer examples: - 0 RateLimitReset: description: Epoch second at which the current window resets. schema: type: integer examples: - 1755300060 responses: BadRequest: description: > Malformed or unusable request — bad JSON, missing or oversized file, unknown parameter, `wait=true` on an endpoint that does not support it. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingInput: summary: No input supplied value: error: type: invalid_request code: missing_input message: Provide either a multipart `image` field or an `input_ref`. param: image doc_url: https://docs.trycarhub.com/errors/missing_input request_id: req_2Kd8xQmPvL4T waitUnsupported: summary: wait=true on a long-running endpoint value: error: type: invalid_request code: wait_not_supported message: >- This endpoint is long-running; poll the job or use a webhook instead. param: wait doc_url: https://docs.trycarhub.com/errors/wait_not_supported request_id: req_2Kd8xQmPvL4T Unauthorized: description: Missing, malformed, revoked or expired credential. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidKey: value: error: type: authentication code: invalid_api_key message: The provided API key is invalid or has been revoked. param: null doc_url: https://docs.trycarhub.com/errors/invalid_api_key request_id: req_2Kd8xQmPvL4T InsufficientCredits: description: > The organisation's balance cannot cover the reservation for this call. Nothing was queued and nothing was charged. Top up with `POST /mgmt/v1/billing/checkout` — or, in test mode, `POST /mgmt/v1/billing/test-credits`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: emptyCreditBalances: value: error: type: insufficient_credits code: insufficient_credits message: Credit balance is 3 credits; this call reserves 8. param: null doc_url: https://docs.trycarhub.com/errors/insufficient_credits request_id: req_2Kd8xQmPvL4T Forbidden: description: >- Authenticated but not allowed: key scope excludes this endpoint family, role too low for a management route, or the resource belongs to another organisation. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: outOfScope: value: error: type: permission code: scope_not_granted message: This API key is not scoped for the `render` endpoint family. param: null doc_url: https://docs.trycarhub.com/errors/scope_not_granted request_id: req_2Kd8xQmPvL4T NotFound: description: No such resource, or it is not visible to this credential. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknownJob: value: error: type: not_found code: job_not_found message: No job with id `job_3ZxK9pQr7TnW`. param: id doc_url: https://docs.trycarhub.com/errors/job_not_found request_id: req_2Kd8xQmPvL4T Conflict: description: >- The request contradicts the current state — an idempotency key replayed with a different body, or an input storage reservation that exceeds the organisation quota. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyReuse: value: error: type: conflict code: idempotency_key_reuse message: >- This Idempotency-Key was already used with a different request body. param: Idempotency-Key doc_url: https://docs.trycarhub.com/errors/idempotency_key_reuse request_id: req_2Kd8xQmPvL4T RateLimited: description: Too many requests for this endpoint and plan. Back off and retry. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: tooFast: value: error: type: rate_limit code: rate_limit_exceeded message: >- Rate limit of 120 requests per minute exceeded for `plate.read`. param: null doc_url: https://docs.trycarhub.com/errors/rate_limit_exceeded request_id: req_2Kd8xQmPvL4T InternalError: description: >- Something broke on our side. The request was not billed. Retry with the same `Idempotency-Key`; if it persists, quote `request_id`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: error: type: internal code: internal_error message: An unexpected error occurred. param: null doc_url: https://docs.trycarhub.com/errors/internal_error request_id: req_2Kd8xQmPvL4T securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: CarHub API key description: > 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`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.