> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Depth Maps API

> Turn a video into a steady depth map video to use as a structure and motion reference for video models, with Video Depth Anything, through the BudgetPixel API.

**Video → depth map video.** Turn a video into a depth map: a video that shows how near or
far each part of the scene is. In the default grayscale, near is white and far is black, and
the result is steady from frame to frame, at the input's frame size and frame rate. The
endpoint is `POST /v1/depth-maps/{model}`.

Use it when a video model should follow the layout and motion of a clip you already have,
without its colours. The depth video works as a reference video; see
[Use the result as a reference video](#use-the-result-as-a-reference-video). The colour
maps (`turbo`, `inferno`, `magma`, `viridis`) are for looking at the depth yourself.

## Model

1 model. Each name opens its API reference with every parameter.

| Model | Maker | What it does |
| - | - | - |
| [Video Depth Anything](/api-reference/depth-maps/make-a-depth-map-with-video-depth-anything)<br />`video-depth-anything` | ByteDance | Turns a video into a depth map video, near white and far black, steady from frame to frame, at the input's frame size (up to 1080p) and frame rate (up to 30 fps), in three sizes. |

## How a request works

1. Send `POST /v1/depth-maps/video-depth-anything` with the `video` and any options. The
   response returns a job `id` right away (it starts with `dpt_`), with the price in
   `credits`.
2. Poll [`GET /v1/depth-maps/{id}`](/api-reference/depth-maps/get-depth-map-job-status)
   until `status` is `succeeded`. The response then holds the depth video's URL in
   `video_url`.

[Media inputs](/concepts/media-inputs) covers passing the video, and
[Async jobs](/concepts/async-jobs) covers job statuses and errors. A job is `pending`,
`processing`, `succeeded`, `failed` or `canceled`; the last three are final.

## Sizes and pricing

`size` picks the model size, which sets the price. A depth map is priced per second of the
**input** video, rounded up to whole seconds, with a 5-second minimum.

| `size` | What you get | Credits per second |
| - | - | - |
| `small` (default) | The fastest, with clean structure. | 20 |
| `base` | Adds edge detail. | 30 |
| `large` | Draws the finest detail (hair, thin poles, distant people) and is the steadiest. | 40 |

Only the size and the length of the input set the price. The output `resolution`,
`colormap`, `keep_audio` and `side_by_side` don't change it. A 12.4-second clip at `large`
bills as 13 seconds, `13 × 40 = 520` credits. A 3-second clip at `small` bills as 5
seconds, `5 × 20 = 100` credits.

[`POST /v1/cost`](/api-reference/models/estimate-the-cost-of-a-request) quotes a request
before you send it. Send the `size` and the clip's length in `seconds`:

```bash theme={null}
curl -X POST https://api.budgetpixel.com/v1/cost \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "video-depth-anything", "size": "large", "seconds": 12.4 }'
```

```json theme={null}
{
  "model": "video-depth-anything",
  "type": "video-depth",
  "unit": "second",
  "size": "large",
  "credits_per_second": 40,
  "size_pricing": { "small": 20, "base": 30, "large": 40 },
  "min_seconds": 5,
  "seconds": 13,
  "credits": 520,
  "exact": true
}
```

Leave out `seconds` to get only the rates: `credits_per_second`, `size_pricing` and
`min_seconds`. [`GET /v1/models?type=video-depth`](/api-reference/models/list-available-models)
lists the model with `credits_per_unit: 20` (the `small` rate) and `size_pricing`, the rate
for every size. You pay only for jobs that succeed; see
[Pricing & credits](/concepts/pricing-and-credits).

## Example

Create the job. This turns a clip into a `large` grayscale depth map:

```bash theme={null}
curl -X POST https://api.budgetpixel.com/v1/depth-maps/video-depth-anything \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "https://example.com/clip.mp4",
    "size": "large"
  }'
```

The response comes back at once. `seconds` is the length you're billed for and `credits` is
the price:

```json theme={null}
{
  "id": "dpt_a1b2c3d4e5f6",
  "status": "pending",
  "model": "video-depth-anything",
  "size": "large",
  "seconds": 13,
  "credits": 520,
  "message": "Depth map job started. Poll GET /v1/depth-maps/{id} until status is succeeded."
}
```

Poll the job until `status` is `succeeded`:

```bash theme={null}
curl https://api.budgetpixel.com/v1/depth-maps/dpt_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```

```json theme={null}
{
  "id": "dpt_a1b2c3d4e5f6",
  "status": "succeeded",
  "model": "video-depth-anything",
  "video_url": "https://...",
  "video_codec": "h264"
}
```

If a job fails, `status` is `failed` and `error_message` says why. Failed jobs aren't
charged.

## Parameters

Every parameter is also on the
[API reference page](/api-reference/depth-maps/make-a-depth-map-with-video-depth-anything).

| Parameter | Type | Default | What it does |
| - | - | - | - |
| `video` | string, required | | The video to turn into a depth map: a public URL, or an uploaded-file URL from `POST /v1/uploads`. Up to 30 seconds, MP4, MOV or WebM, up to 100 MB. |
| `size` | string | `small` | `small`, `base` or `large`. Sets the per-second price; see [Sizes and pricing](#sizes-and-pricing). |
| `colormap` | string | `grayscale` | `grayscale`, `turbo`, `inferno`, `magma` or `viridis`. `grayscale` (near is white) is what video models take as a depth reference; the other four colour the map for viewing. |
| `resolution` | string | `auto` | `auto`, `360p`, `480p`, `720p` or `1080p`. The output's short side. `auto` keeps the input's size, up to 1080p. It never upscales, and the price is the same at every resolution. |
| `keep_audio` | boolean | `false` | Copy the input's audio into the depth video. |
| `side_by_side` | boolean | `false` | Return the input on the left and the depth map on the right, so the video is twice as wide. |

`POST /v1/uploads` takes files up to 50 MB. For a larger video, up to 100 MB, pass a
public URL instead. The input video is checked against BudgetPixel's content policy
before the job starts, like every other input. A blocked request returns `400` and isn't
charged; see [content moderation blocks](/concepts/async-jobs#content-moderation-blocks).

## The result

* **Format.** An H.264 MP4. The poll response reports `video_codec: "h264"`.
* **Frame size and rate.** The input's frame size, up to 1080p (or the `resolution` you
  chose), and the input's frame rate, up to 30 fps.
* **Look.** In grayscale, near is white and far is black.
* **Audio.** The input's audio is copied only when `keep_audio` is `true`.
* **Download it.** `video_url` is a short-lived signed URL; call the poll endpoint again
  for a fresh one. The file itself is deleted 24 hours after generation, so download it if
  you need to keep it.

## Use the result as a reference video

A depth map keeps a clip's layout and motion and drops its colour, which makes it a
structure and motion reference for video models. Take the finished job's `video_url`, pass
it where a video model accepts a reference video (for example `reference_videos` on
SeeDance 2.5), and describe the scene you want in the prompt.

* Keep the default `grayscale` colormap for this. It's the one video models take as a depth
  reference.
* Leave `side_by_side` off for a reference clip: it adds the input video next to the depth
  map.
* Use the URL right away or download the file, since it's deleted after 24 hours.

The [Video generation API](/apis/video-generation-api) lists the video models, and
[Video generation modes](/concepts/models#video-generation-modes) shows which inputs each
one takes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.