Name: Depth Anything 3 Metric API: Metric Depth Estimation
Brand: magicapi
SKU: api-magicapi-monocular-metric-depth-estimation-vufinder-depth-anything-v3-metric
Availability: InStock
Author: API Market

Shashank Agarwal

# 📐 Metric Depth Estimation API (ByteDance Depth Anything 3 Metric)

## Overview
Depth Anything 3 Metric is a depth model from the Depth Anything 3 family by ByteDance Seed. Its developer describes this variant as monocular metric depth estimation: it estimates how far each pixel is from the camera using one ordinary photo, with no second camera or depth sensor. This listing is packaged by vufinder.

Metric depth means the values are on a real-world scale rather than only showing which parts of the scene are nearer or farther.

Send one or more image URLs in `images`. For each image the API returns a file with the prediction arrays (JSON or NPZ) in `data` and, by default, a depth image in `depth_images`.

## Features
- **Single-image depth**: one ordinary photo per depth result; no stereo pair or depth sensor needed.
- **Several images per request**: `images` takes a list of image URLs (JPG, JPEG, PNG or WEBP). Each image gets its own result.
- **Depth images**: `return_depth` (default `true`) adds a depth image per input image in `depth_images`.
- **Raw arrays**: `data` holds the prediction arrays as JSON (default) or NPZ (`output_format`). In JSON, `to_base64` (default `true`) stores arrays as base64 strings with their shape and dtype; `keys_to_exclude` drops keys you do not need.
- **Processing resolution**: `default` works at 504 px (36 patches of 14 px), `match_input` follows the input size and `custom` uses `num_patches`.
- **Transparent images**: `alpha_blend_onto` sets how alpha channels are handled (`keep`, `white`, `black` or `mean`).

## Use Cases
1. **Distance estimates from photos**: read approximate distances to objects in a scene from the metric depth arrays.
2. **3D and AR content**: turn single photos into depth maps for 3D photo effects or scene layout.
3. **Robotics and scene understanding**: add a depth estimate to camera frames when no depth sensor is available.
4. **Dataset preparation**: create depth maps for image collections to use as training or evaluation data.

## Visual Examples
### Example Input
One photo in `images`, with `processing_resolution` set to `match_input` and `alpha_blend_onto` set to `white`:

![Depth Anything 3 Metric example input photo](https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-input-api-market.jpeg)

```json
{
  "images": [
    "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-input-api-market.jpeg"
  ],
  "to_base64": true,
  "num_patches": 36,
  "return_depth": true,
  "output_format": "json",
  "keys_to_exclude": "",
  "alpha_blend_onto": "white",
  "processing_resolution": "match_input"
}
```

### Example Output
The depth image from `depth_images`:

![Depth Anything 3 Metric example output: depth image of the input photo](https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-output-gnfdke8n-api-market.png)

The response also returned one JSON file in `data` with the prediction arrays for the image (base64 strings with shape and dtype, because `to_base64` was `true`).

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `output_format` | string | No | `json` | `json`, `npz` | Format of the prediction result files in `data` |
| `processing_resolution` | string | No | `default` | `default`, `match_input`, `custom` | Maximum spatial size of the image passed to the model. `default` is 504 px (36 patches of 14 x 14 px). `match_input` computes the size from the inputs (across all images in the request). `custom` uses `num_patches`. |
| `alpha_blend_onto` | string | No | `keep` | `keep`, `white`, `black`, `mean` | How to handle images with an alpha channel. `mean` blends the image onto the ImageNet mean RGB values; `keep` keeps the original pixel values. |
| `images` | array of URLs | Yes | none |  | Input image URLs (JPG, JPEG, PNG or WEBP). Each image gets its own result. |
| `keys_to_exclude` | string | No | `""` |  | Comma-separated list of keys to leave out of the output JSON files |
| `num_patches` | integer | No | `36` |  | Maximum spatial size of the image in patches of 14 px. Only used when `processing_resolution` is `custom`. |
| `return_depth` | boolean | No | `true` |  | Whether to return depth images in `depth_images` |
| `to_base64` | boolean | No | `true` |  | Whether to store the arrays in the JSON files as base64 strings with shape and dtype |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.024 per API unit.
- **1 API unit = 1 successful request with up to 22 seconds of processing.** A request that takes longer is billed one more unit for each started block of 22 seconds (for example, 45 seconds of processing is 3 units, $0.072).
- Each request is billed on its total processing time, so sending several images, or using a larger `processing_resolution`, can use more units.
- **Example cost**: the example request above took 2.9 seconds of processing, so it used 1 API unit and cost $0.024.
- **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/monocular-metric-depth-estimation-vufinder-depth-anything-v3-metric`

### 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/monocular-metric-depth-estimation-vufinder-depth-anything-v3-metric/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d2ef7653aa75f87e3b502738a3f57ca2b09ba92f6f286075c8929a69937a013f",
    "input": {
      "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-input-api-market.jpeg"
      ],
      "to_base64": true,
      "num_patches": 36,
      "return_depth": true,
      "output_format": "json",
      "keys_to_exclude": "",
      "alpha_blend_onto": "white",
      "processing_resolution": "match_input"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "gnfdke8nd5rmw0d1d1br7tz154",
  "version": "d2ef7653aa75f87e3b502738a3f57ca2b09ba92f6f286075c8929a69937a013f",
  "status": "starting",
  "created_at": "2026-10-23T10:38:20.150Z"
}
```

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

