Skip to main content
POST
/
api
/
common
/
upload
/
base64
curl --request POST \
  --url https://api.vidgo.ai/api/common/upload/base64 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base64_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
'
{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "file_id": "da2611c99d3ce825bc9a5409378db8e4",
    "file_name": "test-base64.png",
    "original_name": "test-base64.png",
    "file_size": 3242,
    "mime_type": "image/png",
    "upload_path": "temp/test-base64",
    "file_url": "https://storage.vidgo.ai/temp/test-base64/test-base64.png",
    "download_url": "https://storage.vidgo.ai/temp/test-base64/test-base64.png",
    "upload_time": "2025-12-29T13:09:01.233635",
    "expires_at": "2026-01-01T13:09:01.233635"
  }
}

​
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

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

application/json
​
base64_data
string
required

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
string

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
string

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"

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