图像生成服务集成说明

概述

本系统已集成第三方图像生成模型，支持文生图和图片编辑（图生图）功能。

系统支持两个模型服务：

• 图像生成服务：异步接口，支持任务状态轮询
• API 聚合服务：同步接口，第三方标准格式

任务类型

系统提供两个任务类型：

配置信息

任务类型配置

• 任务类型ID: 25
• 任务Key: image_model
• 显示名称: 图像生成（文生图）
• 分类: 文生图 (text_to_image)
• 模型服务: 图像生成服务
• 算力: 按实际使用量计费，具体定价以产品页为准

支持的参数

分辨率和比例映射

系统支持 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}
• 请求体:

{
    "model": "<第三方图像生成模型标识>",
    "prompt": "图片描述文本",
    "size": "1:1"
}

• 参考图支持（可选）:

{
    "model": "<第三方图像生成模型标识>",
    "prompt": "图片描述文本",
    "size": "1:1",
    "image": ["https://example.com/ref.png"]
}

2. 查询任务状态

• URL: GET <图像生成服务地址>/v1/tasks/{id}
• 认证: Header Authorization: {token}
• 响应:

{
    "id": "task-id",
    "state": "succeeded",
    "data": {
        "images": [
            {"url": "https://...", "file_name": "output.png"}
        ]
    },
    "progress": 100
}

状态映射

API 聚合服务站点

系统支持 6 个 API 聚合服务站点：

• 基类: 聚合站点通用驱动
• 文件位置: task/visual_drivers/（聚合站点驱动文件）
• 接口类型: 同步接口

API 接口

1. 文生图

• URL: POST {base_url}/v1/images/generations
• 认证: Header Authorization: Bearer {api_key}
• Content-Type: application/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: 图片尺寸

POST /v1/images/edits
Content-Type: multipart/form-data

image: [文件上传]
prompt: "将他们合并在一个图片里面"
model: "<第三方图像生成模型标识>"
n: 1
size: "1024x1536"

比例映射

配置要求

必需配置

使用图像生成服务时，需要在系统配置中设置第三方服务配置项（详见配置文件）：

# 第三方服务配置项（详见配置文件）
image_service:
  api_key: "your_api_key"

API 聚合服务站点配置

使用 API 聚合服务站点时，需要在系统配置中设置：

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：

{
    "type": 25,
    "prompt": "a beautiful sunset over the ocean",
    "ratio": "1:1"
}

2. 图片编辑/图生图（type=26）

通过标准 AI 工具接口提交任务，指定 type=26，并传入参考图：

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