A depth map API with explicit cost and failure boundaries

The DepthCarve API accepts JSON at POST /api/v1/depth-map with a Bearer API key and an imageDataUri field. Input is validated before a provider call and limited to compressed PNG, JPEG, or WebP data. A useful result preserves the shapes that control the next operation while suppressing background distance, edge halos, and texture that would become false geometry. DepthCarve keeps the source beside the estimate and exposes range controls before export, so a technically valid file does not get mistaken for production-ready input.

Resize and compress in your own trusted backend, set a client timeout, and save the returned file immediately. Do not place a live DepthCarve key in public JavaScript or a mobile application bundle. Black point removes low-value range, white point sets the upper boundary, contrast separates meaningful levels, and inversion chooses which end becomes raised or near. These controls are applied to the output instead of triggering another inference, which makes comparison fast and keeps model usage predictable.

Start with the free 8-bit PNG to confirm orientation, crop, and silhouette in your backend, queue, or media pipeline. If the receiving application expects a 16-bit grayscale container, authorize that export after the preview is approved. When the next stage needs closed geometry, set real dimensions and build the watertight relief STL rather than importing an open displacement sheet.

The optional geometry bundle adds provider-generated depth, normals, point cloud, GLB, and camera information for workflows that need more than a grayscale preview. Provider files are temporary and should be downloaded immediately. Keep the chosen DepthCarve settings with the project so a revision can be reproduced without guessing which range or inversion created the approved result.

The current response is a relative visual depth preview, not certified metric distance. External URLs are temporary, and production code must copy required output into its own authorized storage. Zoom into boundaries, look for isolated bright or dark islands, and test the output at the final aspect ratio. A higher mesh grid or a 16-bit container cannot repair an incorrect scene interpretation. Correct the crop, source lighting, or depth range first; only add density after the underlying field is useful.

DepthCarve makes previews free because visual approval should happen before a professional export or provider job is charged. Paid provider failures create a unique refund entry automatically. That protection covers technical failure, not an aesthetically unsuitable but completed estimate, so the preview remains the essential acceptance gate.

The browser compresses the selected image before it leaves the device. The source is sent to the chosen inference provider only when Generate is pressed, and D1 stores job state, an input fingerprint, and credit entries rather than the original file. Model output URLs can expire, so download approved assets into the normal project archive instead of treating a provider link as storage.

Every credit movement carries a unique reference. Repeated callbacks cannot grant the same purchase twice, and repeated export authorization for the same user, job, and format does not keep charging. External requests retry only bounded server errors. Clear failures are returned to the interface rather than being hidden behind a permanent loading state.