BudgetPixel Stock Music API

openapi: 3.2.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).


    **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 Stock Music API
  version: '2026-06-20'
servers:
- description: Production
  url: https://api.budgetpixel.com/v1
security:
- ApiKeyAuth: []
tags:
- description: Search the free background music library — available on every plan, including Free
  name: Stock Music
paths:
  /stock/music:
    get:
      description: 'Search BudgetPixel''s free background music library (the tracks at

        budgetpixel.com/background-music):

        AI-generated instrumental beds for videos, podcasts, streams and apps — lofi,

        corporate, cinematic, acoustic, electronic and more, each listened to and scored

        before it is listed. Tracks are instrumental, up to about a minute long, mostly

        WAV. Search only — nothing is generated when a query comes up empty. To make a

        track to order (a set length, lyrics, a soundtrack for a video), use the music

        generation endpoints (paid plans).


        **Plans.** Available on **every plan, including Free**. The stock searches

        (images, sound effects, music) are the only endpoints a Free plan''s API key can

        call.


        **Pricing.** **10 credits per search**, charged when the search succeeds,

        including a search that matches nothing. Invalid parameters are refused with a

        `400` and cost nothing. `POST /v1/cost` with `{"model": "stock-music-search"}`

        quotes the price (on paid plans).


        **Licence.** Every track is licensed

        CC BY 4.0: commercial use, editing

        and client work are allowed with credit. Each result carries a ready-made credit

        line (`attribution.text`, or `attribution.html` for web pages) that meets the

        licence. Put it in the video description, credits or page where the audio is used.


        **How the search matches.** Name the sound in a few plain words. Every word

        counts: a result must carry most of what you asked for, rare words weigh more

        than common ones, and a word the library does not have counts as a miss. Word

        forms are matched (`ticking` finds `tick`). Results that match more of your

        words come first, then the more popular. A long description returns the items

        it names, or nothing; it does not return items that only share its adjectives.


        Besides the standard `/v1` limits, sound-effect and music searches together are

        capped at **60 per minute per account**.'
      operationId: searchStockMusic
      parameters:
      - description: The genre, mood or use, in a few plain words, e.g. `lofi study`, `upbeat corporate`, `dark true crime documentary`. Up to 200 characters. Omit to browse.
        in: query
        name: query
        schema:
          maxLength: 200
          type: string
      - description: Shortest track to return, in seconds.
        in: query
        name: min_duration
        schema:
          exclusiveMinimum: 0
          maximum: 600
          type: number
      - description: Longest track to return, in seconds.
        in: query
        name: max_duration
        schema:
          exclusiveMinimum: 0
          maximum: 600
          type: number
      - description: '`popular` (default — with a query, best matches first), `newest`, or `top` (highest rated).'
        in: query
        name: sort
        schema:
          default: popular
          enum:
          - popular
          - newest
          - top
          type: string
      - in: query
        name: limit
        schema:
          default: 20
          maximum: 20
          minimum: 1
          type: integer
      - description: Results to skip. The next page is `offset + limit`; each page is a new search.
        in: query
        name: offset
        schema:
          default: 0
          maximum: 5000
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockAudioList'
          description: Matching tracks.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Insufficient credits for a search (10 credits).
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Search free stock music
      tags:
      - Stock Music
