A depth map API with explicit cost and failure boundaries

Send JSON to POST /api/v1/depth-map with an Authorization: Bearer header and a single imageDataUri field. The value must be a compressed PNG, JPEG, or WebP data URI under 1.5 MB, and it is validated before any provider call is made. A request that fails validation costs nothing and creates no job.

A successful call returns a job identifier, a status, and a temporary depth-map URL. That URL is hosted by the inference provider and expires, so a production integration copies the bytes into its own authorised storage during the request rather than handing the link to a user or writing it to a queue that may run hours later.

One credit is debited per successful request, and the ledger records each movement with a unique reference so a retry or a duplicated callback cannot debit or refund twice. Requests are rate limited per key, and a rejected request does not consume credit. New accounts include one welcome credit, which is enough to test a real integration path rather than a toy payload.

When the upstream provider reports a failure, the debit is returned automatically. The distinction that matters operationally is between a technical failure and a completed estimate you did not like: a refund covers the first, never the second. Build your retry logic around that boundary instead of retrying an unsuitable image.

Keys are shown once and stored only as hashes, so a lost key is rotated rather than recovered. Keep them on the server: a live key in a browser bundle, a mobile binary, or a public repository is equivalent to publishing it. Compress and resize images in your own trusted backend before sending, and set a client timeout so a stalled request does not hold a worker open.

Record the job identifier alongside your own request identifier. When a user reports a bad result, that pair is what lets you retrieve the exact input fingerprint and job state without storing the source image, which DepthCarve deliberately does not keep.