Name: Depth Anything 3 Metric Large API: Depth in Meters
Brand: magicapi
SKU: api-magicapi-metric-depth-estimation-david20321-depth-anything-v3-metric-large
Availability: InStock
Author: API Market

Shashank Agarwal

# 📏 Metric Depth Estimation API (ByteDance Depth Anything 3 Metric Large)

## Overview
Depth Anything 3 Metric Large (DA3Metric-Large) is a depth model from the Depth Anything 3 family by ByteDance Seed, released under the Apache 2.0 license. Its developer describes this build as metric depth estimation that returns a 16-bit PNG depth map with metric metadata. This listing is packaged by david20321.

Metric depth means the values are distances on a real-world scale (meters), not only an ordering of nearer and farther parts of the scene.

Send one image URL in `image`. The API returns a JSON object with a link to the 16-bit PNG depth map (`depth_png`), the nearest and farthest depth in meters (`depth_min_m`, `depth_max_m`), the values needed to turn PNG pixel values into meters (`offset_m`, `scale_m_per_unit`) and details of how the image was processed.

## Features
- **Single-image metric depth**: one ordinary photo in, a depth map in meters out. No stereo pair or depth sensor needed.
- **16-bit PNG depth map**: `depth_png` is a URL to a 16-bit PNG, together with `depth_min_m`, `depth_max_m`, `offset_m` and `scale_m_per_unit` to convert pixel values to meters.
- **Focal length control**: set `focal_length_px` to your camera's focal length in pixels. The default of `0` uses a 60 degree horizontal field of view heuristic; the value used is returned as `focal_length_used`.
- **Processing resolution cap**: `max_process_res` caps the resolution the model processes at (`0` uses the server default cap); the value used is returned as `process_res_used`.
- **Raw float depth**: set `return_raw_depth` to `true` to also get a compressed NPZ file with the float32 metric depth map in `depth_npz`.
- **Optional base64 copy**: `include_base64` (default `true`) adds the depth PNG as a base64 string in `depth_png_base64`.

## Use Cases
1. **3D reconstruction and point clouds**: combine the metric depth map with the focal length to place each pixel in 3D.
2. **Robotics and AR prototypes**: estimate distances to surfaces in a scene from a single camera frame.
3. **Measuring scenes from photos**: read the nearest and farthest distances directly from `depth_min_m` and `depth_max_m`.
4. **Depth inputs for other models**: use the depth map as a control image for depth-guided image or video generation.
5. **Photo effects**: depth-based background blur, fog or relighting driven by real distances.

## Visual Examples
### Example Input
![Example input photo for metric depth estimation](https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-input-api-market.jpg)

- `focal_length_px`: `0` (60 degree horizontal field of view heuristic)
- `max_process_res`: `0` (server default cap)
- `return_raw_depth`: `false`
- `include_base64`: `false`

### Example Output
![16-bit metric depth map returned for the example photo](https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-output-b304p3yh-api-market.png)

The returned JSON (`depth_png` points to the depth map above):

```json
{
  "contract_version": "da3-metric/v1",
  "depth_max_m": 16.037353038787842,
  "depth_min_m": 3.306834638118744,
  "depth_npz": null,
  "depth_png": "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-output-b304p3yh-api-market.png",
  "depth_png_base64": null,
  "focal_length_used": 886.8100134752652,
  "input_height_px": 1024,
  "input_width_px": 1024,
  "model_commit": "2c21ea849ceec7b469a3e62ea0c0e270afc3281a",
  "model_name": "DA3METRIC-LARGE",
  "model_ref": "depth-anything/DA3METRIC-LARGE",
  "offset_m": 3.306834638118744,
  "process_res_used": 1024,
  "scale_m_per_unit": 0.00019425525903210648
}
```

For this 1024 x 1024 image the model processed at 1024 pixels, used a focal length of about 886.8 pixels and measured depth from 3.31 m to 16.04 m. These numbers fit `meters = offset_m + pixel value x scale_m_per_unit`: pixel value 0 is `depth_min_m` and 65535 is `depth_max_m`.

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Input image URL |
| `focal_length_px` | number | No | `0` |  | Focal length in pixels. The default `0` uses a 60 degree horizontal field of view heuristic |
| `max_process_res` | integer | No | `0` |  | Optional per-request cap for the model's processing resolution. `0` uses the server default cap |
| `return_raw_depth` | boolean | No | `false` | `true`, `false` | Include the float32 metric depth map as a compressed NPZ file (`depth_npz`) |
| `include_base64` | boolean | No | `true` | `true`, `false` | Include the depth PNG as a base64 string (`depth_png_base64`) |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.027 per API unit.
- **1 API unit = 1 successful request with up to 108 seconds of processing.** A longer job bills one more unit for each started block of 108 seconds (for example, 120 seconds of processing is 2 units, $0.054).
- **Example cost**: the example request (a 1024 x 1024 image) took 5.7 seconds of processing, which is 1 unit, so $0.027.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/metric-depth-estimation-david20321-depth-anything-v3-metric-large`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/metric-depth-estimation-david20321-depth-anything-v3-metric-large/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "e3523ab17a5e6f0e279933a6afdde67efe130bb9e7753cafc52a4b082257f46b",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-input-api-market.jpg",
      "include_base64": false,
      "focal_length_px": 0,
      "max_process_res": 0,
      "return_raw_depth": false
    }
  }'
```

