文件上传 API 快速开始

欢迎使用文件上传 API

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

Base64 上传

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

文件流上传

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

URL 文件上传

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

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

身份验证

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

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

API 基础 URL

https://kieai.redpandaai.co

身份验证请求头

Authorization: Bearer YOUR_API_KEY

快速开始指南

第一步：选择上传方式

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

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

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

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"
  }'

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

curl -X POST "https://kieai.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://kieai.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"
  }'

第一步补充：fileName 参数说明

fileName 参数在所有上传方式中都是可选的，其行为如下：

fileName

string

文件名行为说明：

如不提供文件名，将自动生成随机文件名
若新上传的文件名与已存在文件名相同，则旧文件将被覆盖
由于缓存原因，覆盖文件时此更改可能不会立即生效

示例：

// 不提供 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

文件流上传

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

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

限制：

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

Base64 上传

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

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

限制：

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

实用示例

批量文件上传

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

JavaScript
Python

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;
}

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://kieai.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 字段获取直接下载链接

状态码说明

200

成功

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

400

参数错误

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

401

未授权

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

405

方法不被允许

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

500

服务器错误

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

下一步

URL 文件上传

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

文件流上传

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

Base64 上传

掌握Base64编码文件上传

支持

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

邮箱: [email protected]
文档: docs.kie.ai
API状态: 查看我们的状态页面了解实时API健康状况

​欢迎使用文件上传 API

Base64 上传

文件流上传

URL 文件上传

​身份验证

​API 基础 URL

​身份验证请求头

​快速开始指南

​第一步：选择上传方式

​第一步补充：fileName 参数说明

​第二步：处理响应结果

​上传方式对比

URL 文件上传

文件流上传

Base64 上传

​实用示例

​批量文件上传

​错误处理

​最佳实践

​文件存储说明

​状态码说明

​下一步

URL 文件上传

文件流上传

Base64 上传

​支持

欢迎使用文件上传 API

身份验证

API 基础 URL

身份验证请求头

快速开始指南

第一步：选择上传方式

第一步补充：fileName 参数说明

第二步：处理响应结果

上传方式对比

实用示例

批量文件上传

错误处理

最佳实践

文件存储说明

状态码说明

下一步

支持