components:
  schemas:
    QueueFull:
      description: '`429` body when your account already has as many jobs of this kind

        (image, video or audio) in flight as its concurrency cap allows. Submit

        the next job when one of your running jobs finishes.

        '
      properties:
        active_jobs:
          description: Jobs of this kind in flight right now.
          type: integer
        code:
          enum:
          - queue_full
          type: string
        error:
          description: Human-readable message.
          type: string
        queue_full:
          enum:
          - true
          type: boolean
        queue_limit:
          description: Your concurrency cap for this kind of job.
          type: integer
        retry_after_seconds:
          description: Same value as the `Retry-After` header.
          type: integer
      required:
      - error
      - code
      - queue_full
      - queue_limit
      - active_jobs
      - retry_after_seconds
      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
    ModerationBlocked:
      description: Returned (with HTTP 400) when the input content moderation gate blocks a generation request. The block is a property of the request's prompt or input media — reword the prompt or change the input and retry. Branch on `restriction_reason`, which is stable and machine-readable.
      properties:
        error:
          description: Human-readable explanation of the block.
          type: string
        restriction_reason:
          description: Stable machine-readable block reason.
          enum:
          - input_csam
          - input_explicit_adult
          - input_upload_nudity
          - input_celebrity_likeness
          - strict_model_nsfw
          type: string
      required:
      - error
      - restriction_reason
      type: object
    StockAudio:
      description: One sound effect or music track from the free audio library.
      properties:
        ai_generated:
          example: true
          type: boolean
        attribution:
          description: The credit line the licence requires wherever the audio is used.
          properties:
            html:
              description: The same credit as HTML links, for web pages.
              type: string
            required:
              example: true
              type: boolean
            text:
              example: “Heavy Rain Thunder” by BudgetPixel AI (https://budgetpixel.com/sfx/heavy-rain-thunder-3d04cdea) — CC BY 4.0
              type: string
          type: object
        category:
          description: A sound effect's category; `music` for every track.
          type: string
        channels:
          example: 2
          type: integer
        created_at:
          format: date-time
          type: string
        downloads:
          type: integer
        duration_seconds:
          example: 6.037
          type: number
        format:
          description: The file format of `urls.original`.
          enum:
          - wav
          - mp3
          type: string
        id:
          format: uuid
          type: string
        keywords:
          description: Everyday phrases people search it by.
          items:
            type: string
          type: array
        license:
          properties:
            code:
              example: CC-BY-4.0
              type: string
            name:
              example: CC BY 4.0
              type: string
            url:
              example: https://creativecommons.org/licenses/by/4.0/
              type: string
          type: object
        model:
          description: The model that generated the audio.
          type: string
        page_url:
          description: The item's page on budgetpixel.com — the link its credit line points to.
          example: https://budgetpixel.com/sfx/heavy-rain-thunder-3d04cdea
          type: string
        prompt:
          description: The prompt the audio was generated from.
          type: string
        quality_score:
          description: Review score out of 10.
          type:
          - number
          - 'null'
        sample_rate:
          example: 44100
          type: integer
        size_bytes:
          type: integer
        tags:
          description: How it sounds.
          items:
            type: string
          type: array
        title:
          example: Heavy Rain Thunder
          type: string
        type:
          enum:
          - sound_effect
          - music
          type: string
        urls:
          properties:
            cover:
              description: Square cover art, when the item has one.
              type: string
            original:
              description: The audio file.
              type: string
          type: object
      type: object
    StockAudioList:
      properties:
        credits_charged:
          example: 10
          type: integer
        data:
          items:
            $ref: '#/components/schemas/StockAudio'
          type: array
        has_more:
          description: More results exist past this page.
          type: boolean
        limit:
          type: integer
        object:
          enum:
          - list
          type: string
        offset:
          type: integer
        total:
          description: Total matching items.
          type: integer
      required:
      - object
      - data
      - total
      - limit
      - offset
      - has_more
      - credits_charged
      type: object
  responses:
    TooManyRequests:
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/QueueFull'
      description: 'A limit was reached. Every `429` carries `Retry-After` (seconds). The

        per-minute rate limit, the upload limit and the hourly API post cap answer

        with the `Error` envelope, code `rate_limited`. The monthly spend limit answers with

        code `monthly_spend_limit_reached`, and its `Retry-After` counts down to the

        start of next month (raising the limit in the console clears it sooner).

        A full concurrency queue answers with the flat `QueueFull` body (3D jobs:

        the `Error` envelope with code `queue_full`); its `Retry-After` is a

        suggested wait, because a slot frees as soon as one of your running jobs

        finishes.

        '
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            minimum: 1
            type: integer
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or invalid API key.
    BadRequest:
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Error'
            - $ref: '#/components/schemas/ModerationBlocked'
      description: The request was malformed, referenced an unavailable model, or was blocked by input content moderation (moderation blocks carry a `restriction_reason` — see ModerationBlocked).
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: bpx_live_*
      description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx'
      scheme: bearer
      type: http