POST/api/v3/upload

上传图片（V3）

上传单张图片到图床，支持相册、去重、水印和压缩参数。

接口信息

项目	说明
接口地址	`POST /api/v3/upload`
请求类型	`multipart/form-data`
鉴权	`Authorization: Bearer sk-xxx`

请求头

字段	值格式	必填	说明
Authorization	`Bearer <token>`	是	开放接口 Token，在控制台 → 开放接口获取，`sk-` 开头

请求体

字段	类型	必填	说明
file	file	是	图片文件，支持 JPG、PNG、GIF、BMP、WebP、ICO
params	string	否	额外参数，JSON 字符串，默认 `{}`

params 支持以下字段：

字段	类型	默认值	说明
dedup	bool	`true`	是否按内容去重；同一账号重复上传同一张图时直接返回已有结果
album_id	int	`0`	相册 ID，`0` 表示默认相册；相册必须属于当前账号
watermark	bool	`false`	是否加文字水印，需要在账号设置里开启水印并设置文字，仅部分套餐可用
compress	bool	`false`	是否压缩图片

params 示例：

{
  "dedup": true,
  "album_id": 0,
  "watermark": false,
  "compress": false
}

请求示例

cURL

curl --location --request POST 'https://www.imgurl.org/api/v3/upload' \
--header 'Authorization: Bearer sk-xxx' \
--form 'file=@"/path/to/image.jpg"' \
--form 'params="{\"album_id\":0,\"dedup\":true}"'

Python

import requests

url = "https://www.imgurl.org/api/v3/upload"
headers = {
    "Authorization": "Bearer sk-xxx"
}
files = {
    "file": open("/path/to/image.jpg", "rb")
}
data = {
    "params": '{"dedup": true}'
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "imgid": "vzB3OYiy",
    "path": "2026/01/19/vzB3OYiy.jpg",
    "url": "https://www.imgurl.org/2026/01/19/vzB3OYiy.jpg",
    "thumbnail_url": "https://www.imgurl.org/e8IhefQs3Jv3klW9DubaeTypYkGUm/rs:fill:120:90/g:sm/f:webp/aHR0cHM6Ly8...",
    "width": 552,
    "height": 344,
    "filename": "cUun5b1G.jpg",
    "size": 30615
  }
}

字段	类型	说明
imgid	string	图片唯一 ID（8 位，大小写字母 + 数字）
path	string	存储路径（含日期目录）
url	string	原图公开访问地址
thumbnail_url	string	缩略图地址
width	int	图片宽度（像素）
height	int	图片高度（像素）
filename	string	存储后的文件名
size	int	文件大小（字节）

失败响应

{
  "code": -1000,
  "msg": "invalid.token",
  "data": null
}

msg	说明
invalid.token	Token 缺失、格式不对、已禁用或已过期
no.sub	账号没有有效套餐
Exceeds the maximum size limit of xMB	文件超过套餐单张上限
unsupported.image.format	不是受支持的图片格式
invalid.image	图片已损坏、无法解码或宽高读取失败
image.too.small	图片尺寸过小，宽或高小于 8 像素
image.too.large	图片尺寸超出限制（单边超过 30000 像素或总像素超过 1 亿）
storage.quota.limit	存储空间已满
daily.limit.exceeded / monthly.limit.exceeded	达到每日或每月上传次数
invalid.album	相册不存在或不属于当前账号
invalid.params	`params` 不是合法 JSON
upload.too.frequent	触发频率限制，HTTP 状态码为 429

完整错误码见总览。