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

# Upload input media

> Upload an image, video, or audio file to use as input for a generation (e.g. the
`image` param on an image-to-image or image-to-video request). Returns a
short-lived `url` you pass as that media parameter.

Files are ephemeral — stored privately and deleted ~24h after upload. Max 50 MB.

You don't have to upload first: any media param also accepts a public image URL, a
data URI, or raw base64 directly. Uploading is the convenient path when you have a
local file and no public URL to point at.


## OpenAPI

````yaml /openapi.yaml post /uploads
openapi: 3.1.0
info:
  contact:
    email: support@budgetpixel.com
    name: BudgetPixel Support
  description: >
    The BudgetPixel developer API for programmatic image and video 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 currently available on the **Ultra** plan.


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

    (see `GET /v1/models`). Consumer subscription perks (free daily generations,

    free-for-Ultra models, subscription discounts) do not apply to API traffic.
  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 job status
    name: Audios
  - description: Music generation models
    name: Music
  - description: Format conversion for images, video, and audio
    name: Conversions
  - description: Publish posts to your BudgetPixel feed
    name: Social
  - description: Content moderation — NSFW rating and CSAM detection
    name: Moderation
  - description: Content classification — music genre detection
    name: Classification
paths:
  /uploads:
    post:
      tags:
        - Uploads
      summary: Upload input media
      description: >
        Upload an image, video, or audio file to use as input for a generation
        (e.g. the

        `image` param on an image-to-image or image-to-video request). Returns a

        short-lived `url` you pass as that media parameter.


        Files are ephemeral — stored privately and deleted ~24h after upload.
        Max 50 MB.


        You don't have to upload first: any media param also accepts a public
        image URL, a

        data URI, or raw base64 directly. Uploading is the convenient path when
        you have a

        local file and no public URL to point at.
      operationId: uploadMedia
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  description: >-
                    The media file. Image (PNG/JPEG/WebP/GIF), video (MP4/WebM),
                    or audio (MP3/WAV/OGG).
                  format: binary
                  type: string
              required:
                - file
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
          description: Stored. Pass `url` as a media param on a generation request.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: File exceeds the size limit.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsupported file type.
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    UploadResponse:
      description: >-
        A stored, ephemeral input file. Pass `url` as a media parameter on a
        generation request.
      properties:
        bytes:
          description: Stored file size in bytes.
          type: integer
        content_type:
          example: image/png
          type: string
        expires_in:
          description: Seconds the file is retained (~86400).
          type: integer
        url:
          description: Short-lived URL to use as a media input (valid ~24h).
          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:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: The request was malformed or referenced an unavailable model.
    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, restriction).
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate or queue limit reached. Retry after a short delay.
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: bpx_live_*
      description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx'
      scheme: bearer
      type: http

````