AI图像生成前端对接文档

本文档基于当前代码实际行为整理，已按以下依据核对：

表结构迁移文件
前端接口控制器
场景后台配置逻辑

适用于 H5 / 小程序前端联调。

1. 基础说明

1.1 请求方式

所有接口统一使用 POST

1.2 统一返回格式

成功：

{
  "result": 1,
  "msg": "ok",
  "data": {}
}

失败：

{
  "result": 0,
  "msg": "错误信息",
  "data": []
}

说明：

result=1 表示请求成功
result=0 表示请求失败
msg 为提示文案
data 成功时通常为对象，失败时通常为空数组

1.3 路由标识

plugin.ai-create.frontend.controllers.image.image.index
plugin.ai-create.frontend.controllers.image.image.scenes
plugin.ai-create.frontend.controllers.image.image.store
plugin.ai-create.frontend.controllers.image.image.details
plugin.ai-create.frontend.controllers.image.image.delete
plugin.ai-create.frontend.controllers.image.image.upload-to-attachment

1.4 业务说明

图像生成支持“有场景模式”和“无场景模式”
scene_id 当前为选传
有场景时，后端会按场景配置限制部分参数
无场景时，后端直接按前端提交参数生成

2. 枚举与通用字段规则

2.1 图像状态 `status`

值	说明
`-1`	已删除
`0`	生成中
`1`	生成成功
`2`	生成失败

对应 status_name：

0 -> 生成中
1 -> 生成成功
2 -> 生成失败

2.2 场景状态 `status`

值	说明
`-1`	已删除
`0`	正常

2.3 请求尺寸模式 `size_type`

前端提交生成接口时使用：

值	说明	生效字段
`ratio`	固定比例模式	`image_ratio`、`resolution`
`fixed`	固定尺寸模式	`width`、`height`

说明：

size_type=ratio 时，后端最终会把记录表的 size_type 保存为 1
size_type=fixed 时，后端最终会把记录表的 size_type 保存为 2

2.4 记录表尺寸模式 `record.size_type`

图像记录详情/列表中的 size_type 为落库值：

值	说明
`0`	未设置
`1`	比例分辨率模式
`2`	固定尺寸模式

2.5 场景尺寸模式 `parameter_config.image_size_type`

值	说明
`ratio`	固定比例
`fixed`	固定尺寸

注意：

当前接口 parameter_meta.size_type_options 返回文案里，fixed 展示为“自定义尺寸”
但按迁移文件与后端逻辑，fixed 的准确语义应理解为“固定尺寸”

2.6 清晰度 `resolution / image_quality`

前端传值使用大写：

1K
2K
4K

后端调用下游接口前会转成小写：

1k
2k
4k

2.7 图片字段格式

以下字段可能出现多种形态：

字段	可能格式	说明
`refer_img`	单个 URL 字符串 / JSON 字符串	原始参考图字段
`result_img`	单个 URL 字符串 / JSON 字符串	原始结果图字段
`image_ratio`	单个比例字符串 / JSON 数组字符串	记录表原始比例字段
`image_size_ratio`	单个比例字符串 / 数组	场景接口返回时已做过格式整理

前端建议：

作品图片优先使用 result_imgs、refer_imgs
不要直接依赖 result_img、refer_img 的原始格式

3. 我的作品列表

3.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.index

3.2 请求参数

参数名	类型	必传	说明
`business_id`	int	否	企业空间下传企业 ID
`search`	object	否	搜索对象
`search.status`	int	否	状态筛选：`0/1/2`
`search.scene_id`	int	否	按场景筛选
`page`	int	否	页码

3.3 返回结构

{
  "result": 1,
  "msg": "ok",
  "data": {
    "record_list": {
      "current_page": 1,
      "data": []
    },
    "statistics": {
      "total_count": 10,
      "success_count": 8,
      "fail_count": 1,
      "creating_count": 1
    },
    "comput": {
      "open_comput_power": true,
      "comput_power_name": "算力",
      "image_need_comput_power": "1.0000"
    }
  }
}

3.4 `record_list.data[]` 字段说明

