图片模式使用指南

本文档介绍 ai_app_run_image 接口支持的图片输入模式。

概述

图生视频任务支持以下图片输入模式：

前端实现说明

前端图生视频节点的选择器中提供三种用户可选模式：

• 首尾帧模式 (first_last_frame)：支持首帧和尾帧图片输入，以及首尾帧图片节点连接端口
• 多参考图模式 (multi_reference)：支持多张参考图上传，以及参考图输入端口、参考音频、参考视频连接
• 文生视频 (text_to_video)：不使用图片输入，直接由提示词生成视频

其中首尾帧+参考图模式（first_last_with_ref）不在前端选择器中提供，仅可通过后端配置/接口参数使用。

此外，存在一个内部上下文值 first_last_with_tail，当首尾帧模式下同时存在首帧和尾帧时，系统会自动使用此值作为算力计算的上下文参数，而非用户可选模式。

API 参数

新增参数

示例请求

首尾帧模式（默认）

curl -X POST "/api/ai-app-run-image" \
  -F "prompt=一只猫在奔跑" \
  -F "task_id=<任务ID>" \
  -F "image_urls=https://example.com/first.jpg,https://example.com/last.jpg" \
  -F "image_mode=first_last_frame"

多参考图模式

curl -X POST "/api/ai-app-run-image" \
  -F "prompt=一只猫在奔跑" \
  -F "task_id=<任务ID>" \
  -F "image_urls=https://example.com/ref1.jpg,https://example.com/ref2.jpg" \
  -F "image_mode=multi_reference"

首尾帧+参考图模式

curl -X POST "/api/ai-app-run-image" \
  -F "prompt=一只猫在奔跑" \
  -F "task_id=<任务ID>" \
  -F "image_urls=https://example.com/first.jpg,https://example.com/middle.jpg,https://example.com/last.jpg" \
  -F "image_mode=first_last_with_ref"

数据存储结构

系统在相关数据表中保存以下信息：

• 首尾帧图片URL列表（逗号分隔）
• 参考图URL列表（JSON数组）
• 图片模式配置（JSON对象，包含模式标识）

各模式存储方式

配置层

在统一配置文件中配置任务支持的图片模式

每个图生视频任务可以配置 supported_image_modes 字段来指定支持的图片模式：

# 统一配置文件中某个图生视频任务的配置
UnifiedTaskConfig(
    key='某图生视频任务',
    name='图片生成视频（某视频生成模型）',
    category=TaskCategory.IMAGE_TO_VIDEO,
    # ... 其他配置
    supported_image_modes=[ImageMode.FIRST_LAST_FRAME],  # 支持首尾帧
    default_image_mode='first_last_frame',  # 默认模式
)

ImageMode 常量

class ImageMode:
    FIRST_LAST_FRAME = 'first_last_frame'     # 首尾帧模式
    MULTI_REFERENCE = 'multi_reference'       # 多参考图模式
    FIRST_LAST_WITH_REF = 'first_last_with_ref'  # 首尾帧+参考图模式

驱动支持情况

当前各驱动对模式的支持

说明：

• ✅ 完整支持：驱动原生支持该模式
• ⚠️ 部分支持：驱动会自动降级处理，日志中会记录警告
• 配置模式：当前在统一配置文件中配置的 supported_image_modes

驱动层

驱动层（对应驱动）提供以下能力解析图片模式：

• 解析当前图片模式（返回 first_last_frame 等标识）
• 获取首帧与尾帧
• 获取参考图列表
• 一次性获取所有图片信息（返回包含模式、首帧、尾帧、参考图列表的字典）

前端多参考图模式功能

当用户选择多参考图模式时，前端提供以下功能：

参考图输入

• 文件上传：支持多图片文件选择上传
• 节点连接：通过参考图输入端口连接图片节点，自动提取参考图
• 参考图预览：显示已选择的参考图缩略图和计数
• 清除功能：支持清除全部参考图

参考音视频

• 参考音频：支持连接音频节点或上传音频文件作为参考
• 参考视频：支持连接视频节点作为参考

模型限制

• 参考图数量上限取决于当前选择的视频模型，通过任务配置中的最大参考图数量获取
• 参考图片标签会动态更新显示当前模型支持的数量范围

向后兼容

• image_mode 默认值为 first_last_frame，与现有行为一致
• 不传 reference_images 时，该字段为 null
• 现有接口调用无需修改即可正常工作

数据库迁移

已提供对应的数据库迁移脚本（新增参考图列表字段），部署时按标准流程执行迁移即可。