14 KiB

Raw Blame History

AI 对话消息 API 参数说明

接口: POST /api/v1/ai/conversations/{conversation_id}/messages

版本: v2.0
日期: 2026-02-28
参考: RFC 144 · server/app/api/v1/ai_conversations.py · server/scripts/migrate_model_capabilities.py

请求参数

顶层字段

字段	类型	必填	说明
`content`	`string`	✅	消息文本内容，可包含 `@[name](id)` 提及标记
`generate`	`GenerateConfig`	❌	提供此字段即触发 AI 生成（一步完成）

GenerateConfig

字段	类型	必填	说明
`generationType`	`"image" \| "video"`	✅	生成类型
`modelId`	`string`	✅	模型 ID，如 `"gemini-2.5-flash-image"`
`aiParams`	`AIParams`	✅	AI 模型参数（见下方字段说明）
`businessParams`	`object`	❌	自定义业务参数字典（灵活扩展）

aiParams 图片模型字段

字段	类型	说明	示例值
`size`	`string`	分辨率档位	`"1K"` `"2K"` `"4K"`
`aspectRatio`	`string`	宽高比	`"16:9"` `"9:16"` `"1:1"` `"4:3"` `"21:9"`
`n`	`integer`	单次生成数量	`1`~`15`（取决于模型）
`quality`	`string`	渲染质量档位	`"standard"` `"hd"` `"fast"`
`watermark`	`boolean`	是否添加水印（Volcengine 专用）	`true` / `false`
`referenceImages`	`string[]`	参考图 URL 列表（支持图生图/多图融合）	`["https://..."]`

分辨率对照（图片 K 系列）

`size` + `aspectRatio`	实际像素
`1K` + `16:9`	1824 × 1024
`2K` + `16:9`	3648 × 2048
`4K` + `1:1`	4096 × 4096
`1K` + `9:16`	1024 × 1824
`2K` + `1:1`	2048 × 2048

aiParams 视频模型字段

字段	类型	说明	示例值
`resolution`	`string`	分辨率档位	`"480p"` `"720p"` `"1080p"`
`aspectRatio`	`string`	宽高比（`adaptive` 跟随参考图比例）	`"16:9"` `"9:16"` `"1:1"` `"adaptive"`
`duration`	`integer`	视频时长（秒）	`4` `5` `8` `10` `12`
`imgMode`	`string`	图片参考模式（有参考图时有效）	`"reference"` `"first_frame"` `"last_frame"`
`generateAudio`	`boolean`	是否生成音频（Seedance 1.5 Pro）	`true` / `false`
`referenceImages`	`ReferenceImageObj[]`	视频参考图对象列表（格式见下方）	—

视频 referenceImages 对象格式

{
  "type": "image_url",
  "image_url": { "url": "https://example.com/image.jpg" },
  "role": "reference_image"
}

role 可选值：

role	说明
`reference_image`	风格/内容参考，生成与参考图相关的视频
`first_frame`	将图片作为视频第一帧，从该帧向后生成
`last_frame`	将图片作为视频最后一帧，反向推演前序画面

分辨率对照（视频 P 系列）

`resolution` + `aspectRatio`	实际像素
`480P` + `16:9`	832 × 480
`720P` + `16:9`	1280 × 720
`1080P` + `16:9`	1920 × 1080
`720P` + `9:16`	720 × 1280
`1080P` + `1:1`	1080 × 1080

Model Capabilities 配置结构

数据库 ai_models.capabilities 字段定义了每个模型的前端 UI 约束，共四种数据类型：

枚举字段（size / quality / duration / imgMode）

{
  "type": "enum",
  "values": [
    { "name": "720P", "value": "720P" },
    { "name": "1080P", "value": "1080P" }
  ],
  "default": "720P"
}

简单数组字段（aspect_ratio）

{
  "values": ["16:9", "9:16", "1:1", "4:3"],
  "default": "16:9"
}

整数范围字段（n）

{
  "type": "integer",
  "min": 1,
  "max": 15
}

对象字段（input_reference / prompt）