字段	类型	是否必返	说明
`id`	int	是	作品 ID
`scene_id`	int	是	场景 ID；无场景生成时可能为 `0`
`scene_name`	string	是	场景名称；无场景生成时可能为空字符串
`prompt`	string	是	最终描述词
`status`	int	是	图像状态
`status_name`	string	是	状态文案
`result_img`	string	null	是	原始结果图字段
`refer_img`	string	null	是	原始参考图字段
`result_imgs`	array	是	结果图数组，前端应优先使用
`refer_imgs`	array	是	参考图数组，前端应优先使用
`cover_img`	string	是	封面图；优先取结果图第一张，否则取参考图第一张，否则为空
`refer_cover_img`	string	是	参考图第一张，没有则为空
`is_multi_result`	int	是	是否多图：`0/1`
`belong_name`	string	是	归属名称：个人或企业名
`created_at`	string	是	创建时间

3.5 `statistics` 字段说明

字段	类型	说明
`total_count`	int	总数
`success_count`	int	成功数
`fail_count`	int	失败数
`creating_count`	int	生成中数量

3.6 `comput` 字段说明

字段	类型	说明
`open_comput_power`	bool	是否开启算力抵扣
`comput_power_name`	string	算力名称
`image_need_comput_power`	string/number	生成 1 次图像预计消耗的算力

说明：

当前代码把算力信息放在 index 接口
scenes 接口当前不返回算力字段

3.7 前端处理建议

列表卡片封面优先使用 cover_img
多图角标直接使用 is_multi_result
如果 status=2，点击详情后显示失败原因 reason

4. 创作场景列表

4.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.scenes

4.2 请求参数

参数名	类型	必传	说明
`business_id`	int	否	企业 ID
`keyword`	string	否	场景关键词
`category_id`	int/string	否	分类 ID
`page`	int	否	页码

4.3 返回结构

{
  "result": 1,
  "msg": "ok",
  "data": {
    "category_list": [],
    "scene_list": {
      "current_page": 1,
      "data": []
    },
    "parameter_meta": {}
  }
}

4.4 `category_list[]` 字段说明

字段	类型	是否必返	说明
`id`	int	是	分类 ID
`name`	string	是	分类名称

4.5 `scene_list.data[]` 字段说明

字段	类型	是否必返	说明
`id`	int	是	场景 ID
`name`	string	是	场景名称
`effect_img`	string	null	是	场景效果图
`default_prompt`	string	null	是	后台默认提示词
`category`	object	null	是	原始分类对象
`category_name`	string	是	分类名称
`use_count`	int	是	使用次数
`use_count_text`	string	是	使用次数文案
`need_refer_img`	int	是	是否支持参考图：`0/1`
`need_refer_img_text`	string	是	参考图文案
`refer_img_required_text`	string	是	参考图是否必传文案
`source_text`	string	是	来源说明/默认提示词展示字段
`parameter_config`	object	是	场景参数配置

4.6 `parameter_config` 字段说明

字段	类型	是否必返	说明
`desc_enabled`	int	是	是否允许填写描述词：`0/1`
`desc_required`	int	是	描述词是否必填：`0/1`
`default_prompt`	string	是	默认提示词
`refer_img_enabled`	int	是	是否允许参考图：`0/1`
`refer_img_required`	int	是	参考图是否必传：`0/1`
`refer_img_limit`	int	是	参考图数量限制；`0` 表示不限制
`param_limit_enabled`	int	是	是否锁定参数：`0/1`
`generate_count`	int	是	默认生成数量/生成张数
`image_quality`	string	是	默认清晰度；一般为 `1K/2K/4K`
`image_size_type`	string	是	场景尺寸模式：`ratio/fixed`
`image_size_ratio`	string/array	是	默认比例；单个比例时可能是字符串，多个比例时可能是数组
`image_width`	int	是	默认宽度；`image_size_type=fixed` 时使用
`image_height`	int	是	默认高度；`image_size_type=fixed` 时使用
`allow_user_prompt`	bool	是	前端是否允许用户输入提示词
`allow_user_resolution`	bool	是	前端是否允许用户选择清晰度
`allow_user_count`	bool	是	前端是否允许用户选择数量
`allow_user_ratio`	bool	是	前端是否允许用户选择比例
`allow_user_custom_size`	bool	是	前端是否允许用户输入宽高

4.7 `parameter_meta` 字段说明

字段	类型	说明
`quality_options`	array	清晰度选项：`1K/2K/4K`
`count_options`	array	数量选项：`1/3/5/10`
`ratio_options`	array	比例选项
`size_type_options`	array	尺寸模式选项；当前文案为“固定比例/自定义尺寸”

4.8 字段依赖说明

