Skip to main content
POST
/
api
/
common
/
upload
/
url
curl --request POST \
  --url https://api.vidgo.ai/api/common/upload/url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_url": "https://example.com/images/sample.jpg"
}
'
{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "file_id": "1bdfdbac6ebc2228d0b398d728bf4699",
    "file_name": "test-image.png",
    "original_name": "image-from-url.png",
    "file_size": 1419815,
    "mime_type": "image/png",
    "upload_path": "temp/test-uploads",
    "file_url": "https://storage.vidgo.ai/temp/test-uploads/test-image.png",
    "download_url": "https://storage.vidgo.ai/temp/test-uploads/test-image.png",
    "upload_time": "2025-12-29T13:08:57.673515",
    "expires_at": "2026-01-01T13:08:57.673515"
  }
}

​
Usage Guide

  • This endpoint enables uploading files to Vidgo API by providing a remote URL
  • The system automatically downloads the file from the specified URL and stores it in Vidgo API storage
  • Ideal for migrating files from external servers or integrating with third-party file sources
  • Files are returned with a direct access URL and remain available for 72 hours

​
Parameter Details

  • File URL Requirement:
    • The file_url must be a publicly accessible URL using HTTP or HTTPS protocol
    • The remote server must allow the file to be downloaded without authentication
    • 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: "avatars", the actual path will be temp/avatars
    • 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

  • Ensure your source URL is publicly accessible and does not require authentication or special headers
  • The download process may take a few seconds depending on the file size and network conditions
  • For persistent storage needs, download and save the file locally before the 72-hour expiration
  • The file_url and download_url in the response are identical and both provide direct access to the uploaded file

​
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 URL: The provided URL is malformed or unreachable
  • Download Failure: Network timeout or connection issues when downloading from the remote URL
  • Unsupported File Type: The file at the URL is not in a supported image format (JPEG, PNG, GIF, WebP)
  • 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
​
file_url
string<uri>
required

The remote file URL to upload.

Must be a publicly accessible URL using HTTP or HTTPS protocol.

Supported formats: JPEG, PNG, GIF, WebP

Note: The file will be downloaded from this URL and stored in Vidgo API storage.

Example:

"https://example.com/images/sample.jpg"

​
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:

"avatars"

​
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:

"my-custom-image.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