BudgetPixel Uploads API

openapi: 3.2.0
info:
  title: Budgetpixel Uploads API
  version: '2026-06-20'
  contact:
    email: support@budgetpixel.com
    name: BudgetPixel Support
  description: 'Operations tagged Uploads across 2 of this provider''s published API definitions: budgetpixel-openapi.yaml, budgetpixel-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: Production
  url: https://api.budgetpixel.com/v1
security:
- ApiKeyAuth: []
tags:
- description: Upload input media for image/video generation
  name: Uploads
paths:
  /uploads:
    post:
      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.


        **Rate limit.** This endpoint is free (not metered), so it carries a dedicated cap

        of **60 uploads/min per account** (a rolling window), on top of the global per-key

        and per-IP request limits. Exceeding it returns `429` with a `Retry-After` header.

        '
      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'
      summary: Upload input media
      tags:
      - Uploads
    servers:
    - description: Production
      url: https://api.budgetpixel.com/v1
components:
  responses:
    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.
    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).
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate or queue limit reached. Retry after a short delay.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or invalid API key.
  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
    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
    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
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: bpx_live_*
      description: 'API key as a bearer token: Authorization: Bearer bpx_live_xxx'
      scheme: bearer
      type: http
x-refined-from:
- budgetpixel-openapi.yaml
- budgetpixel-openapi.yaml