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

# Upload File from Base64

> Upload files to Vidgo API using Base64-encoded data or Data URL format

## Usage Guide

* This endpoint accepts Base64-encoded file data for upload to Vidgo API storage
* Supports both Data URL format (with MIME type prefix) and pure Base64 strings
* Ideal for uploading files that are already Base64-encoded in your application, such as canvas drawings or client-side image manipulations
* Files are immediately accessible via the returned URL and remain available for 72 hours

## Parameter Details

* **Base64 Data Format**:

  * **Data URL format**: `data:image/png;base64,iVBORw0KGgo...` (recommended)

  * **Pure Base64 string**: `iVBORw0KGgo...` (without MIME type prefix)

  * The Base64 string must not contain any whitespace, newline characters, or formatting

  * Supported file formats: **JPEG, PNG, GIF, WebP** only

  * Maximum upload limit: **1 image per request**

* **Storage Configuration**:

  * All files are automatically stored with a `temp/` prefix in the storage path

  * If you specify `upload_path: "profile-images"`, the actual path will be `temp/profile-images`

  * Files will expire and be automatically deleted **72 hours** after upload

* **File Naming**:

  * If `file_name` is not provided, the system generates a unique name in the format: `{timestamp}_{random}_{extension}`

  * Example auto-generated name: `20251229130857_a8B9cD2e.png`

## Developer Notes

* When to use Base64 upload:

  * Client-side generated images (canvas, screenshots)

  * Images already encoded in Base64 format in your application

  * Small to medium-sized images where encoding overhead is acceptable

* When NOT to use Base64 upload:

  * Large image files (Base64 encoding increases size by \~33%)

  * Files stored on disk (use stream upload instead)

  * Files available via URL (use URL upload instead)

* Ensure your Base64 data is properly formatted without any line breaks or spaces

* For persistent storage needs, download and save the file locally before the 72-hour expiration

## Rate Limits and Quotas

* **Rate Limit**: 5 requests per minute per API key

* When the rate limit is exceeded, you will receive a `429 Too Many Requests` error

* Implement exponential backoff retry logic for handling rate limit errors

## Common Error Scenarios

* **Invalid Base64 Encoding**: The provided Base64 string cannot be decoded

* **Invalid Data URL Format**: The Data URL format is malformed (e.g., missing `data:` prefix or `;base64,` separator)

* **Unsupported File Type**: The decoded file is not in a supported image format (JPEG, PNG, GIF, WebP)

* **Invalid File Data**: The decoded data is empty or corrupted

* **Authentication Error**: Missing or invalid API key in the Authorization header


## OpenAPI

````yaml /api-manual/file-series/upload-base64.json POST /api/common/upload/base64
openapi: 3.0.0
info:
  title: Vidgo API - Upload File from Base64
  description: Upload files to Vidgo API using Base64-encoded data or Data URL format
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/common/upload/base64:
    post:
      tags:
        - File Upload
      summary: Upload File from Base64
      description: >-
        Upload files using Base64-encoded data or Data URL format. Supports both
        pure Base64 strings and Data URL format with MIME type prefix.
      operationId: uploadFileFromBase64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadBase64Request'
            examples:
              data-url-format:
                summary: Data URL Format
                value:
                  base64_data: >-
                    data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
              pure-base64:
                summary: Pure Base64 String
                value:
                  base64_data: >-
                    iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
              custom-naming:
                summary: Upload with Custom Path and Name
                value:
                  base64_data: >-
                    data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAA8=
                  upload_path: profile-images
                  file_name: user-avatar.jpg
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          description: Bad request - Invalid Base64, unsupported file type, or invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-base64:
                  summary: Invalid Base64 Encoding
                  value:
                    detail: Invalid Base64 encoding
                invalid-data-url:
                  summary: Invalid Data URL Format
                  value:
                    detail: Invalid data URL format
                unsupported-type:
                  summary: Unsupported File Type
                  value:
                    detail: 'Unsupported file type: image/svg+xml'
                invalid-file-data:
                  summary: Invalid File Data
                  value:
                    detail: Invalid file data
        '401':
          description: Unauthorized - Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not-authenticated:
                  summary: Not Authenticated
                  value:
                    detail: Not authenticated
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate-limit:
                  summary: Rate Limit Exceeded
                  value:
                    detail: Rate limit exceeded
        '500':
          description: Server error - Storage connection or upload failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                server-error:
                  summary: Server Error
                  value:
                    detail: 'Upload failed: S3 connection error'
components:
  schemas:
    UploadBase64Request:
      type: object
      required:
        - base64_data
      properties:
        base64_data:
          type: string
          description: >-
            Base64-encoded file data.


            Supports two formats:


            1. **Data URL format**: `data:image/png;base64,iVBORw0KGgo...`


            2. **Pure Base64 string**: `iVBORw0KGgo...` (without MIME type
            prefix)


            **Supported formats**: JPEG, PNG, GIF, WebP


            **Note**: The Base64 string should not include any whitespace or
            newline characters.
          example: >-
            data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
        upload_path:
          type: string
          description: >-
            Custom storage directory path.


            If not specified, the system will auto-categorize the file.


            **Note**: All files are stored with a `temp/` prefix regardless of
            the specified path.
          example: profile-images
        file_name:
          type: string
          description: >-
            Custom filename for the uploaded file.


            If not specified, the system will generate a unique filename in the
            format: `{timestamp}_{random}_{extension}`


            **Example auto-generated name**: `20251229130857_a8B9cD2e.png`
          example: user-avatar.png
    UploadResponse:
      type: object
      required:
        - success
        - code
        - msg
        - data
      properties:
        success:
          type: boolean
          example: true
          description: Indicates whether the upload was successful
        code:
          type: integer
          example: 200
          description: HTTP status code
        msg:
          type: string
          example: File uploaded successfully
          description: Response message
        data:
          type: object
          required:
            - file_id
            - file_name
            - original_name
            - file_size
            - mime_type
            - upload_path
            - file_url
            - download_url
            - upload_time
            - expires_at
          properties:
            file_id:
              type: string
              example: da2611c99d3ce825bc9a5409378db8e4
              description: Unique file identifier (MD5 hash)
            file_name:
              type: string
              example: test-base64.png
              description: The stored filename
            original_name:
              type: string
              example: test-base64.png
              description: The original filename
            file_size:
              type: integer
              example: 3242
              description: File size in bytes
            mime_type:
              type: string
              example: image/png
              description: MIME type of the uploaded file
            upload_path:
              type: string
              example: temp/test-base64
              description: Storage path (includes temp/ prefix)
            file_url:
              type: string
              format: uri
              example: https://storage.vidgo.ai/temp/test-base64/test-base64.png
              description: Direct access URL for the uploaded file
            download_url:
              type: string
              format: uri
              example: https://storage.vidgo.ai/temp/test-base64/test-base64.png
              description: Download URL (same as file_url)
            upload_time:
              type: string
              format: date-time
              example: '2025-12-29T13:09:01.233635'
              description: Upload timestamp in ISO 8601 format
            expires_at:
              type: string
              format: date-time
              example: '2026-01-01T13:09:01.233635'
              description: Expiration timestamp in ISO 8601 format (72 hours after upload)
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Not authenticated
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication


        Get your API Key:


        Visit the [API Key Management
        Page](https://vidgo.ai/apis/dashboard/api-key) to get your API Key


        Add it to the request header:


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````