Response when the prediction has finished (200 OK):
```json
{
  "id": "gnfdke8nd5rmw0d1d1br7tz154",
  "status": "succeeded",
  "output": {
    "data": [
      "URL of the JSON file with the prediction arrays for the image"
    ],
    "depth_images": [
      "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-output-gnfdke8n-api-market.png"
    ]
  },
  "error": null,
  "created_at": "2026-10-23T10:38:20.150Z",
  "started_at": "2026-10-23T10:38:44.816Z",
  "completed_at": "2026-10-23T10:38:47.726Z"
}
```

`output` is an object. `data` is a list of result file URLs (JSON or NPZ, per `output_format`), one per input image. `depth_images` is a list of depth image URLs, one per input image, or `null` when `return_depth` is `false`.

### 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 `images` list, an `output_format` other than `json` or `npz`, or a `processing_resolution` that is not in the list.
- **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. 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/monocular-metric-depth-estimation-vufinder-depth-anything-v3-metric";

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: "d2ef7653aa75f87e3b502738a3f57ca2b09ba92f6f286075c8929a69937a013f", 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({
  "images": [
    "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-input-api-market.jpeg"
  ],
  "to_base64": true,
  "num_patches": 36,
  "return_depth": true,
  "output_format": "json",
  "keys_to_exclude": "",
  "alpha_blend_onto": "white",
  "processing_resolution": "match_input"
}).then((output) => console.log(output));
```

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

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


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": "d2ef7653aa75f87e3b502738a3f57ca2b09ba92f6f286075c8929a69937a013f", "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")


print(create_and_wait_for_prediction({
    "images": [
        "https://blog.api.market/wp-content/uploads/2026/10/depth-anything-v3-metric-input-api-market.jpeg"
    ],
    "to_base64": True,
    "num_patches": 36,
    "return_depth": True,
    "output_format": "json",
    "keys_to_exclude": "",
    "alpha_blend_onto": "white",
    "processing_resolution": "match_input"
}))
```

## FAQ
- **Is the depth on a real-world scale?**
  - Its developer describes this variant as metric depth estimation, so the values are on a real-world scale. For depth that only orders the scene from near to far, use the Depth Anything 3 Mono listing.
- **Can I process several images in one request?**
  - Yes. Put several URLs in `images`. You get one result file in `data` and one depth image in `depth_images` per image, and the request is billed on its total processing time.
- **Should I choose JSON or NPZ?**
  - JSON (the default) is easy to read in any language; with `to_base64` set to `true` the arrays are base64 strings with their shape and dtype. NPZ is the NumPy archive format, convenient if you load the arrays in Python.
- **How do I control the resolution?**
  - `processing_resolution` `default` uses 504 px. Use `match_input` to follow the input size, or `custom` together with `num_patches` (each patch is 14 px). Larger sizes take longer and can use more units.
- **How is a request billed?**
  - $0.024 per request for up to 22 seconds of processing, plus one unit for each further started block of 22 seconds.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **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 (absolute-scale) depth from single images with ByteDance Depth Anything 3 Metric: depth images plus JSON or NPZ arrays.