当 param_limit_enabled=1 时，前端应优先按场景配置展示和提交
当 image_size_type=ratio 时，应使用 image_size_ratio + image_quality
当 image_size_type=fixed 时，应使用 image_width + image_height
当 refer_img_enabled=0 时，前端应隐藏参考图上传入口
当 refer_img_required=1 时，前端应阻止空参考图提交

4.9 前端处理建议

场景弹窗大图使用 effect_img
来源说明使用 source_text
选择场景后，页面表单是否可编辑应参考 parameter_config

5. 提交图像生成

5.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.store

5.2 请求参数

参数名	类型	必传	说明
`business_id`	int	否	企业空间生成时传
`scene_id`	int	否	场景 ID；有场景模式下传
`prompt`	string	否	描述词；无场景时实际必填
`refer_img`	string/array	否	参考图；支持单图 URL、JSON 字符串或数组
`pic_count`	int	否	生成数量
`generate_count`	int	否	`pic_count` 别名
`resolution`	string	否	清晰度：`1K/2K/4K`
`image_quality`	string	否	`resolution` 别名
`size_type`	string	否	尺寸模式：`ratio/fixed`
`image_size_type`	string	否	`size_type` 别名
`image_ratio`	string/array	否	比例；仅 `size_type=ratio` 时生效
`width`	int	否	宽度；仅 `size_type=fixed` 时生效
`height`	int	否	高度；仅 `size_type=fixed` 时生效

5.3 提交规则

有场景模式

传 scene_id
后端会校验场景是否存在
若 param_limit_enabled=1，后端会忽略前端传入的数量/清晰度/尺寸参数
若 desc_enabled=0，后端会忽略前端传入的 prompt
若 desc_required=1，描述词必须传
若 refer_img_required=1，参考图必须传
若 refer_img_limit>0，参考图数量必须严格等于该值

无场景模式

不传 scene_id
后端不会执行场景限制
prompt 实际必填
参数完全按前端提交值处理

尺寸规则

size_type=ratio 时：
- image_ratio 必填
- resolution 必填
size_type=fixed 时：
- width 必填
- height 必填

清晰度规则

前端传 1K/2K/4K
后端下发下游前会转成 1k/2k/4k

5.4 常见错误文案

错误文案	说明
`场景不存在`	传入的 `scene_id` 无效
`当前场景不支持参考图`	场景关闭了参考图
`请上传参考图`	场景要求参考图必传
`参考图数量需为X张`	参考图数量和限制不一致
`请填写描述词`	场景要求描述词必填
`请输入图像描述`	无场景且未传 `prompt`，或最终无可用描述词
`生成数量不支持`	`pic_count` 不在允许范围内
`图像比例不支持`	`image_ratio` 不在允许范围内
`图像清晰度不支持`	`resolution` 不在允许范围内
`固定比例模式下图像比例必填`	`size_type=ratio` 缺少比例
`固定比例模式下图像清晰度必填`	`size_type=ratio` 缺少清晰度
`自定义尺寸模式下宽高必填`	`size_type=fixed` 缺少宽高

5.5 请求示例

示例一：有场景模式

{
  "business_id": 0,
  "scene_id": 3,
  "prompt": "生成一张商务头像",
  "refer_img": [
    "https://xx/r1.jpg"
  ]
}

示例二：无场景固定比例模式

{
  "prompt": "生成一张商务头像",
  "pic_count": 1,
  "size_type": "ratio",
  "image_ratio": "1:1",
  "resolution": "1K"
}

示例三：无场景固定尺寸模式

{
  "prompt": "生成一张电商主图",
  "pic_count": 1,
  "size_type": "fixed",
  "width": 1024,
  "height": 1024
}

5.6 返回结构

{
  "result": 1,
  "msg": "AI图像生成任务已提交",
  "data": {
    "record": {
      "id": 20,
      "scene_id": 0,
      "scene_name": "",
      "prompt": "生成一张商务头像",
      "refer_img": "[\"https://xx/r1.jpg\"]",
      "status": 0,
      "status_name": "生成中",
      "job_id": "req_xxx"
    }
  }
}

5.7 `data.record` 字段说明

