curl --request POST \
--url https://api.poyo.ai/api/common/upload/url \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"file_url": "https://example.com/images/sample.jpg"
}
'{
"success": true,
"code": 200,
"msg": "File uploaded successfully",
"data": {
"file_id": "1bdfdbac6ebc2228d0b398d728bf4699",
"file_name": "test-image.png",
"original_name": "image-from-url.png",
"file_size": 1419815,
"mime_type": "image/png",
"upload_path": "temp/test-uploads",
"file_url": "https://storage.poyo.ai/temp/test-uploads/test-image.png",
"download_url": "https://storage.poyo.ai/temp/test-uploads/test-image.png",
"upload_time": "2025-12-29T13:08:57.673515",
"expires_at": "2026-01-01T13:08:57.673515"
}
}文件管理
通过 URL 上传文件
提供远程 URL，将文件上传到 PoYo AI
POST
/
api
/
common
/
upload
/
url
curl --request POST \
--url https://api.poyo.ai/api/common/upload/url \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"file_url": "https://example.com/images/sample.jpg"
}
'{
"success": true,
"code": 200,
"msg": "File uploaded successfully",
"data": {
"file_id": "1bdfdbac6ebc2228d0b398d728bf4699",
"file_name": "test-image.png",
"original_name": "image-from-url.png",
"file_size": 1419815,
"mime_type": "image/png",
"upload_path": "temp/test-uploads",
"file_url": "https://storage.poyo.ai/temp/test-uploads/test-image.png",
"download_url": "https://storage.poyo.ai/temp/test-uploads/test-image.png",
"upload_time": "2025-12-29T13:08:57.673515",
"expires_at": "2026-01-01T13:08:57.673515"
}
}使用指南
- 该接口通过提供远程 URL 将文件上传到 PoYo AI
- 系统会自动从指定 URL 下载文件，并存储到 PoYo AI 存储中
- 适合从外部服务器迁移文件，或对接第三方文件来源
- 返回文件的直接访问 URL，文件保留 72 小时
参数详情
-
文件 URL 要求：
-
file_url必须是使用 HTTP 或 HTTPS 协议的公开可访问 URL - 远程服务器必须允许无需认证即可下载该文件
- 支持的文件格式：仅 JPEG、PNG、GIF、WebP
- 上传数量上限：每次请求 1 张图片
-
-
存储配置：
-
所有文件在存储路径中都会自动加上
temp/前缀 -
如果指定
upload_path: "avatars"，实际路径为temp/avatars - 文件在上传 72 小时后过期并自动删除
-
所有文件在存储路径中都会自动加上
-
文件命名：
-
如果未提供
file_name，系统会按以下格式生成唯一文件名：{timestamp}_{random}_{extension} -
自动生成的文件名示例：
20251229130857_a8B9cD2e.png
-
如果未提供
开发者说明
- 确保源 URL 公开可访问，且不需要认证或特殊请求头
- 下载过程可能需要几秒钟，取决于文件大小和网络状况
- 如需持久保存，请在 72 小时过期前将文件下载到本地
-
响应中的
file_url和download_url完全相同，都可以直接访问已上传的文件
速率限制与配额
- 速率限制：每个已认证用户、每个上传接口，在 60 秒固定窗口内最多 10 次请求
-
超出速率限制时，会收到
429 Too Many Requests错误 - 固定窗口从窗口内第一次请求开始计算，同一用户的 JWT 请求和 API Key 请求共享该窗口
- 使用指数退避重试逻辑处理速率限制错误
常见错误场景
- URL 无效：提供的 URL 格式错误或无法访问
- 下载失败：从远程 URL 下载时出现网络超时或连接问题
- 不支持的文件类型：URL 指向的文件不是支持的图片格式（JPEG、PNG、GIF、WebP）
- 认证错误：Authorization 请求头中的 API Key 缺失或无效
授权
所有 API 接口都需要 Bearer Token 认证。
创建 API Key：登录 PoYo，进入 仪表盘 → API 密钥（poyo.ai/zh/dashboard/api-key），点击创建 Key。
在请求头中添加：
Authorization: Bearer YOUR_API_KEY
请求体
application/json
要上传的远程文件 URL。
必须是使用 HTTP 或 HTTPS 协议、可公开访问的 URL。
支持的格式：JPEG、PNG、GIF、WebP
注意：系统会从该 URL 下载文件并存储到 PoYo AI 存储中。
示例:
"https://example.com/images/sample.jpg"
自定义存储目录路径。
未指定时，系统会自动对文件分类。
注意：无论指定什么路径，所有文件都会以 temp/ 前缀存储。
示例:
"avatars"
上传文件的自定义文件名。
未指定时，系统会按以下格式生成唯一文件名：{timestamp}_{random}_{extension}
自动生成的文件名示例：20251229130857_a8B9cD2e.png
示例:
"my-custom-image.png"
响应
文件上传成功
上传是否成功
示例:
true
响应消息
示例:
"File uploaded successfully"
Show child attributes
Show child attributes