图像生成服务集成

<title>图像生成服务集成</title>

# 图像生成服务集成说明

## 概述

本系统已集成第三方图像生成模型，支持文生图和图片编辑（图生图）功能。

系统支持两个模型服务：

- **图像生成服务**：异步接口，支持任务状态轮询
- **API 聚合服务**：同步接口，第三方标准格式

## 任务类型

系统提供两个任务类型：

| 任务类型 | ID | Key | 功能说明 |
|-|-|-|-|
| 文生图 | 25 | `image_model` | 纯文本生成图片 |
| 图片编辑 | 26 | `image_model_edit` | 基于参考图编辑图片 |

## 配置信息

### 任务类型配置

- **任务类型ID**: 25
- **任务Key**: `image_model`
- **显示名称**: 图像生成（文生图）
- **分类**: 文生图 (text_to_image)
- **模型服务**: 图像生成服务
- **算力**: 按实际使用量计费，具体定价以产品页为准

### 支持的参数

| 参数 | 支持值 | 说明 |
|-|-|-|
| supported_sizes | `['1k', '2k', '4k']` | 支持 1K、2K、4K 分辨率 |
| supported_ratios | `['1:1', '2:3', '3:2', '16:9', '9:16']` | 支持的比例 |
| supports_grid_merge | `False` | 不支持宫格合并 |
| supports_grid_image | `True` | 支持宫格生图 |

### 分辨率和比例映射

系统支持 1K、2K、4K 三种分辨率，每种分辨率下支持多种比例：

#### 1K 分辨率

- `1:1` -> `1024x1024` (正方形)
- `3:2` -> `1536x1024` (横版)
- `2:3` -> `1024x1536` (竖版)
- `16:9` -> `1536x1024` (横版)
- `9:16` -> `1024x1536` (竖版)

#### 2K 分辨率

- `1:1` -> `2048x2048` (正方形)
- `3:2` -> `2048x1152` (横版)
- `2:3` -> `1152x2048` (竖版)
- `16:9` -> `2048x1152` (横版)
- `9:16` -> `1152x2048` (竖版)

#### 4K 分辨率

- `1:1` -> `2048x2048` (正方形)
- `3:2` -> `3840x2160` (横版)
- `2:3` -> `2160x3840` (竖版)
- `16:9` -> `3840x2160` (横版)
- `9:16` -> `2160x3840` (竖版)

## 驱动实现

### 驱动

- **对应驱动**: 图像生成服务异步驱动
- **文件位置**: `task/visual_drivers/`（图像生成服务驱动文件）
- **服务类型标识**: `image_service_v1`

### API 接口

#### 1. 提交任务

- **URL**: `POST <图像生成服务地址>/v1/images/generations`
- **认证**: Header `Authorization: {token}`
- **请求体**:

```JSON
{
    "model": "<第三方图像生成模型标识>",
    "prompt": "图片描述文本",
    "size": "1:1"
}
```

- **参考图支持**（可选）:

```JSON
{
    "model": "<第三方图像生成模型标识>",
    "prompt": "图片描述文本",
    "size": "1:1",
    "image": ["https://example.com/ref.png"]
}
```

#### 2. 查询任务状态

- **URL**: `GET <图像生成服务地址>/v1/tasks/{id}`
- **认证**: Header `Authorization: {token}`
- **响应**:

```JSON
{
    "id": "task-id",
    "state": "succeeded",
    "data": {
        "images": [
            {"url": "https://...", "file_name": "output.png"}
        ]
    },
    "progress": 100
}
```

### 状态映射

| API 状态 | 系统状态 | 说明 |
|-|-|-|
| `pending` | RUNNING | 队列中 |
| `running` | RUNNING | 生成中 |
| `succeeded` | SUCCESS | 成功 |
| `error` | FAILED | 失败 |

### API 聚合服务站点

系统支持 6 个 API 聚合服务站点：

| 站点 | 服务类型标识 | 驱动 | 配置依赖 |
|-|-|-|-|
| Site 0 (固定) | `image_site0_v1` | 对应驱动 | api_aggregator.site_0 |
| Site 1 | `image_site1_v1` | 对应驱动 | api_aggregator.site_1 |
| Site 2 | `image_site2_v1` | 对应驱动 | api_aggregator.site_2 |
| Site 3 | `image_site3_v1` | 对应驱动 | api_aggregator.site_3 |
| Site 4 | `image_site4_v1` | 对应驱动 | api_aggregator.site_4 |
| Site 5 | `image_site5_v1` | 对应驱动 | api_aggregator.site_5 |