字段	类型	是否必返	说明
`id`	int	是	作品 ID
`scene_id`	int	是	场景 ID；无场景时为 `0`
`scene_name`	string	是	场景名称；无场景时为空字符串
`prompt`	string	是	最终描述词
`refer_img`	string	null	是	原始参考图字段
`pic_count`	int	是	生成数量
`size_type`	int	是	记录表尺寸模式：`1/2`
`image_ratio`	string	null	是	比例值；可能是单个比例字符串，也可能是 JSON 字符串
`resolution`	string	null	是	落库清晰度；一般是小写，如 `1k`
`width`	int	是	宽度
`height`	int	是	高度
`status`	int	是	状态，初始为 `0`
`status_name`	string	是	状态文案
`job_id`	string	null	是	任务 ID

6. 作品详情

6.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.details

6.2 请求参数

参数名	类型	必传	说明
`id`	int	是	作品 ID
`business_id`	int	否	企业 ID

6.3 返回结构

{
  "result": 1,
  "msg": "ok",
  "data": {
    "record": {}
  }
}

6.4 `record` 字段说明

字段	类型	是否必返	说明
`id`	int	是	作品 ID
`scene_id`	int	是	场景 ID
`scene_name`	string	是	场景名称
`scene_category_name`	string	是	场景分类名；无场景时可能为空
`prompt`	string	是	描述词
`status`	int	是	状态
`status_name`	string	是	状态文案
`reason`	string	null	是	失败原因；失败作品建议展示该字段
`job_id`	string	null	是	任务 ID
`created_at`	string	是	创建时间
`finish_time`	string/null	是	完成时间；未完成时可能为空
`compute`	string	是	算力消耗字段
`data_points`	string	是	数据通点数字段
`result_img`	string	null	是	原始结果图字段
`refer_img`	string	null	是	原始参考图字段
`result_imgs`	array	是	结果图数组
`refer_imgs`	array	是	参考图数组
`is_multi_result`	int	是	是否多图：`0/1`
`member_name`	string	是	作者昵称
`member_avatar`	string	是	作者头像
`belong_name`	string	是	归属名称
`can_retry`	int	是	是否可重新创作；失败时通常为 `1`
`can_upload_to_attachment`	int	是	是否显示上传商城附件按钮
`upload_to_attachment_text`	string	是	按钮文案
`attachment_tag_list`	array	是	附件分组列表

6.5 `attachment_tag_list` 字段说明

字段	类型	说明
`id`	int	分组 ID
`name`	string	分组名称
`parent_id`	int	父级 ID，一级分组为 `0`
`children`	array	子分组列表

6.6 前端处理建议

status=2 时应展示 reason
详情页图片轮播优先使用 result_imgs
参考图区域使用 refer_imgs
can_upload_to_attachment=1 时显示上传按钮

7. 上传到商城附件

7.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.upload-to-attachment

7.2 请求参数

参数名	类型	必传	说明
`id`	int	是	作品 ID
`image_url`	string	否	当前选中的生成图 URL；不传默认上传第一张
`tag_id`	int	否	商城附件分组 ID
`business_id`	int	否	企业 ID

7.3 业务规则

仅成功作品支持上传
仅“平台绑定企业”的企业作品支持上传
image_url 必须是当前作品生成结果图之一
tag_id 有值时会校验是否存在

7.4 返回字段

字段	类型	说明
`attachment_id`	int	商城附件记录 ID
`attachment`	string	存储路径
`url`	string	访问地址
`filename`	string	附件文件名

8. 删除作品

8.1 接口地址

POST:/plugin.ai-create.frontend.controllers.image.image.delete

8.2 请求参数

参数名	类型	必传	说明
`id`	int	是	作品 ID
`business_id`	int	否	企业 ID

8.3 返回说明

成功时：

{
  "result": 1,
  "msg": "删除成功",
  "data": []
}

说明：

删除为逻辑删除
删除后该作品不会再出现在列表里

9. 前端联调建议

9.1 推荐取值优先级

结果图：result_imgs
参考图：refer_imgs
封面图：cover_img
失败原因：reason

9.2 页面展示建议

场景选择页

标题：name
分类：category_name
效果图：effect_img
使用次数：use_count_text
来源说明：source_text

生成页

有场景时根据 parameter_config 控制表单显隐和可编辑性
无场景时至少保证 prompt 必填
如果需要展示算力消耗，当前从 index 接口 data.comput 获取

作品详情页

成功作品显示 result_imgs
失败作品显示 reason
根据 can_upload_to_attachment 控制上传按钮

9.3 联调注意事项

不要直接依赖 result_img/refer_img 原始格式
image_ratio、image_size_ratio 可能不是固定单一类型
scene_id 当前不是必传
scenes 当前没有算力字段，不要从这个接口读取算力

ai图像生成