欢迎使用文件上传 API
文件上传 API 为您提供灵活、高效的文件上传服务，支持多种上传方式以满足不同的业务需求。无论是远程文件迁移、大文件传输还是小文件快速上传，我们的 API 都能为您提供最佳解决方案。
重要提醒：上传的文件为临时文件，将在 3天 后自动删除。请及时下载或迁移重要文件。
身份验证
所有 API 请求都需要使用 Bearer 令牌进行身份验证。请从 API 密钥管理页面 获取您的 API 密钥。
请妥善保管您的 API 密钥，切勿公开分享。如果怀疑密钥泄露，请立即重置。
API 基础 URL
https://kieai.redpandaai.co
身份验证请求头
Authorization: Bearer YOUR_API_KEY
快速开始指南
第一步：选择上传方式
根据您的需求选择合适的上传方式：
适用于从远程服务器下载并上传文件：curl -X POST "https://kieai.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"
}'
第一步补充：fileName 参数说明
fileName 参数在所有上传方式中都是可选的，其行为如下：
文件名行为说明：
- 如不提供文件名，将自动生成随机文件名
- 若新上传的文件名与已存在文件名相同，则旧文件将被覆盖
- 由于缓存原因，覆盖文件时此更改可能不会立即生效
示例：// 不提供 fileName - 自动生成随机文件名
{ uploadPath: "images" } // → 生成 "abc123.jpg"
// 提供 fileName - 使用指定文件名
{ uploadPath: "images", fileName: "my-photo.jpg" }
// 覆盖文件 - 替换现有文件（存在缓存延迟）
{ uploadPath: "images", fileName: "my-photo.jpg" } // 覆盖之前的文件
第二步：处理响应结果
成功上传后，您将收到包含文件信息的响应：
{
"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://kieai.redpandaai.co/files/images/my-image.jpg",
"downloadUrl": "https://kieai.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://kieai.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;
}
错误处理
常见错误及处理方法：
// 检查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限制
- 实施并发控制，避免同时上传过多文件
- 对大文件考虑分片上传策略
- 使用适当的重试机制处理网络问题
- 监控上传进度并提供用户反馈
- 妥善保管API密钥，定期轮换
- 验证文件类型和大小
- 对敏感文件考虑加密传输
- 及时下载重要文件，避免3天后删除
- 实施完整的错误处理逻辑
- 记录上传日志用于问题排查
- 提供友好的错误提示给用户
- 对失败的上传提供重试选项
文件存储说明
重要提醒：所有上传的文件均为临时文件，将在上传后 3天 自动删除。
- 文件上传后立即可访问和下载
- 文件URL在3天内保持有效
- 系统会在响应中提供
expiresAt 字段表示过期时间
- 建议在过期前及时下载或迁移重要文件
- 可以使用
downloadUrl 字段获取直接下载链接
状态码说明
下一步
准备开始上传文件了吗？获取您的API密钥，立即开始使用文件上传服务！