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

# Upload Media File

> Upload a single media file via `multipart/form-data` (field name: `file`). Returns a `file_id` and `url` you can pass into prediction APIs. See [How to Use](/file-api/how-to-use) for limits, supported formats, and the full workflow.



## OpenAPI

````yaml /file-api/media-files.json post /api/v1/media/files
openapi: 3.1.0
info:
  title: Media Files API
  description: >-
    Upload, list, and delete media files for use with Modellix prediction APIs.
    Authenticate with an API Key. This API is not billed. Uploaded files are
    retained for a limited time (default 7 days).
  version: 1.0.0
  contact:
    name: Modellix API Support
    email: support@modellix.ai
servers:
  - url: https://api.modellix.ai/
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/v1/media/files:
    post:
      summary: Upload Media File
      description: >-
        Upload a single media file via `multipart/form-data` (field name:
        `file`). Returns a `file_id` and `url` you can pass into prediction
        APIs. See [How to Use](/file-api/how-to-use) for limits, supported
        formats, and the full workflow.
      operationId: uploadMediaFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Media file to upload
      responses:
        '200':
          description: Upload succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadMediaResponse'
              examples:
                success:
                  summary: Uploaded image
                  value:
                    code: 0
                    message: success
                    data:
                      file_id: 550e8400-e29b-41d4-a716-446655440000
                      type: image
                      url: >-
                        https://file.modellix.ai/example/550e8400-e29b-41d4-a716-446655440000.png
                      filename: image.png
                      size: 102400
                      created_at: 1784084400000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UploadMediaResponse:
      type: object
      required:
        - code
        - message
        - data
      properties:
        code:
          type: integer
          description: Response code, 0 indicates success
          example: 0
        message:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/UploadMediaData'
    UploadMediaData:
      type: object
      required:
        - file_id
        - type
        - url
        - filename
        - size
        - created_at
      properties:
        file_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          $ref: '#/components/schemas/MediaType'
        url:
          type: string
          format: uri
          example: >-
            https://file.modellix.ai/example/550e8400-e29b-41d4-a716-446655440000.png
        filename:
          type: string
          example: image.png
        size:
          type: integer
          format: int64
          example: 102400
        created_at:
          type: integer
          format: int64
          description: Upload time as Unix timestamp in milliseconds
          example: 1784084400000
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: Error code (matches HTTP status)
          example: 400
        message:
          type: string
          description: 'Error message in the form Category: detail'
          example: 'Invalid format: unsupported file format'
    MediaType:
      type: string
      enum:
        - image
        - video
        - audio
      description: 'Media category: image, video, or audio'
  responses:
    BadRequest:
      description: Bad request — missing file, unsupported format, or invalid file content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_file:
              value:
                code: 400
                message: 'Missing required parameter: file is required'
            unsupported_format:
              value:
                code: 400
                message: 'Invalid format: unsupported file format'
    Unauthorized:
      description: Unauthorized — Invalid or missing API Key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: 'Authentication failed: invalid API key'
    PayloadTooLarge:
      description: File exceeds the maximum allowed size
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 413
            message: 'Value out of range: file too large'
    QuotaExceeded:
      description: Team upload quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 429
            message: 'Rate limit exceeded: upload quota exceeded'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 500
            message: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API Key authentication. Format: Bearer YOUR_API_KEY'

````