- **基类**: 聚合站点通用驱动
- **文件位置**: `task/visual_drivers/`（聚合站点驱动文件）
- **接口类型**: 同步接口

#### API 接口

##### 1. 文生图

- **URL**: `POST {base_url}/v1/images/generations`
- **认证**: Header `Authorization: Bearer {api_key}`
- **Content-Type**: `application/json`
- **请求体**:

```JSON
{
    "model": "<第三方图像生成模型标识>",
    "prompt": "图片描述文本",
    "n": 1,
    "size": "1024x1024"
}
```

##### 2. 图片编辑

- **URL**: `POST {base_url}/v1/images/edits`
- **认证**: Header `Authorization: Bearer {api_key}`
- **Content-Type**: `multipart/form-data`
- **表单字段**:

  - `image`: 图片文件（必需，支持多张）
  - `prompt`: 文本描述（必需）
  - `model`: 模型名称
  - `n`: 生成数量
  - `size`: 图片尺寸

```Plaintext
POST /v1/images/edits
Content-Type: multipart/form-data

image: [文件上传]
prompt: "将他们合并在一个图片里面"
model: "<第三方图像生成模型标识>"
n: 1
size: "1024x1536"
```

#### 比例映射

| 前端比例 | 第三方标准尺寸 |
|-|-|
| `1:1` | `1024x1024` |
| `3:2` / `16:9` | `1536x1024` (横版) |
| `2:3` / `9:16` | `1024x1536` (竖版) |

## 配置要求

### 必需配置

使用图像生成服务时，需要在系统配置中设置第三方服务配置项（详见配置文件）：

```YAML
# 第三方服务配置项（详见配置文件）
image_service:
  api_key: "your_api_key"
```

### API 聚合服务站点配置

使用 API 聚合服务站点时，需要在系统配置中设置：

```YAML
api_aggregator:
  site_0:
    base_url: "<官方地址>"
    api_key: "your_api_key"
    name: "智剧通官方API"
  site_1:
    base_url: "<官方地址>"
    api_key: "your_api_key"
    name: "聚合站点 1"
  site_2:
    base_url: "<官方地址>"
    api_key: "your_api_key"
    name: "聚合站点 2"
  # site_3, site_4, site_5 根据需要配置
```

### 配置验证

启动时会验证以下配置：

- 图像生成服务 API Key 必须存在且不为空（使用图像生成服务时）
- `api_aggregator.site_X.api_key` 和 `api_aggregator.site_X.base_url` 必须存在且不为空（使用 API 聚合服务时）

## 使用方式

### 1. 文生图（type=25）

通过标准 AI 工具接口提交任务，指定 `type=25`：

```JSON
{
    "type": 25,
    "prompt": "a beautiful sunset over the ocean",
    "ratio": "1:1"
}
```

### 2. 图片编辑/图生图（type=26）

通过标准 AI 工具接口提交任务，指定 `type=26`，并传入参考图：

```JSON
{
    "type": 26,
    "prompt": "an island near sea, with seagulls, moon shining over the sea",
    "ratio": "2:3",
    "image_path": "https://example.com/ref.png"
}
```

**注意**：`image_path` 参数支持：

- 单张图片 URL
- 多张图片 URL 用逗号分隔（如需要）
- 本地图片路径（自动上传到 CDN）

### 支持的比例值

- `1:1` - 正方形
- `2:3` - 竖版
- `3:2` - 横版
- `16:9` - 映射为 3:2 (横版)
- `9:16` - 映射为 2:3 (竖版)

## 错误处理

驱动实现了完整的错误处理和报警机制：

1. **网络异常**: 返回可重试错误，用户可稍后重试
2. **API 格式错误**: 发送报警通知，返回系统错误
3. **未知异常**: 记录完整堆栈，发送报警

## 相关文件

- 配置文件: `config/unified_config.py`
- 驱动文件: `task/visual_drivers/`（图像生成服务驱动文件）
- 工厂注册: `task/visual_drivers/driver_factory.py`
- 常量定义: `config/constant.py`