欢迎使用文件上传 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"
  }'

第二步:处理响应结果

成功上传后,您将收到包含文件信息的响应:
{
  "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

文件流上传

最适合:大文件、本地文件优势
  • 高传输效率
  • 支持大文件
  • 二进制传输
限制
  • 需要本地文件
  • 服务器处理时间

Base64 上传

最适合:小文件、API集成优势
  • JSON格式传输
  • 易于集成
  • 支持Data URL
限制
  • 数据量增加33%
  • 不适合大文件
  • 推荐≤10MB

实用示例

批量文件上传

使用文件流上传处理多个文件:
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;
}

错误处理

常见错误及处理方法:

最佳实践

文件存储说明

重要提醒:所有上传的文件均为临时文件,将在上传后 3天 自动删除。
  • 文件上传后立即可访问和下载
  • 文件URL在3天内保持有效
  • 系统会在响应中提供 expiresAt 字段表示过期时间
  • 建议在过期前及时下载或迁移重要文件
  • 可以使用 downloadUrl 字段获取直接下载链接

状态码说明

200
成功
请求已成功处理,文件上传完成
400
参数错误
请求参数不正确或缺少必填参数
401
未授权
缺少身份验证凭据或凭据无效
405
方法不被允许
请求方法不支持,请检查HTTP方法
500
服务器错误
处理请求时发生意外错误,请重试或联系支持

下一步

支持

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

准备开始上传文件了吗?获取您的API密钥,立即开始使用文件上传服务!