图片上传与管理（Image Upload & Management）

上传本地图片到妙图云存储，获取访问 URL，用于后续图像处理任务。上传的图片以内容记录形式管理，可列出和删除。

设计说明

妙图 OpenAPI 将用户的图片视为**内容（Content）**而非原始文件。每次上传都会产生一个 图片 ID（id）和可访问的 URL。

• 图像处理任务（抠图、风格转换、高清放大等）通过 URL 引用图片
• 通过 ID 可列出历史上传、按 ID 删除

提示

多数图像处理接口支持直接使用 公网 URL，只有当图像无法通过公网访问时才需要先上传。

---

基本信息

接口	路径	Scope
上传图片	POST /images/upload	*
查询图片列表	GET /images/page	*
删除图片	DELETE /images/{id}	*

---

上传图片

请求

路径：POST /images/upload
Content-Type：multipart/form-data

参数	类型	必填	说明
file	File	是	图片文件（支持 JPEG、PNG、WebP、SVG）
title	string	否	图片标题，默认使用原始文件名

响应

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 1024,
    "url": "https://img.magiqsight.com/files/42/image_abc123.png",
    "width": 1920,
    "height": 1080,
    "title": "product.png",
    "createTime": "2026-06-03T10:00:00"
  }
}

字段	说明
id	图片内容 ID，用于列出和删除
url	图片访问 URL，用于图像处理任务
width / height	图片尺寸（像素），SVG 可能为 0
createTime	上传时间

请求示例

curl

curl -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -F "file=@/path/to/product.png" \
  -F "title=商品主图" \
  "https://magiqsight.com/openapi/v1/images/upload"

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

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）

响应

{
  "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": "2026-06-03T10:00:00"
      }
    ]
  }
}

请求示例

curl -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  "https://magiqsight.com/openapi/v1/images/page?pageNo=1&pageSize=20"

---

删除图片

路径：DELETE /images/{id}

参数	位置	说明
id	路径参数	图片内容 ID（上传时返回的 id）

响应

{
  "code": 0,
  "msg": "成功",
  "data": true
}

请求示例

curl -X DELETE \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  "https://magiqsight.com/openapi/v1/images/1024"

---

完整工作流示例

上传图片并提交抠图任务：

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()
  task = resp.json()["data"]
  status = task["status"]
  if status == 1:
    result_url = task["imageUrls"][0]
        print(f"抠图完成：{result_url}")
        break
  elif 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("原图已删除")

---

注意事项

文件限制

项目	限制
单文件最大	20 MB
建议分辨率	不超过 4096×4096 像素
支持格式	JPEG、PNG、WebP、SVG

存储与隐私

• 上传的图片存储在用户私有空间，其他用户无法访问
• 文件长期保存，不会自动过期
• 返回的 URL 可直接用于所有图像处理接口
• 建议定期通过删除接口清理不再使用的图片

---

错误代码

code	说明
400	请求参数错误（文件为空、格式不支持等）
401	未授权，令牌无效或过期
429	请求频率超限，请降低速率后重试

---

限流策略

• 速率限制：每秒最多 10 次请求
• 超出后返回 429 Too Many Requests，请使用指数退避重试

---

相关接口

• 抠图 — 使用上传图片进行前景分离
• 转绘 — 将照片转换为艺术风格
• 高清放大 — 提升图片分辨率
• 任务查询 — 查询异步任务的处理状态