Depth map API: build or buy, and what the bill actually includes

A depth API receives an image and returns a depth representation. The contract should state the accepted format, the maximum size, the output format, the expected latency, the failure modes, and the retention behavior. If any of those is vague, the integration will discover it in production.

DepthCarve's server-to-server endpoint accepts a compressed image data URI up to 1.5 MB, returns a temporary depth-map URL, costs one credit per successful request, and is rate limited per key. The contract is published as OpenAPI so a client can generate a typed wrapper instead of guessing.

A synchronous call that sometimes takes ten seconds and sometimes two minutes is hard to put behind a user interface. A queue with a job id and a poll or callback contract is easier to reason about, but it adds state: queued, processing, succeeded, failed, refunded. Each state needs a timeout and a recovery path.

If the Worker dies between reserving a credit and receiving a provider id, the job can be left in processing forever. The system needs a reconciliation sweep that closes stale rows and refunds the debit. This is not an edge case at scale; it is a Tuesday.

A job contract should expose a stable id, a state, a created time, and a terminal error code. The client should be able to answer three questions without reading logs: is it still running, did it succeed, and if it failed, will the credit come back? A state machine that can only say processing forces support to guess.

A retry should not charge twice. The safest pattern is a client-supplied idempotency key mapped to a server-side job, with one debit per successful job and an automatic refund on confirmed provider failure. The debit and the refund should be separate ledger entries with unique references so a duplicate callback cannot create a second charge.

If the API sells credits, the ledger is the source of truth. Usage counters that are not reconciled with the ledger will drift. The customer will notice before the dashboard does.

Store the idempotency key with the job row and enforce uniqueness in the database, not in application memory. Two workers can process the same retry at the same time; only a unique constraint makes the debit safe. A repeated key should return the original job, not create a second one.

Model providers often return signed URLs that expire. A product can either copy the output into its own storage or tell the customer to download it immediately. Copying adds storage cost and retention obligations; not copying adds support load when a link expires.

DepthCarve keeps the provider links temporary and does not store the ZIP. The contract says so, the UI says so, and the rebuild path is free while the link works. If your product needs long retention, budget for object storage and a lifecycle policy rather than pretending the provider URL is permanent.

The model price is only one term. Add the cost of failed calls, retries, idle capacity, storage, egress, support, and the engineering time to keep the queue healthy. A cheap model with a 10% failure rate can be more expensive than a reliable one when the failures are refunded or retried.

Measure cost per successful job, not cost per call. Measure it after refunds and retries. That number is what the price has to cover.

Track four numbers per provider: requests, successes, confirmed failures, and median completion time. A provider that is cheap per call but slow enough to trigger client retries can dominate the bill. Alert on the failure rate and the queue age, not only on the monthly invoice.

Build when depth is the core differentiator, the volume justifies a dedicated team, and you need control over the model, the data path, or the latency. Buy when depth is a supporting feature and the harder problem is the product around it: accounts, billing, review, and support.

A middle path is to build the product surface and buy the model call. That is what DepthCarve does. The workbench, the review loop, the credit ledger, and the bundle contract are ours; the inference is a provider contract with a fallback and a refund path.

A written exit plan matters too. If the provider changes its price or deprecates the model, can you swap it without changing the customer contract? Keep the model call behind one adapter and store the provider name with each job so a migration is measurable. Record the model version in the job output as well; a silent provider upgrade can change the result even when the contract looks stable.