> ## 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 Stream

> Upload files to Vidgo API using multipart/form-data format for direct file uploads

## Usage Guide

* This endpoint enables direct file uploads using the standard `multipart/form-data` format
* Supports uploading files directly from local storage with automatic file type identification
* Best suited for local file uploads from desktop applications, mobile apps, or web forms
* Files are immediately accessible via the returned URL and remain available for 72 hours

## Parameter Details

* **File Upload Requirement**:

  * The `file` field must contain binary file data

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

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

  * The system automatically identifies the file type from the binary data

* **Parameter Naming Convention**:

  * This endpoint supports both **snake\_case** and **camelCase** naming conventions

  * `upload_path` or `uploadPath` - both are accepted

  * `file_name` or `fileName` - both are accepted

  * Use whichever convention matches your application's coding style

* **Storage Configuration**:

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

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

  * 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 file stream upload:

  * Direct file uploads from user's local storage

  * Form-based file uploads from web applications

  * Mobile app file uploads

  * Server-to-server file transfers

* This is the most efficient upload method for files already stored on disk

* The multipart/form-data format is standard across all programming languages and HTTP clients

* 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

* **Missing File**: No file was provided in the request body (422 error)

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

* **Empty File**: The uploaded file has zero bytes or is corrupted

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

## Example Usage

### cURL Example

```bash theme={null}
curl -X POST "https://api.vidgo.ai/api/common/upload/stream" \
  -H "Authorization: Bearer VIDGO_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "file_name=my-image.png"
```

### Python Example

```python theme={null}
import requests

url = "https://api.vidgo.ai/api/common/upload/stream"
headers = {"Authorization": "Bearer VIDGO_API_KEY"}

files = {"file": open("/path/to/image.png", "rb")}
data = {"file_name": "my-image.png"}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```

### JavaScript Example (Node.js)

```javascript theme={null}
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/image.png'));
form.append('file_name', 'my-image.png');

axios.post('https://api.vidgo.ai/api/common/upload/stream', form, {
  headers: {
    'Authorization': 'Bearer VIDGO_API_KEY',
    ...form.getHeaders()
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```


## OpenAPI

````yaml /api-manual/file-series/upload-stream.json POST /api/common/upload/stream
openapi: 3.0.0
info:
  title: Vidgo API - Upload File Stream
  description: >-
    Upload files to Vidgo API using multipart/form-data format for direct file
    uploads
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/common/upload/stream:
    post:
      tags:
        - File Upload
      summary: Upload File Stream
      description: >-
        Upload files using multipart/form-data format. Supports direct file
        uploads from local storage with automatic type identification.
      operationId: uploadFileStream
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadStreamRequest'
            examples:
              basic-upload:
                summary: Basic File Upload
                value:
                  file: (binary file data)
              custom-naming-snake-case:
                summary: Upload with Custom Path and Name (snake_case)
                value:
                  file: (binary file data)
                  upload_path: photos
                  file_name: vacation-photo.jpg
              custom-naming-camel-case:
                summary: Upload with Custom Path and Name (camelCase)
                value:
                  file: (binary file data)
                  uploadPath: documents
                  fileName: profile-image.png
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          description: Bad request - Unsupported file type or empty file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupported-type:
                  summary: Unsupported File Type
                  value:
                    detail: 'Unsupported file type: video/mp4'
                empty-file:
                  summary: Empty File
                  value:
                    detail: File is empty
        '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
        '422':
          description: Unprocessable Entity - Missing required file field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                missing-file:
                  summary: Missing File Field
                  value:
                    detail:
                      - loc:
                          - body
                          - file
                        msg: field required
                        type: value_error.missing
        '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: Failed to write file to storage'
components:
  schemas:
    UploadStreamRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: >-
            File binary data to upload.


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


            **Maximum**: 1 image per request


            **Note**: The system automatically identifies and categorizes file
            types.
        upload_path:
          type: string
          description: >-
            Custom storage directory path.


            Supports both naming conventions:

            - **snake_case**: `upload_path`

            - **camelCase**: `uploadPath`


            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: photos
        file_name:
          type: string
          description: >-
            Custom filename for the uploaded file.


            Supports both naming conventions:

            - **snake_case**: `file_name`

            - **camelCase**: `fileName`


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


            **Example auto-generated name**: `20251229130857_a8B9cD2e.png`
          example: photo.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
            - file_size
            - mime_type
            - file_url
            - download_url
            - expires_at
          properties:
            file_id:
              type: string
              example: 872defd8180ee9c6d32265ef4e8d255b
              description: Unique file identifier (MD5 hash)
            file_name:
              type: string
              example: test-stream.png
              description: The stored filename
            original_name:
              type: string
              example: uploaded-file.png
              description: The original filename from the uploaded file
            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-stream
              description: Storage path (includes temp/ prefix)
            file_url:
              type: string
              format: uri
              example: https://storage.vidgo.ai/temp/test-stream/test-stream.png
              description: Direct access URL for the uploaded file
            download_url:
              type: string
              format: uri
              example: https://storage.vidgo.ai/temp/test-stream/test-stream.png
              description: Download URL (same as file_url)
            upload_time:
              type: string
              format: date-time
              example: '2025-12-29T13:09:04.731057'
              description: Upload timestamp in ISO 8601 format
            expires_at:
              type: string
              format: date-time
              example: '2026-01-01T13:09:04.731057'
              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
    ValidationErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: array
          description: List of validation errors
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
                description: Location of the validation error
              msg:
                type: string
                description: Error message
              type:
                type: string
                description: Error type
  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

        ```

````