{
  "input_reference": {
    "image": {
      "supported": true,
      "total_max": 14,
      "object_max": 10,
      "character_max": 4,
      "formats": ["jpeg", "png", "webp"],
      "max_size_mb": 7
    }
  },
  "prompt": {
    "max_chars_cn": 300,
    "max_words_en": 600,
    "hint": "建议不超过300个汉字..."
  }
}

input_reference.image 字段说明

字段	类型	说明
`supported`	`boolean`	是否支持图片输入
`total_max`	`integer`	最多接受张数
`object_max`	`integer`	对象参考图上限（部分模型）
`character_max`	`integer`	角色参考图上限（部分模型）
`formats`	`string[]`	支持的图片格式
`max_size_mb`	`integer`	单张图片最大体积（MB）
`aspect_ratio_min`	`float`	宽高比下限（宽/高，可选）
`aspect_ratio_max`	`float`	宽高比上限（宽/高，可选）
`min_dimension`	`integer`	宽/高最小像素值（px，可选）
`max_pixels`	`integer`	单张图片最大总像素（宽×高，可选）

各模型 Capabilities 速查表

图片模型

模型	size 可选值	aspectRatio	n 范围	quality	参考图上限
`gemini-2.5-flash-image`	1K	1:1/2:3/3:2/3:4/4:3/4:5/5:4/9:16/16:9/21:9	1	—	14张 (jpeg/png)
`gemini-3-pro-image-preview`	1K/2K/4K	1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9	1	—	14张总(对象10+角色4)
`gemini-3.1-flash-image-preview`	1K/2K/4K	1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9	1	—	14张总(对象10+角色4)
`doubao-seedream-4-5-251128`	2K/4K	1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9	1~15	standard	14张
`doubao-seedream-4-0-250828`	1K/2K/4K	1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9	1~15	standard/fast	14张
`doubao-seedream-5-0-260128`	2K/3K	1:1/2:3/3:2/3:4/4:3/9:16/16:9/21:9	1~15	standard	14张

Doubao 系列限制：输入图片数 + 生成图片数 ≤ 15

视频模型

模型	size 可选值	aspectRatio	duration（秒）	imgMode	音频	参考图上限
`doubao-seedance-1-5-pro-251215`	480P/720P/1080P	16:9/9:16/1:1/4:3/3:4/21:9/adaptive	4/5/8/10/12	reference_image/first_frame/last_frame	✅	4张
`sora-2`	720P	9:16/16:9	4/8/12	first_frame（仅）	—	1张
`sora-2-pro`	720P	9:16/16:9	4/8/12	first_frame（仅）	—	1张

使用示例

示例 1：仅发消息（不触发生成）

{
  "content": "帮我生成一个日落场景"
}

示例 2：文生图（Gemini）

{
  "content": "生成一个日落场景",
  "generate": {
    "generationType": "image",
    "modelId": "gemini-2.5-flash-image",
    "aiParams": {
      "size": "1K",
      "aspectRatio": "16:9",
      "n": 1,
      "quality": "standard"
    }
  }
}

示例 3：图生图（携带参考图 · Gemini）

{
  "content": "将参考图改为冬雪场景",
  "generate": {
    "generationType": "image",
    "modelId": "gemini-2.5-flash-image",
    "aiParams": {
      "size": "1K",
      "aspectRatio": "1:1",
      "n": 1,
      "quality": "standard",
      "referenceImages": [
        "https://example.com/ref.png"
      ]
    }
  }
}

示例 4：多图融合（Gemini Pro）

{
  "content": "融合两张图片的风格",
  "generate": {
    "generationType": "image",
    "modelId": "gemini-3-pro-image-preview",
    "aiParams": {
      "size": "2K",
      "aspectRatio": "1:1",
      "n": 1,
      "referenceImages": [
        "https://example.com/ref1.png",
        "https://example.com/ref2.png"
      ]
    }
  }
}

示例 5：文生视频（Seedance）

