ModelFold Docs

简体中文

English

简体中文

English

Appearance

文件上传 API 快速开始 ​

几分钟内开始使用文件上传 API，支持多种上传方式

欢迎使用文件上传 API ​

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

INFO

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

WARNING

重要提醒：上传文件在上传 24 小时后自动删除。请及时下载或迁移重要文件。

身份验证 ​

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

WARNING

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

API 基础 URL ​

https://ai.modelfold.online

身份验证请求头 ​

http
Authorization: Bearer YOUR_API_KEY

快速开始指南 ​

第一步：选择上传方式 ​

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

URL 文件上传 ​

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

<TabItem value="bash" label="cURL"> bash curl -X POST "https://ai.modelfold.online/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" }'

JavaScript ​

javascript
const response = await fetch('https://ai.modelfold.online/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);

Python ​

python
import requests

url = "https://ai.modelfold.online/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}")

</TabItem>

文件流上传 ​

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

<TabItem value="bash" label="cURL"> bash curl -X POST "https://ai.modelfold.online/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"

JavaScript ​

javascript
const formData = new FormData();
formData.append('file', fileInput.files[);
formData.append('uploadPath', 'images/user-uploads');
formData.append('fileName', 'custom-name.jpg');

const response = await fetch('https://ai.modelfold.online/api/file-stream-upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log('上传成功:', result);

Python ​

python
import requests

url = "https://ai.modelfold.online/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}")

</TabItem>

Base64 上传 ​

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

<TabItem value="bash" label="cURL"> bash curl -X POST "https://ai.modelfold.online/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" }'

JavaScript ​

javascript
const response = await fetch('https://ai.modelfold.online/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);

Python ​

python
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://ai.modelfold.online/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}")

</TabItem>

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

INFO

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

fileName (string, optional) ​

文件名行为说明：

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

示例：

javascript
// 不提供 fileName - 自动生成随机文件名
{ uploadPath: "images" } // → 生成 "abc123.jpg"

// 提供 fileName - 使用指定文件名
{ uploadPath: "images", fileName: "my-photo.jpg" }

// 覆盖文件 - 替换现有文件（存在缓存延迟）
{ uploadPath: "images", fileName: "my-photo.jpg" } // 覆盖之前的文件

第二步：处理响应结果 ​

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

json
{
  "success": true,
  "code": 200,
  "msg": "文件上传成功",
  "data": {
    "success": true,
    "fileName": "my-image.jpg",
    "filePath": "ModelFold/12345/images/my-image.jpg",
    "downloadUrl": "https://tempfile.redpandaai.co/ModelFold/12345/images/my-image.jpg",
    "fileSize": 245760,
    "mimeType": "image/jpeg",
    "uploadedAt": "2025-01-15T10:30:00.000Z"
  }
}

上传方式对比 ​

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

  • URL 文件上传 — 最适合 ：文件迁移、批量处理 优势 ： 无需本地文件 自动下载处理 支持远程资源 限制 ： 需要公开可访问的URL 30秒下载超时 推荐≤100MB

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

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

实用示例 ​

批量文件上传 ​

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

JavaScript ​

javascript
class FileUploadAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://ai.modelfold.online';
  }
  
  async uploadFile(file, uploadPath, fileName = null) {
    const formData = new FormData();
    formData.append('file', file);
    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
    });
    
    const r = await response.json();
    if (!r.success || r.code !== 200) throw new Error(r.msg);
    
    return r;
  }
  
  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
      })
    });
    
    const r = await response.json();
    if (!r.success || r.code !== 200) throw new Error(r.msg);
    
    return r;
  }
  
  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
      })
    });
    
    const r = await response.json();
    if (!r.success || r.code !== 200) throw new Error(r.msg);
    
    return r;
  }
}

// 使用示例
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.downloadUrl);
    } 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.downloadUrl);
    } catch (error) {
      console.error(`URL ${i + 1} 上传失败:`, error.message);
    }
  }
  
  return results;
}

Python ​

python
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://ai.modelfold.online'
        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 = {}
        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
        )
        
        r = response.json()
        if not r.get('success') or r.get('code') != 200:
            raise Exception(r.get('msg'))
        
        return r
    
    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
        )
        
        r = response.json()
        if not r.get('success') or r.get('code') != 200:
            raise Exception(r.get('msg'))
        
        return r
    
    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
        )
        
        r = response.json()
        if not r.get('success') or r.get('code') != 200:
            raise Exception(r.get('msg'))
        
        return r

# 使用示例
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']['downloadUrl']}")
        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']['downloadUrl']}")
        except Exception as e:
            print(f"URL {i + 1} 上传失败: {e}")

if __name__ == '__main__':
    main()

错误处理 ​

出错时 HTTP 状态仍为 200，错误码在响应体 code 中。常见错误及处理方法：

401 未授权
javascript
// 检查API密钥是否正确
const result = await response.json();
if (result.code === 401) {
  console.error('API密钥无效，请检查Authorization头');
  // 重新获取或更新API密钥
}
400 参数错误
javascript
// 检查请求参数
const result = await response.json();
if (result.code === 400) {
  console.error('请求参数错误:', result.msg);
  // 检查必填参数是否提供
  // 检查文件格式是否支持
  // 检查URL是否可访问
}
500 服务器错误
javascript
// 实施重试机制
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密钥，定期轮换 * 验证文件类型和大小 * 对敏感文件考虑加密传输
错误处理 * 实施完整的错误处理逻辑 * 记录上传日志用于问题排查 * 提供友好的错误提示给用户 * 对失败的上传提供重试选项

文件存储说明 ​

WARNING

重要提醒：上传文件在上传 24 小时后自动删除。

  • 文件上传后立即可访问和下载
  • 建议在过期前及时下载或迁移重要文件
  • 可以使用 downloadUrl 字段获取直接下载链接

状态码说明 ​

错误码在响应体 code 中，HTTP 状态为 200。

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

支持 ​

INFO

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

准备开始上传文件了吗？获取您的API密钥，立即开始使用文件上传服务！

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold