Upload File from Base64

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

POST /api/common/upload/base64

cURL

data-url-format

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=="
}
'

200

Example

{
  "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

200

application/json

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

Show child attributes