{
  "content": "写实风格，晴朗蓝天下的雏菊花田，镜头逐渐拉近",
  "generate": {
    "generationType": "video",
    "modelId": "doubao-seedance-1-5-pro-251215",
    "aiParams": {
      "resolution": "720p",
      "aspectRatio": "16:9",
      "duration": 5
    }
  }
}

示例 6：图生视频 - 参考图模式（Seedance）

{
  "content": "戴眼镜的男生和柯基坐在草坪上，卡通风格",
  "generate": {
    "generationType": "video",
    "modelId": "doubao-seedance-1-5-pro-251215",
    "aiParams": {
      "resolution": "720p",
      "aspectRatio": "adaptive",
      "duration": 5,
      "imgMode": "reference",
      "referenceImages": [
        { "type": "image_url", "image_url": { "url": "https://example.com/ref1.jpg" }, "role": "reference_image" },
        { "type": "image_url", "image_url": { "url": "https://example.com/ref2.jpg" }, "role": "reference_image" }
      ]
    }
  }
}

说明：aspectRatio: "adaptive" 表示自动跟随参考图宽高比。

示例 7：图生视频 - 首尾帧模式（Seedance）

{
  "content": "女孩对着镜头说茄子，360度环绕运镜",
  "generate": {
    "generationType": "video",
    "modelId": "doubao-seedance-1-5-pro-251215",
    "aiParams": {
      "resolution": "720p",
      "aspectRatio": "adaptive",
      "duration": 5,
      "generateAudio": true,
      "referenceImages": [
        { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "role": "first_frame" },
        { "type": "image_url", "image_url": { "url": "https://example.com/last.jpg" }, "role": "last_frame" }
      ]
    }
  }
}

说明：role: "first_frame" 为视频首帧，role: "last_frame" 为视频尾帧，系统自动补全中间过渡内容。

示例 8：图生视频（Sora-2，首帧模式）

{
  "content": "夕阳西下，海浪拍打礁石",
  "generate": {
    "generationType": "video",
    "modelId": "sora-2",
    "aiParams": {
      "resolution": "720p",
      "aspectRatio": "16:9",
      "duration": 8,
      "referenceImages": [
        { "type": "image_url", "image_url": { "url": "https://example.com/sunset.jpg" }, "role": "first_frame" }
      ]
    }
  }
}

说明：Sora-2 仅支持 first_frame 模式，参考图上限 1 张。

示例 9：@ 提及资源（自动解析参考图）

{
  "content": "基于 @[角色A](uuid-a) 和 @[场景B](uuid-b) 生成一张图片",
  "generate": {
    "generationType": "image",
    "modelId": "gemini-2.5-flash-image",
    "aiParams": {
      "size": "1K",
      "aspectRatio": "16:9"
    }
  }
}

后端自动处理流程：

解析消息中的 @[角色A](uuid-a) 提及标记
查询对应资源的图片 URL
自动合并到 aiParams.referenceImages（与手动传入的 URL 去重合并）
提及元数据写入 businessParams.mentions

响应结构

interface SendMessageResponse {
  messageId: string;
  conversationId: string;
  userId: string;
  aiJobId?: string;
  role: number;           // 1=用户 2=AI 3=系统
  content: string;
  metaData: {
    generate?: {
      generationType: string;
      modelId: string;
      aiParams: Record<string, any>;
      businessParams?: {
        mentions?: Array<{
          resourceId: string;
          resourceType: number;
          title: string;
        }>;
      };
    };
  };
  orderIndex: number;
  createdAt: string;
  updatedAt: string;

  // 仅在触发了 AI 生成时存在
  generation?: {
    jobId: string;
    taskId: string;
    status: string;
    estimatedCredits: number;
    referenceImagesCount: number;
  };
}

@ 提及功能

提及语法

@[显示名称](资源 UUID)

处理流程

消息内容解析 → 验证资源存在 → 提取图片 URL
        ↓
手动传入 referenceImages + 提及解析 URLs → 去重合并
        ↓
aiParams.referenceImages（传给 AI 模型）
businessParams.mentions（业务元数据存档）

支持的资源类型

resourceType	说明
1	角色
2	场景
3	道具
4	素材
5	分镜