Response (201 Created):
```json
{
  "id": "b304p3yh05rgc0d1d9qvwb2npr",
  "version": "e3523ab17a5e6f0e279933a6afdde67efe130bb9e7753cafc52a4b082257f46b",
  "status": "starting",
  "created_at": "2026-10-23T20:24:35.529Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/metric-depth-estimation-david20321-depth-anything-v3-metric-large/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "b304p3yh05rgc0d1d9qvwb2npr",
  "status": "succeeded",
  "output": {
    "contract_version": "da3-metric/v1",
    "depth_max_m": 16.037353038787842,
    "depth_min_m": 3.306834638118744,
    "depth_npz": null,
    "depth_png": "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-output-b304p3yh-api-market.png",
    "depth_png_base64": null,
    "focal_length_used": 886.8100134752652,
    "input_height_px": 1024,
    "input_width_px": 1024,
    "model_commit": "2c21ea849ceec7b469a3e62ea0c0e270afc3281a",
    "model_name": "DA3METRIC-LARGE",
    "model_ref": "depth-anything/DA3METRIC-LARGE",
    "offset_m": 3.306834638118744,
    "process_res_used": 1024,
    "scale_m_per_unit": 0.00019425525903210648
  },
  "error": null,
  "created_at": "2026-10-23T20:24:35.529Z",
  "started_at": "2026-10-23T20:27:22.684Z",
  "completed_at": "2026-10-23T20:27:28.346Z"
}
```

`output` is a JSON object. `depth_png` is the URL of the 16-bit PNG depth map. `depth_min_m` and `depth_max_m` are the nearest and farthest depth in meters, and `offset_m` and `scale_m_per_unit` convert PNG pixel values to meters. `focal_length_used`, `process_res_used`, `input_width_px` and `input_height_px` describe how the image was processed, and `contract_version`, `model_name`, `model_ref` and `model_commit` identify the output format and model build. `depth_npz` (the float32 depth map as NPZ, when `return_raw_depth` is `true`) and `depth_png_base64` (when `include_base64` is `true`) are `null` otherwise.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image` or a `max_process_res` that is not an integer.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Check that `image` is a public URL of a readable image. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/metric-depth-estimation-david20321-depth-anything-v3-metric-large";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "e3523ab17a5e6f0e279933a6afdde67efe130bb9e7753cafc52a4b082257f46b", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "image": "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-input-api-market.jpg",
  "include_base64": false,
  "focal_length_px": 0,
  "max_process_res": 0,
  "return_raw_depth": false
}).then((result) => {
  console.log("Depth map:", result.depth_png);
  console.log(`Depth range: ${result.depth_min_m} m to ${result.depth_max_m} m`);
});
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/metric-depth-estimation-david20321-depth-anything-v3-metric-large"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "e3523ab17a5e6f0e279933a6afdde67efe130bb9e7753cafc52a4b082257f46b", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


result = create_and_wait_for_prediction({
  "image": "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-large-input-api-market.jpg",
  "include_base64": False,
  "focal_length_px": 0,
  "max_process_res": 0,
  "return_raw_depth": False
})
print("Depth map:", result["depth_png"])
print(f"Depth range: {result['depth_min_m']} m to {result['depth_max_m']} m")
```

## FAQ
- **How do I turn the PNG into distances in meters?**
  - Read the PNG as 16-bit values and compute `offset_m + value x scale_m_per_unit` for each pixel. In the example, value 0 is 3.31 m (`depth_min_m`) and 65535 is 16.04 m (`depth_max_m`). For the exact float values, set `return_raw_depth` to `true` and read the NPZ file in `depth_npz`.
- **What does `focal_length_px` change?**
  - Metric depth depends on the camera's focal length. If you know it in pixels, pass it; otherwise the default `0` assumes a 60 degree horizontal field of view. The value used comes back as `focal_length_used`.
- **What is `max_process_res` for?**
  - It caps the resolution the model processes the image at for this request. `0` keeps the server default cap. The value used comes back as `process_res_used`.
- **Should I keep `include_base64` on?**
  - Only if you want the PNG inline in the response. It defaults to `true`; set it to `false`, as in the example, to get just the `depth_png` URL and a smaller response.
- **Does it accept several images per request?**
  - No. `image` takes one image URL; send one request per image.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Estimate metric depth from one image with ByteDance Depth Anything 3 Metric Large: a 16-bit PNG depth map, depth range in meters and optional float32 NPZ.