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

---

## 目录

- [请求参数](#请求参数)
- [aiParams 图片模型字段](#aiparams-图片模型字段)
- [aiParams 视频模型字段](#aiparams-视频模型字段)
- [Model Capabilities 配置结构](#model-capabilities-配置结构)
- [各模型 Capabilities 速查表](#各模型-capabilities-速查表)
- [使用示例](#使用示例)
- [响应结构](#响应结构)
- [@ 提及功能](#-提及功能)
- [注意事项](#注意事项)
- [相关接口](#相关接口)

---

## 请求参数

### 顶层字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `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 对象格式

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

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

### 简单数组字段（aspect_ratio）

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

### 整数范围字段（n）

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

### 对象字段（input_reference / prompt）

```json
{
  "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：仅发消息（不触发生成）

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

---

### 示例 2：文生图（Gemini）

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

---

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

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

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

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

---

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

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

```json
{
  "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，首帧模式）

```json
{
  "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：@ 提及资源（自动解析参考图）

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

后端自动处理流程：

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

---

## 响应结构

```typescript
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` | 获取可提及资源列表 |

---

**版本**: v2.0  
**最后更新**: 2026-02-28  
**维护者**: Jointo AI Team