主题
图片上传与管理(Image Upload & Management)
上传本地图片到妙图云存储,获取访问 URL,用于后续图像处理任务。上传的图片以内容记录形式管理,可列出和删除。
设计说明
妙图 OpenAPI 将用户的图片视为**内容(Content)**而非原始文件。每次上传都会产生一个 图片 ID(id)和可访问的 URL。
- 图像处理任务(抠图、风格转换、高清放大等)通过 URL 引用图片
- 通过 ID 可列出历史上传、按 ID 删除
提示
多数图像处理接口支持直接使用 公网 URL,只有当图像无法通过公网访问时才需要先上传。
基本信息
| 接口 | 路径 | Scope |
|---|---|---|
| 上传图片 | POST /images/upload | upload 或 * |
| 查询图片列表 | GET /images/page | page 或 * |
| 删除图片 | DELETE /images/{id} | * |
上传图片
请求
路径:POST /images/upload
Content-Type:multipart/form-data
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | File | 是 | 图片文件(支持 JPEG、PNG、WebP、SVG) |
title | string | 否 | 图片标题,默认使用原始文件名 |
响应
json
{
"code": 0,
"msg": "",
"data": {
"id": 1024,
"url": "https://img.magiqsight.com/files/42/image_abc123.png",
"width": 1920,
"height": 1080,
"title": "product.png",
"createTime": 1748944800000
}
}| 字段 | 说明 |
|---|---|
id | 图片内容 ID,用于列出和删除 |
url | 图片访问 URL。持有链接即可直接获取,用于图像处理任务 |
width / height | 图片尺寸(像素),SVG 可能为 0 |
createTime | 上传时间,Unix 毫秒时间戳 |
请求示例
curl
bash
curl -X POST \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
-F "file=@/path/to/product.png;type=image/png" \
-F "title=商品主图" \
"https://magiqsight.com/openapi/v1/images/upload"Python
python
import requests
url = "https://magiqsight.com/openapi/v1/images/upload"
headers = {"Authorization": f"Bearer {api_token}"}
with open("product.png", "rb") as f:
files = {"file": ("product.png", f, "image/png")}
data = {"title": "商品主图"}
response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
if result["code"] == 0:
image_id = result["data"]["id"]
image_url = result["data"]["url"]
print(f"上传成功:id={image_id}, url={image_url}")Node.js
javascript
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');
const form = new FormData();
form.append('file', fs.createReadStream('product.png'));
form.append('title', '商品主图');
const res = await axios.post(
'https://magiqsight.com/openapi/v1/images/upload',
form,
{
headers: {
...form.getHeaders(),
'Authorization': `Bearer ${process.env.TUSEN_API_TOKEN}`
}
}
);
const { id, url } = res.data.data;
console.log(`上传成功:id=${id}, url=${url}`);查询图片列表
路径:GET /images/page
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pageNo | integer | 1 | 页码 |
pageSize | integer | 20 | 每页数量(最大 100) |
响应
json
{
"code": 0,
"msg": "",
"data": {
"total": 5,
"list": [
{
"id": 1024,
"url": "https://img.magiqsight.com/files/42/image_abc123.png",
"width": 1920,
"height": 1080,
"title": "product.png",
"createTime": 1748944800000
}
]
}
}请求示例
bash
curl -H "Authorization: Bearer $TUSEN_API_TOKEN" \
"https://magiqsight.com/openapi/v1/images/page?pageNo=1&pageSize=20"删除图片
路径:DELETE /images/{id}
| 参数 | 位置 | 说明 |
|---|---|---|
id | 路径参数 | 图片内容 ID(上传时返回的 id) |
响应
json
{
"code": 0,
"msg": "",
"data": true
}请求示例
bash
curl -X DELETE \
-H "Authorization: Bearer $TUSEN_API_TOKEN" \
"https://magiqsight.com/openapi/v1/images/1024"完整工作流示例
上传图片并提交抠图任务:
python
import requests
import time
BASE = "https://magiqsight.com/openapi/v1"
headers = {"Authorization": f"Bearer {api_token}"}
# 1. 上传图片
with open("product.jpg", "rb") as f:
resp = requests.post(f"{BASE}/images/upload",
headers=headers,
files={"file": ("product.jpg", f, "image/jpeg")})
resp.raise_for_status()
image = resp.json()["data"]
image_url = image["url"]
image_id = image["id"]
print(f"上传成功:id={image_id}")
# 2. 提交抠图任务
resp = requests.post(f"{BASE}/image/matting",
headers=headers,
json={"url": image_url})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"任务已提交:taskId={task_id}")
# 3. 轮询任务结果
for _ in range(60):
resp = requests.get(f"{BASE}/tasks/{task_id}", headers=headers)
resp.raise_for_status()
body = resp.json()
if body.get("code") != 0:
print(f"查询失败:code={body.get('code')}, msg={body.get('msg')}")
break
task = body["data"]
status = task["status"]
if status == 1:
result_url = task["imageUrls"][0]
print(f"抠图完成:{result_url}")
break
if status in (2, 3):
print(f"任务结束:status={status}, resultMetadata={task.get('resultMetadata')}")
break
time.sleep(2)
# 4. 清理:删除原图
requests.delete(f"{BASE}/images/{image_id}", headers=headers)
print("原图已删除")注意事项
文件要求
请求里文件部分的 Content-Type 必须以 image/ 开头。curl 请写成 file=@路径;type=image/png(或对应类型),不要依赖默认的 application/octet-stream。空文件的 msg 是「文件不能为空」;类型不被接受时 msg 是「仅支持图片格式(JPEG、PNG、WebP、SVG)」。这两种都是 HTTP 200、code 400。
访问
返回的 url 只要持有链接即可直接访问,可交给图像处理接口使用。
错误代码
成功时 code 为 0,msg 为 ""。
| code | HTTP 状态 | 说明 |
|---|---|---|
400 | 200 | 文件为空,或 Content-Type 不是 image/* |
401 | 401 | 未登录。msg 为「账号未登录」 |
403 | 403 | 令牌没有 upload、page 或删除所需的 * |
429 | 429 | 超过该令牌的每分钟次数上限。msg 为「请求过于频繁,请稍后重试」,并带 Retry-After |
删除别人的图片或不存在的图片时,HTTP 仍是 200,code 为 400,msg 为「图片不存在」。频率限制与其他接口共用同一令牌配额,见积分与限速。
