> ## 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.

# Get depth map job status

> Poll until `status` is `succeeded`. The depth video is returned as a
short-lived signed `video_url` (valid for several hours; re-call for a fresh
URL anytime — the underlying object is deleted 24h after generation).

The depth video is an H.264 MP4 at the input's frame size (up to 1080p,
or the `resolution` you asked for) and frame rate (up to 30 fps). In
grayscale, near is white and far is black.

With `face_mesh` or `include_face_landmarks`, the response adds
`face_mesh` (how much of the clip had a face, and each face's frames)
and, with `include_face_landmarks`, a signed `face_landmarks_url`.




## OpenAPI

````yaml /openapi.yaml get /depth-maps/{id}
openapi: 3.1.0
info:
  contact:
    email: support@budgetpixel.com
    name: BudgetPixel Support
  description: >
    The BudgetPixel developer API for programmatic image, video, music and

    sound-effect generation.


    Generation is **asynchronous**: you create a job, then poll its status until
    it

    reaches a terminal state (`succeeded` / `failed`). You are charged in
    credits

    only on success — never for failures, timeouts, or content blocked before

    generation.


    **Authentication.** All requests require an API key sent as a bearer token:

        Authorization: Bearer bpx_live_xxx

    Create and manage keys from your BudgetPixel account dashboard. The
    developer

    API is available on **every paid plan**. On the **Free** plan, API keys can
    call

    the free library searches only: `GET /v1/stock/images`,

    `GET /v1/stock/sound-effects` and `GET /v1/stock/music`.


    **Pricing.** API usage is metered in credits at each model's published price

    (see `GET /v1/models`), and your plan's model discounts and active
    promotions

    apply to API charges exactly as they do on the web — `POST /v1/cost` quotes

    your discounted price. Pro and Ultra plans include a daily free-models

    allowance (a shared pool of free generations per day across qualified image

    models such as FLUX 2 Klein and Qwen-Image) that covers API

    requests too — the standard price applies once the day's pool is used.

    Other promotional free daily generations remain web/app-only. Failed

    generations are never charged.


    **Rate limits.** Requests are limited per minute: **600 requests/min per API

    key** and **1200 requests/min per source IP** (defaults; subject to tuning).

    Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset` (seconds until the window resets). Exceeding a limit

    returns HTTP `429` with a `Retry-After` header — wait that long before

    retrying. Rejected requests still count against the window, so a tight retry

    loop keeps you limited; back off instead. Generation jobs additionally have
    a

    per-plan concurrency cap (the same one as the web workshop), independent of

    these request limits. `POST /v1/uploads` also has a dedicated **60
    uploads/min

    per account** cap (it's free/unmetered) on top of these limits. Every `429`

    this API returns carries `Retry-After`, including a full concurrency queue

    (a suggested wait) and the monthly spend limit (seconds until the month

    resets).


    **Characters.** Write `@handle` in the prompt of an image or video
    generation to cast a

    character: one of the free BudgetPixel AI influencers (`@barry`, `@rosa`,
    ...) or a character

    of your own. Its picture and look go with the mention, so the same face
    appears in every

    post. `GET /v1/characters` lists the ones you can cast, `GET
    /v1/characters/{handle}` gives

    one in full with every picture, and `POST /v1/characters/recommend` picks
    influencers for a

    brief.


    **Wardrobe.** Dress a character by writing an outfit's `@handle` next to
    theirs:

    `@barry wearing @camel_belted_overcoat_outfit`. The outfit's picture goes
    with the mention and

    the character wears it in place of their own clothes. `GET /v1/wardrobe`
    lists the outfits you

    can use (your own, the ones you saved and the free library) and `GET
    /v1/wardrobe/{handle}`

    gives one in full.


    **Output retention.** Generated files are kept for 24 hours after the job is

    created. Job status responses give the exact time as `expires_at`; after it,

    `expired` is `true` and no download URLs are returned.
  title: BudgetPixel API
  version: '2026-06-20'
servers:
  - description: Production
    url: https://api.budgetpixel.com/v1
security:
  - ApiKeyAuth: []
tags:
  - description: Account and credit balance
    name: Account
  - description: Discover available models and pricing
    name: Models
  - description: Upload input media for image/video generation
    name: Uploads
  - description: Image job status
    name: Images
  - description: FLUX image models
    name: Black Forest Labs
  - description: SeeDream image models
    name: Bytedance
  - description: Video job status
    name: Videos
  - description: Kuaishou Kling video models
    name: Kling
  - description: SeeDance video models
    name: ByteDance (SeeDance)
  - description: Music and sound-effect job status
    name: Audios
  - description: Music generation models
    name: Music
  - description: Text-to-sound-effect models (priced per second)
    name: Sound Effects
  - description: >-
      Image-to-3D models — a picture in, a textured 3D model (GLB, plus
      FBX/USDZ/STL on Meshy) out
    name: 3D Models
  - description: Format conversion for images, video, and audio
    name: Conversions
  - description: Publish posts to your BudgetPixel feed and enter clan themes
    name: Social
  - description: Cast BudgetPixel AI influencers and your own characters with @mentions
    name: Characters
  - description: >-
      Outfits your characters can wear, called with an @mention next to the
      character
    name: Wardrobe
  - description: >-
      Body poses on two faceless mannequins (woman and man), called with an
      @mention next to the character
    name: Poses
  - description: Content moderation — NSFW rating and CSAM detection
    name: Moderation
  - description: Content classification — music genre detection
    name: Classification
  - description: >-
      Search the free stock image library — available on every plan, including
      Free
    name: Stock Images
  - description: >-
      Search the free sound effect library — available on every plan, including
      Free
    name: Stock Sound Effects
  - description: >-
      Search the free background music library — available on every plan,
      including Free
    name: Stock Music
  - description: >-
      Turn a video into a depth map video to guide other video models with its
      structure and motion
    name: Depth Maps
paths:
  /depth-maps/{id}:
    get:
      tags:
        - Depth Maps
      summary: Get depth map job status
      description: >
        Poll until `status` is `succeeded`. The depth video is returned as a

        short-lived signed `video_url` (valid for several hours; re-call for a
        fresh

        URL anytime — the underlying object is deleted 24h after generation).


        The depth video is an H.264 MP4 at the input's frame size (up to 1080p,

        or the `resolution` you asked for) and frame rate (up to 30 fps). In

        grayscale, near is white and far is black.


        With `face_mesh` or `include_face_landmarks`, the response adds

        `face_mesh` (how much of the clip had a face, and each face's frames)

        and, with `include_face_landmarks`, a signed `face_landmarks_url`.
      operationId: getDepthMapJob
      parameters:
        - description: The opaque job id returned by the create endpoint.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepthMapJob'
          description: Current job status. `video_url` is populated once succeeded.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DepthMapJob:
      allOf:
        - $ref: '#/components/schemas/MotionJob'
        - properties:
            face_landmarks_url:
              description: >
                With `include_face_landmarks`, once `status=succeeded`: a
                short-lived signed URL to a JSON

                file (`format: budgetpixel-face-landmarks/1`) with, per frame
                and per face, 478 `[x, y, z]`

                landmarks (x and y as fractions of the frame), 52 blendshape
                scores (names in

                `blendshape_names`) and a 4x4 head-pose `matrix`. Kept 7 days.
              format: uri
              type: string
            face_mesh:
              description: >-
                Present when the job asked for `face_mesh` or
                `include_face_landmarks`, once the worker has run.
              properties:
                coverage:
                  description: >-
                    Share of frames with at least one face, 0 to 1. 0 means no
                    face was found, so nothing was drawn.
                  type: number
                drawn:
                  description: 'Whether the mesh was drawn on the video (`face_mesh: true`).'
                  type: boolean
                faces:
                  description: One entry per tracked face.
                  items:
                    properties:
                      first_frame:
                        type: integer
                      frames:
                        description: Frames this face has a mesh in
                        including bridged gaps.: null
                        type: integer
                      id:
                        type: integer
                      interpolated_frames:
                        description: >-
                          Frames filled in across a short gap in tracking (up to
                          0.3 s).
                        type: integer
                      last_frame:
                        type: integer
                    type: object
                  type: array
                frames:
                  description: Frames in the output.
                  type: integer
                frames_with_face:
                  type: integer
              type: object
          type: object
    MotionJob:
      properties:
        completed_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        error_message:
          type: string
        id:
          type: string
        model:
          type: string
        status:
          description: Lifecycle state. `succeeded`/`failed`/`canceled` are terminal.
          enum:
            - pending
            - processing
            - succeeded
            - failed
            - canceled
          type: string
        video_codec:
          description: >-
            Codec of the MP4 at `video_url`; present once `status=succeeded`.
            Video upscales are `h265` (HEVC, 10-bit); motion-control outputs are
            `h264`.
          enum:
            - h264
            - h265
          type: string
        video_codec_note:
          description: >-
            Present only when `video_codec` is `h265` — a short explanation of
            where H.265 plays and what to do when it does not.
          type: string
        video_url:
          description: Short-lived presigned URL; present once `status=succeeded`.
          format: uri
          type: string
      type: object
    Error:
      properties:
        error:
          properties:
            code:
              description: Stable machine-readable code.
              example: model_not_available
              type: string
            message:
              type: string
            type:
              description: Error category.
              example: invalid_request_error
              type: string
          required:
            - type
            - code
            - message
          type: object
      required:
        - error
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or invalid API key.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        Authenticated but not permitted (plan gate, ownership, account
        restriction). Content-moderation blocks are 400, not 403.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: The requested job was not found.
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: bpx_live_*
      description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx'
      scheme: bearer
      type: http

````

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