Skip to content

图片上传与管理(Image Upload & Management) ​

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

设计说明 ​

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

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

提示

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


基本信息 ​

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

上传图片 ​

请求 ​

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

参数类型必填说明
fileFile是图片文件(支持 JPEG、PNG、WebP、SVG)
titlestring否图片标题,默认使用原始文件名

响应 ​

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

参数类型默认值说明
pageNointeger1页码
pageSizeinteger20每页数量(最大 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 为 ""。

codeHTTP 状态说明
400200文件为空,或 Content-Type 不是 image/*
401401未登录。msg 为「账号未登录」
403403令牌没有 upload、page 或删除所需的 *
429429超过该令牌的每分钟次数上限。msg 为「请求过于频繁,请稍后重试」,并带 Retry-After

删除别人的图片或不存在的图片时,HTTP 仍是 200,code 为 400,msg 为「图片不存在」。频率限制与其他接口共用同一令牌配额,见积分与限速。


相关接口 ​

妙图设计 API Beta