Skip to main content
POST
/
api
/
common
/
upload
/
stream
curl --request POST \
  --url https://api.vidgo.ai/api/common/upload/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "file_id": "872defd8180ee9c6d32265ef4e8d255b",
    "file_name": "test-stream.png",
    "file_size": 3242,
    "mime_type": "image/png",
    "file_url": "https://storage.vidgo.ai/temp/test-stream/test-stream.png",
    "download_url": "https://storage.vidgo.ai/temp/test-stream/test-stream.png",
    "expires_at": "2026-01-01T13:09:04.731057",
    "original_name": "uploaded-file.png",
    "upload_path": "temp/test-stream",
    "upload_time": "2025-12-29T13:09:04.731057"
  }
}

​
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

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

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)

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));

Authorizations

​
Authorization
string
header
required

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer VIDGO_API_KEY

Body

multipart/form-data
​
file
file
required

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
string

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
string

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"

Response

File uploaded successfully

​
success
boolean
required

Indicates whether the upload was successful

Example:

true

​
code
integer
required

HTTP status code

Example:

200

​
msg
string
required

Response message

Example:

"File uploaded successfully"

​
data
object
required