# AI生图后端API文档 V0.1

## 基础信息

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

## 统一响应格式

```json
{
  "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 | 负面提示词，描述不想出现的内容 |

#### 请求示例

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

#### 响应示例

```json
{
  "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
  }
}
```

#### 错误响应示例

```json
{
  "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 | 图片尺寸 |

#### 响应示例

```json
{
  "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`

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

#### 请求参数

无参数

#### 响应示例

```json
{
  "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`

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

#### 请求参数

无参数

#### 响应示例

```json
{
  "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 | 每页数量 |

#### 响应示例

```json
{
  "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失败 |

---

## 前端对接示例

### 文生图调用

```javascript
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);
}
```

### 图生图调用

```javascript
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);
}
```

### 获取历史记录

```javascript
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`