> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a file

> Upload a file (multipart/form-data) and get back a `file_<id>`. The id can be passed as the `image`/`video`/`reference_images` source on POST /v3/videos. `purpose` defaults to `reference_media` (accepts common image/video types). The MIME type is detected from the bytes; size and per-org quota are enforced. Files expire after a default TTL, capped by the project's retention.

Returns a `file_<id>` you can pass as a media source on later calls. See the [Files guide](/build/multimodal/files).


## OpenAPI

````yaml post /v3/files
openapi: 3.1.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task API
  version: 3.0.0
servers:
  - description: Production
    url: https://api.opper.ai
  - description: Local development
    url: http://localhost:8080
security:
  - BearerAuth: []
tags:
  - description: Schema-driven function management and execution
    name: Functions
  - description: OpenAI-compatible chat completions
    name: Chat
  - description: OpenAI Responses API compatible endpoint
    name: Responses
  - description: Google-compatible interactions endpoint
    name: Interactions
  - description: Model registry and capabilities
    name: Models
  - description: Synchronous image generation
    name: Images
  - description: Text-to-speech and speech-to-text
    name: Audio
  - description: Asynchronous video generation
    name: Videos
  - description: Reusable file storage for media inputs and generated outputs
    name: Files
  - description: Async generation status and downloads
    name: Artifacts
  - description: OpenAI-compatible embeddings
    name: Embeddings
  - description: Recorded HTTP request/response generations
    name: Generations
  - description: System health and status
    name: System
  - description: Roundtable endpoint — fan out a query to multiple LLMs and combine results
    name: Roundtable
  - description: Web search, fetch, and other utility tools
    name: Tools
paths:
  /v3/files:
    post:
      tags:
        - Files
      summary: Upload a file
      description: >-
        Upload a file (multipart/form-data) and get back a `file_<id>`. The id
        can be passed as the `image`/`video`/`reference_images` source on POST
        /v3/videos. `purpose` defaults to `reference_media` (accepts common
        image/video types). The MIME type is detected from the bytes; size and
        per-org quota are enforced. Files expire after a default TTL, capped by
        the project's retention.
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  description: The file bytes.
                  format: binary
                  type: string
                filename:
                  description: >-
                    Optional advisory filename (defaults to the upload's
                    filename).
                  type: string
                purpose:
                  default: reference_media
                  description: Intended use; gates the accepted MIME types.
                  type: string
                ttl_seconds:
                  description: >-
                    Optional lifetime in seconds; may only shorten the
                    default/retention-capped TTL.
                  type: integer
              required:
                - file
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  bytes:
                    type: integer
                  created_at:
                    format: date-time
                    type: string
                  expires_at:
                    format: date-time
                    type: string
                  filename:
                    type: string
                  id:
                    description: file_… id
                    type: string
                  mime_type:
                    type: string
                  object:
                    example: file
                    type: string
                  purpose:
                    type: string
                  status:
                    type: string
                type: object
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
            - code
            - message
          type: object
        meta:
          type: object
      required:
        - error
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http

````