文件上传 API 快速开始

欢迎使用文件上传 API

文件上传 API 为您提供灵活、高效的文件上传服务，支持多种上传方式以满足不同的业务需求。无论是远程文件迁移、大文件传输还是小文件快速上传，我们的 API 都能为您提供最佳解决方案。

Base64 上传

Base64 编码文件上传，适合小文件

文件流上传

高效的二进制文件流上传，适合大文件

URL 文件上传

从远程 URL 自动下载并上传文件

文件上传是免费的 - 上传文件到我们的服务不收取任何费用。您可以放心上传文件，无需担心上传成本或费用。

重要提醒：上传的文件为临时文件，将在 3天后自动删除。请及时下载或迁移重要文件。

身份验证

所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面获取您的 API 密钥。

请妥善保管您的 API 密钥，切勿公开分享。如果怀疑密钥泄露，请立即重置。

API 基础 URL

https://apibox.redpandaai.co

身份验证请求头

Authorization: Bearer YOUR_API_KEY

快速开始指南

第一步：选择上传方式

根据您的需求选择合适的上传方式：

URL 文件上传
文件流上传
Base64 上传

适用于从远程服务器下载并上传文件：

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('上传成功:', 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"上传成功: {result}")

适用于直接上传本地文件，特别是大文件：

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('上传成功:', 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"上传成功: {result}")

适用于 Base64 编码的文件数据：

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('上传成功:', result);

import requests
import base64

# 读取文件并转换为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"上传成功: {result}")

第二步：处理响应结果

成功上传后，您将收到包含文件信息的响应：

{
  "success": true,
  "code": 200,
  "msg": "文件上传成功",
  "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"
  }
}

上传方式对比

选择最适合您需求的上传方式：

URL 文件上传

最适合：文件迁移、批量处理优势：

无需本地文件
自动下载处理
支持远程资源

限制：

需要公开可访问的URL
30秒下载超时
推荐≤100MB

文件流上传

最适合：大文件、本地文件优势：

高传输效率
支持大文件
二进制传输

限制：

需要本地文件
服务器处理时间

Base64 上传

最适合：小文件、API集成优势：

JSON格式传输
易于集成
支持Data URL

限制：

数据量增加33%
不适合大文件
推荐≤10MB

实用示例

批量文件上传

使用文件流上传处理多个文件：

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(`上传失败: ${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(`上传失败: ${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(`上传失败: ${response.statusText}`);
    }
    
    return response.json();
  }
}

// 使用示例
const uploader = new FileUploadAPI('YOUR_API_KEY');

// 批量上传文件
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(`文件 ${i + 1} 上传成功:`, result.data.fileUrl);
    } catch (error) {
      console.error(`文件 ${i + 1} 上传失败:`, error.message);
    }
  }
  
  return results;
}

// 从URL批量上传
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} 上传成功:`, result.data.fileUrl);
    } catch (error) {
      console.error(`URL ${i + 1} 上传失败:`, 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:
        """文件流上传"""
        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'上传失败: {response.text}')
        
        return response.json()
    
    def upload_from_url(self, file_url: str, upload_path: str = '', 
                       file_name: Optional[str] = None) -> dict:
        """URL文件上传"""
        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'上传失败: {response.text}')
        
        return response.json()
    
    def upload_base64(self, base64_data: str, upload_path: str = '', 
                     file_name: Optional[str] = None) -> dict:
        """Base64文件上传"""
        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'上传失败: {response.text}')
        
        return response.json()

# 使用示例
def main():
    uploader = FileUploadAPI('YOUR_API_KEY')
    
    # 批量上传本地文件
    file_paths = [
        '/path/to/file1.jpg',
        '/path/to/file2.png',
        '/path/to/document.pdf'
    ]
    
    print("开始批量上传文件...")
    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"文件 {i + 1} 上传成功: {result['data']['fileUrl']}")
        except Exception as e:
            print(f"文件 {i + 1} 上传失败: {e}")
    
    # 批量从URL上传
    urls = [
        'https://example.com/image1.jpg',
        'https://example.com/image2.png'
    ]
    
    print("\n开始从URL批量上传...")
    for i, url in enumerate(urls):
        try:
            result = uploader.upload_from_url(
                url, 
                'downloads', 
                f'download-{i + 1}.jpg'
            )
            print(f"URL {i + 1} 上传成功: {result['data']['fileUrl']}")
        except Exception as e:
            print(f"URL {i + 1} 上传失败: {e}")

if __name__ == '__main__':
    main()

错误处理

常见错误及处理方法：

401 未授权

// 检查API密钥是否正确
if (response.status === 401) {
  console.error('API密钥无效，请检查Authorization头');
  // 重新获取或更新API密钥
}

400 参数错误

// 检查请求参数
if (response.status === 400) {
  const error = await response.json();
  console.error('请求参数错误:', error.msg);
  // 检查必填参数是否提供
  // 检查文件格式是否支持
  // 检查URL是否可访问
}

500 服务器错误

// 实施重试机制
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;
      
      // 指数退避
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

最佳实践

文件大小优化

小文件 (≤1MB)：推荐使用 Base64 上传
中等文件 (1MB-10MB)：推荐使用文件流上传
大文件 (>10MB)：必须使用文件流上传
远程文件：使用 URL 上传，注意100MB限制

性能优化

实施并发控制，避免同时上传过多文件
对大文件考虑分片上传策略
使用适当的重试机制处理网络问题
监控上传进度并提供用户反馈

安全考虑

妥善保管API密钥，定期轮换
验证文件类型和大小
对敏感文件考虑加密传输
及时下载重要文件，避免3天后删除

错误处理

实施完整的错误处理逻辑
记录上传日志用于问题排查
提供友好的错误提示给用户
对失败的上传提供重试选项

文件存储说明

重要提醒：所有上传的文件均为临时文件，将在上传后 3天自动删除。

文件上传后立即可访问和下载
文件URL在3天内保持有效
系统会在响应中提供 expiresAt 字段表示过期时间
建议在过期前及时下载或迁移重要文件
可以使用 downloadUrl 字段获取直接下载链接

文件名行为说明

fileName 参数详细说明：

可选参数：如不提供，系统将自动生成随机文件名
文件覆盖：如果相同路径下已存在同名文件，旧文件将被覆盖
缓存机制：由于CDN缓存机制，文件覆盖可能不会立即生效，需要几分钟时间才能完全传播更新

状态码说明

200

成功

请求已成功处理，文件上传完成

400

参数错误

请求参数不正确或缺少必填参数

401

未授权

缺少身份验证凭据或凭据无效

405

方法不被允许

请求方法不支持，请检查HTTP方法

500

服务器错误

处理请求时发生意外错误，请重试或联系支持

下一步

URL 文件上传

了解如何从远程URL上传文件

文件流上传

学习高效的文件流上传方法

Base64 上传

掌握Base64编码文件上传

支持

需要帮助吗？我们的技术支持团队随时为您提供帮助。

邮箱: support@api.box
文档: docs.api.box
API状态: 查看我们的状态页面了解实时API健康状况

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management