注意事项

图片参数

n 的上限因模型不同而异：Gemini 系列最大 1，Doubao 系列最大 15（参考图张数 + 生成张数 ≤ 15）
size 与 aspectRatio 配合使用，前端从 capabilities 读取可选值
quality 不是所有模型都支持，需检查模型的 capabilities

视频参数

resolution 字段名称与图片的 size 不同，视频使用 resolution
imgMode: "reference" 在传参时等同于 capabilities 中的 "reference_image"（适配器内部转换）
generateAudio 目前仅 doubao-seedance-1-5-pro-251215 支持
aspectRatio: "adaptive" 为视频专属值，表示自动跟随参考图比例

参考图

图片模型：referenceImages 为 string[]（URL 列表）
视频模型：referenceImages 为 ReferenceImageObj[]（对象列表，含 role 字段）
参考图格式和大小限制见各模型 capabilities 的 input_reference.image

接口	说明
`POST /ai/conversations`	创建对话会话
`GET /ai/conversations`	获取对话列表（支持按 projectId / targetType / targetId / tagId / mediaType 筛选）
`GET /ai/conversations/{id}`	获取会话详情
`PATCH /ai/conversations/{id}`	更新会话标题/状态
`DELETE /ai/conversations/{id}`	删除会话（软删除）
`POST /ai/conversations/{id}/messages`	发送消息（本文档）
`GET /ai/conversations/{id}/messages`	获取消息列表（支持分页）
`POST /ai/conversations/{id}/generate`	单独触发 AI 生成（无需附带消息）
`GET /ai/conversations/storyboards/{id}/related-resources`	获取可提及资源列表

14 KiB

Raw Blame History

AI 对话消息 API 参数说明

目录

请求参数

顶层字段

GenerateConfig

aiParams 图片模型字段

分辨率对照（图片 K 系列）

aiParams 视频模型字段

视频 referenceImages 对象格式

分辨率对照（视频 P 系列）

Model Capabilities 配置结构

枚举字段（size / quality / duration / imgMode）

简单数组字段（aspect_ratio）

整数范围字段（n）

对象字段（input_reference / prompt）

input_reference.image 字段说明

各模型 Capabilities 速查表

图片模型

视频模型

使用示例

示例 1：仅发消息（不触发生成）

示例 2：文生图（Gemini）

示例 3：图生图（携带参考图 · Gemini）

示例 4：多图融合（Gemini Pro）

示例 5：文生视频（Seedance）

示例 6：图生视频 - 参考图模式（Seedance）

示例 7：图生视频 - 首尾帧模式（Seedance）

示例 8：图生视频（Sora-2，首帧模式）

示例 9：@ 提及资源（自动解析参考图）

响应结构

@ 提及功能

提及语法

处理流程

支持的资源类型

注意事项

图片参数

视频参数

参考图

相关接口

14 KiB Raw Blame History

AI 对话消息 API 参数说明

目录

请求参数

顶层字段

GenerateConfig

aiParams 图片模型字段

分辨率对照（图片 K 系列）

aiParams 视频模型字段

视频 referenceImages 对象格式

分辨率对照（视频 P 系列）

Model Capabilities 配置结构

枚举字段（size / quality / duration / imgMode）

简单数组字段（aspect_ratio）

整数范围字段（n）

对象字段（input_reference / prompt）

input_reference.image 字段说明

各模型 Capabilities 速查表

图片模型

视频模型

使用示例

示例 1：仅发消息（不触发生成）

示例 2：文生图（Gemini）

示例 3：图生图（携带参考图 · Gemini）

示例 4：多图融合（Gemini Pro）

示例 5：文生视频（Seedance）

示例 6：图生视频 - 参考图模式（Seedance）

示例 7：图生视频 - 首尾帧模式（Seedance）

示例 8：图生视频（Sora-2，首帧模式）

示例 9：@ 提及资源（自动解析参考图）

响应结构

@ 提及功能

提及语法

处理流程

支持的资源类型

注意事项

图片参数

视频参数

参考图

相关接口

14 KiB

Raw Blame History