Maas-Model-platform/docs/inside/API/MD004_AI生图/MD004_AI生图后端API_V0.1.md

AI生图后端API文档 V0.1

基础信息

• Base URL: http://localhost:8000
• API前缀: /api/image
• 认证方式: 需要用户登录，使用用户配置的apikey调用百炼平台

统一响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

字段	类型	说明
code	int	状态码：200成功，400参数错误，403未配置apikey，500服务器错误
message	string	响应消息
data	object	响应数据

---

接口列表

1. 文生图接口

POST /api/image/text-to-image

根据文本提示词生成图片，支持多种模型和尺寸。

请求头

参数	类型	必填	说明
Content-Type	string	是	application/json
Authorization	string	是	Bearer {token}

请求体

参数	类型	必填	默认值	说明
prompt	string	是	-	文本提示词，描述想要生成的图片内容
model	string	否	wanx2.1-t2i-turbo	模型名称
n	int	否	1	生成图片数量，范围1-4
size	string	否	1024*1024	图片尺寸
negative_prompt	string	否	null	负面提示词，描述不想出现的内容

请求示例

{
  "prompt": "一只可爱的橘猫在阳光下睡觉",
  "model": "wanx2.1-t2i-turbo",
  "n": 2,
  "size": "1024*1024",
  "negative_prompt": "模糊，低质量"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "success": true,
    "images": [
      "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/images/20250629/abc123.png",
      "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/images/20250629/def456.png"
    ],
    "bill": "0.14",
    "record_id": 1
  }
}

错误响应示例

{
  "code": 403,
  "message": "未配置API密钥，请在用户设置中配置apikey",
  "data": null
}

---

2. 图生图接口

POST /api/image/image-to-image

根据参考图片和文本提示词生成新图片。

请求头

参数	类型	必填	说明
Content-Type	string	是	multipart/form-data
Authorization	string	是	Bearer {token}

请求参数（Form Data）

参数	类型	必填	默认值	说明
image	file	是	-	参考图片文件
prompt	string	是	-	文本提示词
model	string	否	wanx2.1-imageedit	模型名称
n	int	否	1	生成图片数量，范围1-4
size	string	否	1024*1024	图片尺寸

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "success": true,
    "images": [
      "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/images/20250629/xyz789.png"
    ],
    "bill": "0.07",
    "record_id": 2
  }
}

---

3. 获取文生图模型列表

GET /api/image/text-to-image/models

获取所有可用的文生图模型列表。

请求参数

无参数

响应示例

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "model_id": "wanx2.1-t2i-turbo",
      "model_name": "通义万相-文生图-Turbo",
      "description": "高速文生图模型",
      "price_per_image": "0.07",
      "supported_sizes": ["512*512", "768*768", "1024*1024", "1280*720", "720*1280"]
    },
    {
      "model_id": "wanx2.1-t2i-plus",
      "model_name": "通义万相-文生图-Plus",
      "description": "高质量文生图模型",
      "price_per_image": "0.14",
      "supported_sizes": ["512*512", "768*768", "1024*1024", "1280*720", "720*1280"]
    }
  ]
}

---

4. 获取图生图模型列表

GET /api/image/image-to-image/models

获取所有可用的图生图模型列表。

请求参数

无参数

响应示例

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "model_id": "wanx2.1-imageedit",
      "model_name": "通义万相-图像编辑",
      "description": "图生图编辑模型",
      "price_per_image": "0.07",
      "supported_sizes": ["512*512", "768*768", "1024*1024"]
    }
  ]
}

---

5. 获取历史记录

GET /api/image/history

获取当前用户的图片生成历史记录，支持分页。

请求参数

参数	类型	必填	默认值	说明
page	int	否	1	页码
page_size	int	否	20	每页数量

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "model_name": "wanx2.1-t2i-turbo",
        "input_type": "text",
        "input_data": "{\"prompt\": \"一只可爱的橘猫\", \"negative_prompt\": null}",
        "image_count": 2,
        "output_images": [
          "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/images/20250629/abc123.png",
          "https://your-bucket.oss-cn-hangzhou.aliyuncs.com/images/20250629/def456.png"
        ],
        "bill": "0.14",
        "created_at": "2025-06-29T10:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

---

数据字段说明

TextToImageResponse 字段

字段	类型	说明
success	bool	是否成功
images	array	OSS图片URL列表
bill	decimal	本次生成费用
record_id	int	生成记录ID
error	string	错误信息（失败时）

ImageModelInfo 字段

字段	类型	说明
model_id	string	模型ID，用于API调用
model_name	string	模型显示名称
description	string	模型描述
price_per_image	decimal	每张图片价格（元）
supported_sizes	array	支持的图片尺寸列表

ImageHistoryItem 字段

字段	类型	说明
id	int	记录ID
model_name	string	使用的模型名称
input_type	string	输入类型：text（文生图）、image（图生图）
input_data	string	输入数据JSON
image_count	int	生成图片数量
output_images	array	输出图片URL列表
bill	decimal	费用
created_at	datetime	创建时间

---

错误码说明

错误码	HTTP状态码	说明
NO_API_KEY	403	用户未配置API密钥
INVALID_PROMPT	400	提示词为空或无效
INVALID_MODEL	400	无效的模型名称
INVALID_SIZE	400	不支持的图片尺寸
INVALID_COUNT	400	图片数量超出范围(1-4)
GENERATION_FAILED	400	图片生成失败
UPLOAD_FAILED	500	图片上传OSS失败

---

前端对接示例

文生图调用

const response = await fetch('http://localhost:8000/api/image/text-to-image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    prompt: '一只可爱的橘猫在阳光下睡觉',
    model: 'wanx2.1-t2i-turbo',
    n: 2,
    size: '1024*1024'
  })
});

const data = await response.json();
if (data.code === 200) {
  console.log('生成的图片:', data.data.images);
  console.log('费用:', data.data.bill);
}

图生图调用

const formData = new FormData();
formData.append('image', imageFile);
formData.append('prompt', '将图片风格转换为油画');
formData.append('model', 'wanx2.1-imageedit');
formData.append('n', '1');

const response = await fetch('http://localhost:8000/api/image/image-to-image', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const data = await response.json();
if (data.code === 200) {
  console.log('生成的图片:', data.data.images);
}

获取历史记录

const response = await fetch('http://localhost:8000/api/image/history?page=1&page_size=10', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();
if (data.code === 200) {
  console.log('历史记录:', data.data.items);
  console.log('总数:', data.data.total);
}

---

在线文档

启动服务后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc