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. 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.How a request works
- Send
POST /v1/depth-maps/video-depth-anythingwith thevideoand any options. The response returns a jobidright away (it starts withdpt_), with the price incredits. - Poll
GET /v1/depth-maps/{id}untilstatusissucceeded. The response then holds the depth video’s URL invideo_url.
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.
Only the size and the length of the input set the price. The output
resolution,
colormap, keep_audio, side_by_side, face_mesh and include_face_landmarks 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 quotes a request
before you send it. Send the size and the clip’s length in seconds:
seconds to get only the rates: credits_per_second, size_pricing and
min_seconds. GET /v1/models?type=video-depth
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.
Example
Create the job. This turns a clip into alarge grayscale depth map:
seconds is the length you’re billed for and credits is
the price:
status is succeeded:
status is failed and error_message says why. Failed jobs aren’t
charged.
Parameters
Every parameter is also on the API reference page.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.
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
resolutionyou 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_audioistrue. - Download it.
video_urlis 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.
Face mesh
A depth map keeps bodies and motion but flattens faces, so a video model loses lip movement and expressions. Withface_mesh: true the depth map also carries each face’s
mesh: thin cyan lines over the face, green eyes, brows and irises, and orange lips. Faces
are found automatically, up to max_faces, and keep their own mesh as people move.
- When to use it. Clips where people talk, sing or show expressions. Tell the video model in your prompt that the mesh lines are guidance and must not appear.
- Small faces. Faces under about 140 pixels high get the face outline, nose, eyes and lips instead of the full mesh, so they don’t turn into a solid patch.
- Limits. A face turned to full profile gets no mesh until it turns back toward the
camera. A clip with no face still returns its depth map;
face_mesh.coverageis then0.
face_landmarks_url appears with include_face_landmarks: true. It’s a short-lived
signed URL to a JSON file that’s kept for 7 days. For every frame and face it holds 478
[x, y, z] points in MediaPipe Face Mesh order (x and y are fractions of the frame
width and height), 52 expression scores named in blendshape_names (such as jawOpen
and eyeBlinkLeft), and a 4x4 head-pose matrix. It’s about 30 KB per face per frame.
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’svideo_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
grayscalecolormap for this. It’s the one video models take as a depth reference. - Leave
side_by_sideoff for a reference clip: it adds the input video next to the depth map. - Turn on
face_meshwhen people talk or show expressions, so the video model keeps their lip and eye movement. - Use the URL right away or download the file, since it’s deleted after 24 hours.