> ## 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 from URL > Upload files to Vidgo API by providing a remote URL ## 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 ## OpenAPI ````yaml /api-manual/file-series/upload-url.json POST /api/common/upload/url openapi: 3.0.0 info: title: Vidgo API - Upload File from URL description: >- Upload files to Vidgo API by providing a remote URL. The system automatically downloads and stores the file from the specified location. version: 1.0.0 servers: - url: https://api.vidgo.ai description: Production server security: - BearerAuth: [] paths: /api/common/upload/url: post: tags: - File Upload summary: Upload File from URL description: >- Upload files by providing a remote URL. The file will be downloaded from the URL and stored in Vidgo API storage. operationId: uploadFileFromUrl requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UploadUrlRequest' examples: basic-upload: summary: Basic URL Upload value: file_url: https://example.com/images/sample.jpg custom-naming: summary: Upload with Custom Filename value: file_url: https://example.com/images/photo.png file_name: my-custom-image.png custom-path: summary: Upload with Custom Path and Name value: file_url: https://example.com/images/avatar.webp upload_path: avatars file_name: user-avatar.webp responses: '200': description: File uploaded successfully content: application/json: schema: $ref: '#/components/schemas/UploadResponse' '400': description: >- Bad request - Invalid URL, unsupported file type, or download failure content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid-url: summary: Invalid File URL value: detail: >- Failed to download file: HTTPSConnectionPool(host='invalid-url.com', port=443): Max retries exceeded unsupported-type: summary: Unsupported File Type value: detail: 'Unsupported file type: application/pdf' download-failed: summary: Download Failed value: detail: 'Failed to download file: Connection timeout' '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 '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: Unable to connect to R2 storage' components: schemas: UploadUrlRequest: type: object required: - file_url properties: file_url: type: string format: uri description: >- 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: type: string description: >- 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: type: string description: >- 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 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 - original_name - file_size - mime_type - upload_path - file_url - download_url - upload_time - expires_at properties: file_id: type: string example: 1bdfdbac6ebc2228d0b398d728bf4699 description: Unique file identifier (MD5 hash) file_name: type: string example: test-image.png description: The stored filename original_name: type: string example: image-from-url.png description: The original filename from the URL file_size: type: integer example: 1419815 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-uploads description: Storage path (includes temp/ prefix) file_url: type: string format: uri example: https://storage.vidgo.ai/temp/test-uploads/test-image.png description: Direct access URL for the uploaded file download_url: type: string format: uri example: https://storage.vidgo.ai/temp/test-uploads/test-image.png description: Download URL (same as file_url) upload_time: type: string format: date-time example: '2025-12-29T13:08:57.673515' description: Upload timestamp in ISO 8601 format expires_at: type: string format: date-time example: '2026-01-01T13:08:57.673515' 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 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 ``` ````