欢迎使用文件上传 API
文件上传 API 为您提供灵活、高效的文件上传服务，支持多种上传方式以满足不同的业务需求。无论是远程文件迁移、大文件传输还是小文件快速上传，我们的 API 都能为您提供最佳解决方案。
Base64 上传
Base64 编码文件上传，适合小文件
URL 文件上传
从远程 URL 自动下载并上传文件
文件上传是免费的 - 上传文件到我们的服务不收取任何费用。您可以放心上传文件，无需担心上传成本或费用。
重要提醒：上传的文件为临时文件，将在 3天 后自动删除。请及时下载或迁移重要文件。
身份验证
所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥，切勿公开分享。如果怀疑密钥泄露，请立即重置。
API 基础 URL
https://sunoapiorg.redpandaai.co
身份验证请求头
Authorization: Bearer YOUR_API_KEY
快速开始指南
第一步：选择上传方式
根据您的需求选择合适的上传方式：
适用于从远程服务器下载并上传文件：curl -X POST "https://sunoapiorg.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"
}'
适用于直接上传本地文件，特别是大文件：curl -X POST "https://sunoapiorg.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"
适用于 Base64 编码的文件数据：curl -X POST "https://sunoapiorg.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"
}'
第二步：处理响应结果
成功上传后，您将收到包含文件信息的响应：
{
"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://sunoapiorg.redpandaai.co/files/images/my-image.jpg",
"downloadUrl": "https://sunoapiorg.redpandaai.co/download/file_abc123456",
"uploadTime": "2025-01-15T10:30:00Z",
"expiresAt": "2025-01-18T10:30:00Z"
}
}
上传方式对比
选择最适合您需求的上传方式：
URL 文件上传
最适合：文件迁移、批量处理优势：限制：
- 需要公开可访问的URL
- 30秒下载超时
- 推荐≤100MB
实用示例
批量文件上传
使用文件流上传处理多个文件：
class FileUploadAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://sunoapiorg.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://sunoapiorg.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()
错误处理
常见错误及处理方法：
// 检查API密钥是否正确
if (response.status === 401) {
console.error('API密钥无效，请检查Authorization头');
// 重新获取或更新API密钥
}
// 检查请求参数
if (response.status === 400) {
const error = await response.json();
console.error('请求参数错误:', error.msg);
// 检查必填参数是否提供
// 检查文件格式是否支持
// 检查URL是否可访问
}
// 实施重试机制
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限制
- 随机生成：如不提供fileName参数，系统将自动生成随机文件名
- 文件覆盖：若提供的fileName与已存在文件相同，旧文件将被覆盖
- 缓存行为：由于缓存机制，文件覆盖效果可能不会立即显现
- 最佳实践：建议使用带时间戳的唯一文件名避免冲突（如：
image-2024-01-15-10-30.jpg）
- 实施并发控制，避免同时上传过多文件
- 对大文件考虑分片上传策略
- 使用适当的重试机制处理网络问题
- 监控上传进度并提供用户反馈
- 妥善保管API密钥，定期轮换
- 验证文件类型和大小
- 对敏感文件考虑加密传输
- 及时下载重要文件，避免3天后删除
- 实施完整的错误处理逻辑
- 记录上传日志用于问题排查
- 提供友好的错误提示给用户
- 对失败的上传提供重试选项
文件存储说明
重要提醒：所有上传的文件均为临时文件，将在上传后 3天 自动删除。
- 文件上传后立即可访问和下载
- 文件URL在3天内保持有效
- 系统会在响应中提供
expiresAt 字段表示过期时间
- 建议在过期前及时下载或迁移重要文件
- 可以使用
downloadUrl 字段获取直接下载链接
状态码说明
下一步
准备开始上传文件了吗？获取您的API密钥，立即开始使用文件上传服务！