文件流上传

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口

POST /api/file-stream-upload

完整 URL: https://ai.modelfold.online/api/file-stream-upload

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

INFO

上传文件在上传 24 小时后自动删除。

功能特点

• 支持多种文件类型的二进制流上传
• 适合大文件上传，传输效率高
• 自动识别 MIME 类型
• 支持自定义文件名或自动生成（相同文件名会覆盖旧文件，可能存在缓存延迟）
• 返回完整的文件信息和下载链接
• API Key 认证保护

使用建议

• 推荐用于大文件（>10MB）
• 支持多种格式：图片、视频、文档等
• 避免 Base64 编码带来的约 33% 体积增加。

示例命令

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"

请求参数

请求体 (multipart/form-data)

参数	类型	必填	说明
file	string	是	要上传的文件（二进制数据） 示例：``。
uploadPath	string	是	文件上传路径，不带首尾斜杠 示例：images/user-uploads。
fileName	string	否	文件名（可选），包含文件扩展名。如不提供文件名，将自动生成随机文件名。若新上传的文件名与已存在文件名相同，则旧文件将被覆盖，但由于缓存原因，此更改可能不会立即生效 示例：my-image.jpg。

请求示例

curl -X POST "https://ai.modelfold.online/api/file-stream-upload" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -F "file=" \
  -F "uploadPath=images/user-uploads" \
  -F "fileName=my-image.jpg"

{
  "file": "",
  "uploadPath": "images/user-uploads",
  "fileName": "my-image.jpg"
}

响应

200 — File uploaded successfully

参数	类型	必填	说明
success	boolean	是	Whether the request was successful
code	integer	是	Response Status Code
msg	string	是	Response message 示例：File uploaded successfully。
data	object	是	—
data.fileName	string	是	File name 示例：uploaded-image.png。
data.filePath	string	是	Complete file path in storage 示例：images/user-uploads/uploaded-image.png。
data.downloadUrl	string	是	File download URL 示例：https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png。
data.fileSize	integer	是	File size in bytes 示例：154832。
data.mimeType	string	是	File MIME type 示例：image/png。
data.uploadedAt	string	是	Upload timestamp 示例：2025-01-01T12:00:00.000Z。

{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "fileName": "uploaded-image.png",
    "filePath": "images/user-uploads/uploaded-image.png",
    "downloadUrl": "https://tempfile.redpandaai.co/xxx/images/user-uploads/uploaded-image.png",
    "fileSize": 154832,
    "mimeType": "image/png",
    "uploadedAt": "2025-01-01T12:00:00.000Z"
  }
}

400 — 请求参数错误

参数	类型	必填	说明
success	boolean	是	请求是否成功
code	integer	是	响应状态码
msg	string	是	响应消息 示例：File uploaded successfully。

{
  "success": false,
  "code": 400,
  "msg": "Missing required parameter: uploadPath"
}

401 — Unauthorized access

参数	类型	必填	说明
code	integer	否	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 402 / 404 / 422 / 429 / 455 / 500 / 501 / 505。 示例：200。
msg	string	否	响应消息，请求失败时返回错误描述 示例：success。
success	boolean	是	是否成功

{
  "success": false,
  "code": 401,
  "msg": "Authentication failed: Invalid API Key"
}

500 — 服务器内部错误

参数	类型	必填	说明
success	boolean	是	请求是否成功
code	integer	是	响应状态码
msg	string	是	响应消息 示例：File uploaded successfully。

{
  "success": false,
  "code": 500,
  "msg": "Internal server error"
}