---
title: "Upload a file"
url: "https://docs.api.pruna.ai/apis/models-api-0/versions/7dfbc266-0f94-4c90-8518-d9e4d1a245ec/operations/uploadFile"
---

> Full API specification: https://docs.api.pruna.ai/apis/models-api-0/versions/7dfbc266-0f94-4c90-8518-d9e4d1a245ec.md

# Upload a file

`POST` `/v1/files`

Operation ID: `uploadFile`

Upload a file (image or video) to be used as input for predictions. The uploaded file will be stored temporarily and can be referenced in prediction requests by its URL. Uploaded files are available for 30 minutes after upload and are automatically deleted after expiration. Use the returned URL in your prediction input fields that accept file URLs. **Rate limit:** 10000 requests per minute **Example with curl:** ```bash curl -X POST "https://api.pruna.ai/v1/files" \ -H "apikey: YOUR_API_KEY" \ -F "content=@/path/to/your/file.jpg" ``` Note: Use `-F` (form) with `@` prefix to upload a file from your local filesystem.

## Request body (required)

Content types: `multipart/form-data`

## Responses

- `201` - File uploaded successfully
- `400` - Invalid file or missing content
- `401` - Authentication failed
- `413` - File too large
- `429` - Rate limit exceeded
- `500` - Internal server error

## OpenAPI definition

````yaml
openapi: 3.0.3
info:
  title: P-API
  version: 0.3.0
servers:
  - url: https://api.pruna.ai
    description: Production server
paths:
  /v1/files:
    post:
      summary: Upload a file
      description: >
        Upload a file (image or video) to be used as input for predictions.

        The uploaded file will be stored temporarily and can be referenced in
        prediction

        requests by its URL.


        Uploaded files are available for 30 minutes after upload

        and are automatically deleted after expiration. Use the returned URL in

        your prediction input fields that accept file URLs.


        **Rate limit:** 10000 requests per minute


        **Example with curl:**

        ```bash

        curl -X POST "https://api.pruna.ai/v1/files" \
          -H "apikey: YOUR_API_KEY" \
          -F "content=@/path/to/your/file.jpg"
        ```


        Note: Use `-F` (form) with `@` prefix to upload a file from your local
        filesystem.
      operationId: uploadFile
      tags:
        - File Management
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl -X POST "https://api.pruna.ai/v1/files" \
              -H "apikey: YOUR_API_KEY" \
              -F "content=@/path/to/your/file.jpg"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  format: binary
                  description: The file to upload (image or video)
      responses:
        "201":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileUploadResponse"
              example:
                id: fqadqq42xq
                name: test.jpg
                content_type: image/jpeg
                size: 185093
                etag: '"14e9a51deaac6bee2dd8b5c52d7d0b5f"'
                checksums:
                  sha256: aa10d5d09bcee5cb5d854bd81899308b0cf0c0c50e29d4f00c2c06e51f0e2fe6
                metadata:
                  content_length: 185093
                  width: 1344
                  height: 768
                created_at: 2025-01-08T18:51:26.729Z
                expires_at: 2025-01-09T18:51:26.729Z
                urls:
                  get: https://api.pruna.ai/v1/files/fqadqq42xq
        "400":
          description: Invalid file or missing content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: INVALID_FILE
                  message: The uploaded file is invalid or missing
                  details: Please provide a valid image or video file
        "401":
          $ref: "#/components/responses/Unauthorized"
        "413":
          description: File too large
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: FILE_TOO_LARGE
                  message: The uploaded file exceeds the maximum size limit
                  details: Maximum file size is 100MB
        "429":
          $ref: "#/components/responses/RateLimitExceeded"
        "500":
          $ref: "#/components/responses/InternalServerError"
security:
  - ApiKeyAuth: []
components:
  schemas:
    FileUploadResponse:
      type: object
      required:
        - id
        - name
        - content_type
        - size
        - created_at
        - expires_at
        - urls
      properties:
        id:
          type: string
          description: Unique identifier for the uploaded file
          example: fqadqq42xq
        name:
          type: string
          description: Original filename
          example: test.jpg
        content_type:
          type: string
          description: MIME type of the uploaded file
          example: image/jpeg
        size:
          type: integer
          description: File size in bytes
          example: 185093
        etag:
          type: string
          description: Entity tag for cache validation
          example: '"14e9a51deaac6bee2dd8b5c52d7d0b5f"'
        checksums:
          type: object
          description: File integrity checksums
          properties:
            sha256:
              type: string
              description: SHA-256 hash of the file content
              example: aa10d5d09bcee5cb5d854bd81899308b0cf0c0c50e29d4f00c2c06e51f0e2fe6
        metadata:
          type: object
          description: Additional file metadata (varies by file type)
          properties:
            content_length:
              type: integer
              description: Content length in bytes
              example: 185093
            width:
              type: integer
              description: Image width in pixels (for images only)
              example: 1344
            height:
              type: integer
              description: Image height in pixels (for images only)
              example: 768
        created_at:
          type: string
          format: date-time
          description: Timestamp when the file was uploaded
          example: 2025-01-08T18:51:26.729Z
        expires_at:
          type: string
          format: date-time
          description: Timestamp when the file will expire and be deleted
          example: 2025-01-09T18:51:26.729Z
        urls:
          type: object
          description: URLs to access the uploaded file
          required:
            - get
          properties:
            get:
              type: string
              format: uri
              description: URL to retrieve the file. Use this URL in prediction input fields
                that accept file URLs.
              example: https://api.pruna.ai/v1/files/fqadqq42xq
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: string
              description: Additional error context
        request_id:
          type: string
          description: Unique request identifier for debugging
          example: req_1234567890
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: AUTHENTICATION_FAILED
              message: Invalid or missing API key
              details: Include your API key in the 'apikey' header
            request_id: req_1234567890
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: Too many requests
              details: You have exceeded the rate limit for this endpoint. Please wait before
                making additional requests.
            request_id: req_1234567890
      headers:
        RateLimit-Limit:
          description: Allowed limit in the timeframe
          schema:
            type: string
          example: "10000"
        RateLimit-Remaining:
          description: Number of available requests remaining
          schema:
            type: string
          example: "0"
        RateLimit-Reset:
          description: The time remaining, in seconds, until the rate limit quota is reset
          schema:
            type: string
          example: "42"
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
              details: Please try again later or contact support if the problem persists
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: |
        API key for authentication. You can obtain your API key from the
        Pruna AI dashboard.

        Include it in the `apikey` header for all requests.
````