上传文件
curl --request POST \
--url https://api.example.com/api/v1/upload \
--header 'Agent: <agent>' \
--header 'Content-Type: multipart/form-data' \
--form file='@example-file' \
--form created_by=xiaomingimport requests
url = "https://api.example.com/api/v1/upload"
files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "created_by": "xiaoming" }
headers = {"Agent": "<agent>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', 'file:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg');
form.append('created_by', 'xiaoming');
const options = {method: 'POST', headers: {Agent: '<agent>'}};
options.body = form;
fetch('https://api.example.com/api/v1/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Agent: <agent>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/upload"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Agent", "<agent>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/upload")
.header("Agent", "<agent>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/upload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Agent"] = '<agent>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"code": 200,
"msg": "File uploaded successfully",
"data": {
"id": "https://s3.juniortree.com/xiao-x-bao/uploads/2025/09/01/b9cb193906b145939dc3d9cb6240b933.jpg",
"name": "607a919df57e2a8b6a7ab17022cdf663122166603.jpg",
"size": 348514,
"extension": "jpg",
"mime_type": "image/jpeg",
"created_by": "xiaoming",
"created_at": 1756713029
}
}文件上传
文件上传接口
POST
/
api
/
v1
/
upload
上传文件
curl --request POST \
--url https://api.example.com/api/v1/upload \
--header 'Agent: <agent>' \
--header 'Content-Type: multipart/form-data' \
--form file='@example-file' \
--form created_by=xiaomingimport requests
url = "https://api.example.com/api/v1/upload"
files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "created_by": "xiaoming" }
headers = {"Agent": "<agent>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('file', 'file:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg');
form.append('created_by', 'xiaoming');
const options = {method: 'POST', headers: {Agent: '<agent>'}};
options.body = form;
fetch('https://api.example.com/api/v1/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Agent: <agent>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/upload"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Agent", "<agent>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/upload")
.header("Agent", "<agent>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/upload")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Agent"] = '<agent>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nfile:///Users/liueic/Downloads/607a919df57e2a8b6a7ab17022cdf663122166603.jpg\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"created_by\"\r\n\r\nxiaoming\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"code": 200,
"msg": "File uploaded successfully",
"data": {
"id": "https://s3.juniortree.com/xiao-x-bao/uploads/2025/09/01/b9cb193906b145939dc3d9cb6240b933.jpg",
"name": "607a919df57e2a8b6a7ab17022cdf663122166603.jpg",
"size": 348514,
"extension": "jpg",
"mime_type": "image/jpeg",
"created_by": "xiaoming",
"created_at": 1756713029
}
}概述
文件上传接口允许用户将文件上传到对象存储服务,支持多种文件类型(图片、文档、音频、视频等)。上传成功后返回文件的访问URL和元数据信息。认证方式
该接口需要以下认证信息:- Agent (Header): 指定使用的Agent名称(必填)
请求参数
Header参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Agent | string | 是 | 指定使用的Agent名称,如:fastgpt、dify |
Body参数 (multipart/form-data)
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| file | binary | 是 | 需要上传的文件,支持多种格式 |
| created_by | string | 是 | 创建者标识,用于记录上传者信息 |
支持的文件类型
- 图片: jpg, jpeg, png, gif, webp, svg
- 文档: pdf, doc, docx, txt, md
- 音频: mp3, wav, ogg, flac
- 视频: mp4, avi, mov, wmv
- 压缩包: zip, rar, 7z
文件大小限制
- 单个文件最大支持:100MB
- 建议文件大小:10MB以下获得最佳体验
响应说明
成功响应 (200)
{
"code": 200,
"msg": "File uploaded successfully",
"data": {
"id": "https://s3.juniortree.com/xiao-x-bao/uploads/2025/09/01/b9cb193906b145939dc3d9cb6240b933.jpg",
"name": "example.jpg",
"size": 348514,
"extension": "jpg",
"mime_type": "image/jpeg",
"created_by": "xiaoming",
"created_at": 1756713029
}
}
响应字段说明
| 字段名 | 类型 | 描述 |
|---|---|---|
| code | integer | 响应状态码,200表示成功 |
| msg | string | 响应消息 |
| data.id | string | 文件访问URL,可直接用于访问上传的文件 |
| data.name | string | 原始文件名 |
| data.size | integer | 文件大小(字节) |
| data.extension | string | 文件扩展名 |
| data.mime_type | string | 文件MIME类型 |
| data.created_by | string | 上传者标识 |
| data.created_at | integer | 上传时间戳(Unix时间戳) |
使用示例
使用curl上传文件
curl -X POST 'http://localhost:3000/api/v1/upload' \
-H 'Agent: fastgpt' \
-F 'file=@/path/to/your/file.jpg' \
-F 'created_by=user123'
使用Python上传文件
import requests
url = 'http://localhost:3000/api/v1/upload'
headers = {
'Agent': 'fastgpt'
}
files = {
'file': open('document.pdf', 'rb')
}
data = {
'created_by': 'python_user'
}
response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
print(f"文件上传成功!访问URL: {result['data']['id']}")
print(f"文件大小: {result['data']['size']} bytes")
使用JavaScript上传文件
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('created_by', 'web_user');
fetch('http://localhost:3000/api/v1/upload', {
method: 'POST',
headers: {
'Agent': 'dify'
},
body: formData
})
.then(response => response.json())
.then(data => {
console.log('上传成功:', data.data.id);
})
.catch(error => {
console.error('上传失败:', error);
});
错误处理
常见错误码
| 错误码 | 描述 | 解决方案 |
|---|---|---|
| 400 | 参数错误 | 检查必填参数是否完整,文件是否为空 |
| 413 | 文件过大 | 压缩文件或分批上传 |
| 415 | 不支持的文件类型 | 检查文件扩展名是否在支持列表中 |
| 500 | 服务器错误 | 稍后重试或联系技术支持 |
错误响应示例
{
"code": 400,
"msg": "Missing required parameter: file",
"detail": "请确保上传了文件"
}
最佳实践
1. 文件命名规范
- 使用有意义的文件名,避免特殊字符
- 建议使用英文命名,避免中文乱码问题
- 文件名长度控制在50个字符以内
2. 上传前检查
- 验证文件大小是否符合要求
- 检查文件类型是否在支持列表中
- 确保网络连接稳定
3. 安全性建议
- 不要上传包含敏感信息的文件
- 定期清理不需要的文件
- 使用HTTPS协议进行上传
4. 性能优化
- 对于大文件,考虑使用分片上传
- 压缩图片文件以减少传输时间
- 避免同时上传多个大文件
使用场景
1. 聊天文件分享
用户可以在聊天中上传图片、文档等文件,AI可以基于上传的文件内容进行回复。2. 知识库构建
上传文档到知识库,供AI系统学习和回答相关问题。3. 多媒体处理
上传音频、视频文件进行转录、分析或其他AI处理。注意事项
上传的文件将存储在云端,请确保不包含敏感或隐私信息。
文件URL有效期为永久,除非手动删除。建议定期清理不需要的文件以节省存储空间。
对于需要频繁访问的文件,建议缓存文件URL以提高访问速度。
