File Upload API Quickstart

Welcome to File Upload API

The File Upload API provides flexible and efficient file upload services, supporting multiple upload methods to meet diverse business needs. Whether it’s remote file migration, large file transmission, or quick small file uploads, our API offers the best solutions for your requirements.

Base64 Upload

Base64 encoded file upload, suitable for small files

File Stream Upload

Efficient binary file stream upload, ideal for large files

URL File Upload

Automatically download and upload files from remote URLs

File uploads are free - No charges apply for uploading files to our service. You can upload files without worrying about upload costs or fees.

Important Notice: Uploaded files are temporary and will be automatically deleted after 3 days. Please download or migrate important files promptly.

Authentication

All API requests require authentication using Bearer tokens. Please obtain your API key from the API Key Management Page.

Please keep your API key secure and never share it publicly. If you suspect your key has been compromised, reset it immediately.

API Base URL

https://apibox.redpandaai.co

Authentication Header

Authorization: Bearer YOUR_API_KEY

Quick Start Guide

Step 1: Choose Your Upload Method

Select the appropriate upload method based on your needs:

URL File Upload
File Stream Upload
Base64 Upload

Suitable for downloading and uploading files from remote servers:

curl -X POST "https://apibox.redpandaai.co/api/file-url-upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/sample-image.jpg",
    "uploadPath": "images",
    "fileName": "my-image.jpg"
  }'

const response = await fetch('https://apibox.redpandaai.co/api/file-url-upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/sample-image.jpg',
    uploadPath: 'images',
    fileName: 'my-image.jpg'
  })
});

const result = await response.json();
console.log('Upload successful:', result);

import requests

url = "https://apibox.redpandaai.co/api/file-url-upload"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "fileUrl": "https://example.com/sample-image.jpg",
    "uploadPath": "images",
    "fileName": "my-image.jpg"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Upload successful: {result}")

Suitable for directly uploading local files, especially large files:

curl -X POST "https://apibox.redpandaai.co/api/file-stream-upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/your-file.jpg" \
  -F "uploadPath=images/user-uploads" \
  -F "fileName=custom-name.jpg"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('uploadPath', 'images/user-uploads');
formData.append('fileName', 'custom-name.jpg');

const response = await fetch('https://apibox.redpandaai.co/api/file-stream-upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log('Upload successful:', result);

import requests

url = "https://apibox.redpandaai.co/api/file-stream-upload"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

files = {
    'file': ('your-file.jpg', open('/path/to/your-file.jpg', 'rb')),
    'uploadPath': (None, 'images/user-uploads'),
    'fileName': (None, 'custom-name.jpg')
}

response = requests.post(url, headers=headers, files=files)
result = response.json()

print(f"Upload successful: {result}")

Suitable for Base64 encoded file data:

curl -X POST "https://apibox.redpandaai.co/api/file-base64-upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "uploadPath": "images",
    "fileName": "base64-image.png"
  }'

const response = await fetch('https://apibox.redpandaai.co/api/file-base64-upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    base64Data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
    uploadPath: 'images',
    fileName: 'base64-image.png'
  })
});

const result = await response.json();
console.log('Upload successful:', result);

import requests
import base64

# Read file and convert to base64
with open('/path/to/your-file.jpg', 'rb') as f:
    file_data = base64.b64encode(f.read()).decode('utf-8')
    base64_data = f'data:image/jpeg;base64,{file_data}'

url = "https://apibox.redpandaai.co/api/file-base64-upload"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "base64Data": base64_data,
    "uploadPath": "images",
    "fileName": "base64-image.jpg"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Upload successful: {result}")

Step 2: Handle Response

Upon successful upload, you’ll receive a response containing file information:

{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "fileId": "file_abc123456",
    "fileName": "my-image.jpg",
    "originalName": "sample-image.jpg",
    "fileSize": 245760,
    "mimeType": "image/jpeg",
    "uploadPath": "images",
    "fileUrl": "https://apibox.redpandaai.co/files/images/my-image.jpg",
    "downloadUrl": "https://apibox.redpandaai.co/download/file_abc123456",
    "uploadTime": "2025-01-15T10:30:00Z",
    "expiresAt": "2025-01-18T10:30:00Z"
  }
}

Upload Method Comparison

Choose the most suitable upload method for your needs:

URL File Upload

Best for: File migration, batch processingAdvantages:

No local file required
Automatic download handling
Supports remote resources

Limitations:

Requires publicly accessible URL
30-second download timeout
Recommended ≤100MB

File Stream Upload

Best for: Large files, local filesAdvantages:

High transmission efficiency
Supports large files
Binary transmission

Limitations:

Requires local file
Server processing time

Base64 Upload

Best for: Small files, API integrationAdvantages:

JSON format transmission
Easy integration
Supports Data URL

Limitations:

Data size increases by 33%
Not suitable for large files
Recommended ≤10MB

Practical Examples

Batch File Upload

Using file stream upload to handle multiple files:

JavaScript
Python

class FileUploadAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://apibox.redpandaai.co';
  }
  
  async uploadFile(file, uploadPath = '', fileName = null) {
    const formData = new FormData();
    formData.append('file', file);
    if (uploadPath) formData.append('uploadPath', uploadPath);
    if (fileName) formData.append('fileName', fileName);
    
    const response = await fetch(`${this.baseUrl}/api/file-stream-upload`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: formData
    });
    
    if (!response.ok) {
      throw new Error(`Upload failed: ${response.statusText}`);
    }
    
    return response.json();
  }
  
  async uploadFromUrl(fileUrl, uploadPath = '', fileName = null) {
    const response = await fetch(`${this.baseUrl}/api/file-url-upload`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fileUrl,
        uploadPath,
        fileName
      })
    });
    
    if (!response.ok) {
      throw new Error(`Upload failed: ${response.statusText}`);
    }
    
    return response.json();
  }
  
  async uploadBase64(base64Data, uploadPath = '', fileName = null) {
    const response = await fetch(`${this.baseUrl}/api/file-base64-upload`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        base64Data,
        uploadPath,
        fileName
      })
    });
    
    if (!response.ok) {
      throw new Error(`Upload failed: ${response.statusText}`);
    }
    
    return response.json();
  }
}

// Usage example
const uploader = new FileUploadAPI('YOUR_API_KEY');

// Batch upload files
async function uploadMultipleFiles(files) {
  const results = [];
  
  for (let i = 0; i < files.length; i++) {
    try {
      const result = await uploader.uploadFile(
        files[i], 
        'user-uploads', 
        `file-${i + 1}-${files[i].name}`
      );
      results.push(result);
      console.log(`File ${i + 1} uploaded successfully:`, result.data.fileUrl);
    } catch (error) {
      console.error(`File ${i + 1} upload failed:`, error.message);
    }
  }
  
  return results;
}

// Batch upload from URLs
async function uploadFromUrls(urls) {
  const results = [];
  
  for (let i = 0; i < urls.length; i++) {
    try {
      const result = await uploader.uploadFromUrl(
        urls[i], 
        'downloads', 
        `download-${i + 1}.jpg`
      );
      results.push(result);
      console.log(`URL ${i + 1} uploaded successfully:`, result.data.fileUrl);
    } catch (error) {
      console.error(`URL ${i + 1} upload failed:`, error.message);
    }
  }
  
  return results;
}

import requests
import base64
import os
from typing import List, Optional

class FileUploadAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://apibox.redpandaai.co'
        self.headers = {
            'Authorization': f'Bearer {api_key}'
        }
    
    def upload_file(self, file_path: str, upload_path: str = '', 
                   file_name: Optional[str] = None) -> dict:
        """File stream upload"""
        files = {
            'file': (os.path.basename(file_path), open(file_path, 'rb'))
        }
        
        data = {}
        if upload_path:
            data['uploadPath'] = upload_path
        if file_name:
            data['fileName'] = file_name
        
        response = requests.post(
            f'{self.base_url}/api/file-stream-upload',
            headers=self.headers,
            files=files,
            data=data
        )
        
        if not response.ok:
            raise Exception(f'Upload failed: {response.text}')
        
        return response.json()
    
    def upload_from_url(self, file_url: str, upload_path: str = '', 
                       file_name: Optional[str] = None) -> dict:
        """URL file upload"""
        payload = {
            'fileUrl': file_url,
            'uploadPath': upload_path,
            'fileName': file_name
        }
        
        response = requests.post(
            f'{self.base_url}/api/file-url-upload',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=payload
        )
        
        if not response.ok:
            raise Exception(f'Upload failed: {response.text}')
        
        return response.json()
    
    def upload_base64(self, base64_data: str, upload_path: str = '', 
                     file_name: Optional[str] = None) -> dict:
        """Base64 file upload"""
        payload = {
            'base64Data': base64_data,
            'uploadPath': upload_path,
            'fileName': file_name
        }
        
        response = requests.post(
            f'{self.base_url}/api/file-base64-upload',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=payload
        )
        
        if not response.ok:
            raise Exception(f'Upload failed: {response.text}')
        
        return response.json()

# Usage example
def main():
    uploader = FileUploadAPI('YOUR_API_KEY')
    
    # Batch upload local files
    file_paths = [
        '/path/to/file1.jpg',
        '/path/to/file2.png',
        '/path/to/document.pdf'
    ]
    
    print("Starting batch file upload...")
    for i, file_path in enumerate(file_paths):
        try:
            result = uploader.upload_file(
                file_path, 
                'user-uploads', 
                f'file-{i + 1}-{os.path.basename(file_path)}'
            )
            print(f"File {i + 1} uploaded successfully: {result['data']['fileUrl']}")
        except Exception as e:
            print(f"File {i + 1} upload failed: {e}")
    
    # Batch upload from URLs
    urls = [
        'https://example.com/image1.jpg',
        'https://example.com/image2.png'
    ]
    
    print("\nStarting batch URL upload...")
    for i, url in enumerate(urls):
        try:
            result = uploader.upload_from_url(
                url, 
                'downloads', 
                f'download-{i + 1}.jpg'
            )
            print(f"URL {i + 1} uploaded successfully: {result['data']['fileUrl']}")
        except Exception as e:
            print(f"URL {i + 1} upload failed: {e}")

if __name__ == '__main__':
    main()

Error Handling

Common errors and handling methods:

401 Unauthorized

// Check if API key is correct
if (response.status === 401) {
  console.error('Invalid API key, please check Authorization header');
  // Retrieve or update API key
}

400 Bad Request

// Check request parameters
if (response.status === 400) {
  const error = await response.json();
  console.error('Request parameter error:', error.msg);
  // Check if required parameters are provided
  // Check if file format is supported
  // Check if URL is accessible
}

500 Server Error

// Implement retry mechanism
async function uploadWithRetry(uploadFunction, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await uploadFunction();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Exponential backoff
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Best Practices

File Size Optimization

Small files (≤1MB): Recommended to use Base64 upload
Medium files (1MB-10MB): Recommended to use file stream upload
Large files (>10MB): Must use file stream upload
Remote files: Use URL upload, note 100MB limit

Performance Optimization

Implement concurrency control to avoid uploading too many files simultaneously
Consider chunked upload strategies for large files
Use appropriate retry mechanisms to handle network issues
Monitor upload progress and provide user feedback

Security Considerations

Keep API keys secure and rotate them regularly
Validate file types and sizes
Consider encrypted transmission for sensitive files
Download important files promptly to avoid 3-day deletion

Error Handling

Implement comprehensive error handling logic
Log uploads for troubleshooting
Provide user-friendly error messages
Offer retry options for failed uploads

File Storage Information

Important Notice: All uploaded files are temporary and will be automatically deleted after 3 days.

Files are immediately accessible and downloadable after upload
File URLs remain valid for 3 days
The system provides an expiresAt field in the response indicating expiration time
It’s recommended to download or migrate important files before expiration
Use the downloadUrl field to get direct download links

File Name Behavior

fileName Parameter Details:

Optional: If not provided, a random file name will be automatically generated
File Overwriting: If a file with the same name already exists in the same path, the old file will be overwritten
Caching: Due to CDN caching mechanisms, file overwrites may not take effect immediately and could take several minutes to propagate

Status Codes

Success

Request processed successfully, file upload completed

Bad Request

Request parameters are incorrect or missing required parameters

Unauthorized

Authentication credentials are missing or invalid

Method Not Allowed

Request method is not supported, please check HTTP method

Server Error

An unexpected error occurred while processing the request, please retry or contact support

Next Steps

URL File Upload

Learn how to upload files from remote URLs

File Stream Upload

Master efficient file stream upload methods

Base64 Upload

Understand Base64 encoded file uploads

Support

Need help? Our technical support team is here to assist you.

Email: support@api.box
Documentation: docs.api.box
API Status: Check our status page for real-time API health

Ready to start uploading files? Get your API key and begin using the file upload service immediately!

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

File Upload API Quickstart

Welcome to File Upload API

Base64 Upload

File Stream Upload

URL File Upload

Authentication

API Base URL

Authentication Header

Quick Start Guide

Step 1: Choose Your Upload Method

Step 2: Handle Response

Upload Method Comparison

URL File Upload

File Stream Upload

Base64 Upload

Practical Examples

Batch File Upload

Error Handling

Best Practices

File Storage Information

File Name Behavior

Status Codes

Next Steps

URL File Upload

File Stream Upload

Base64 Upload

Support

​Welcome to File Upload API

Base64 Upload

File Stream Upload

URL File Upload

​Authentication

​API Base URL

​Authentication Header

​Quick Start Guide

​Step 1: Choose Your Upload Method

​Step 2: Handle Response

​Upload Method Comparison

URL File Upload

File Stream Upload

Base64 Upload

​Practical Examples

​Batch File Upload

​Error Handling

​Best Practices

​File Storage Information

​File Name Behavior

​Status Codes

​Next Steps

URL File Upload

File Stream Upload

Base64 Upload

​Support

Welcome to File Upload API

Authentication

API Base URL

Authentication Header

Quick Start Guide

Step 1: Choose Your Upload Method

Step 2: Handle Response

Upload Method Comparison

Practical Examples

Batch File Upload

Error Handling

Best Practices

File Storage Information

File Name Behavior

Status Codes

Next Steps

Support