ImageOnlyCheckpointLoader 深度详解（图像转视频专用）

ImageOnlyCheckpointLoader 是 ComfyUI 中专门用于加载视频生成类模型的 Checkpoint 加载器，核心适配 SVD（Stable Video Diffusion） 这类「无文本编码器、依赖图像输入」的模型，是实现图生视频的关键节点。

一、核心定位与适用场景

1. 核心特点

• 无 CLIP 文本编码器输出：因为视频生成模型（如 SVD）不依赖文本指令，仅靠初始图像驱动生成视频帧。
• 强依赖 CLIP_VISION 图像编码器：用于提取初始图像的视觉特征，作为视频生成的条件。
• 输出 MODEL+VAE：分别负责视频帧的生成和图像解码。

2. 适用模型与场景

表格

适用模型	核心场景	输入要求
SVD（svd.safetensors）	短视频生成（14 帧左右）	单张初始图像
SVD-XT（svd_xt.safetensors）	更长视频生成（25 帧左右）	单张初始图像
其他视频生成类 Checkpoint	自定义视频生成工作流	按模型要求输入

二、API 核心参数详解

1. 输入参数

表格

参数名	类型	说明
ckpt_name	字符串	必填，必须是 ComfyUI/models/checkpoints 目录下的视频模型文件名（如 svd.safetensors）

2. 输出参数（索引是节点连接的关键！）

RETURN_TYPES = ("MODEL", "CLIP_VISION", "VAE")

表格

输出索引	输出类型	作用	下游连接节点
0	MODEL	视频生成主模型	连接 KSampler 的 model 参数
1	CLIP_VISION	图像特征编码器	连接 SVD_img2vid_Conditioning 的 clip_vision 参数
2	VAE	图像解码器	连接 SVD_img2vid_Conditioning 的 vae 参数 + VAEDecode 的 vae 参数

划重点：输出索引 1 是 CLIP_VISION，不是常规的 CLIP，这是和 CheckpointLoaderSimple 的核心区别！

三、完整 JSON 工作流拆解（图转视频实战）

以 SVD 生成 14 帧短视频为例，完整工作流包含 6 个节点，我们逐节点拆解逻辑。

1. 完整 JSON 代码

json

{
  "1": {
    "inputs": { "ckpt_name": "svd.safetensors" },
    "class_type": "ImageOnlyCheckpointLoader"
  },
  "2": {
    "inputs": { "image": "start_frame.png", "upload": "image" },
    "class_type": "LoadImage"
  },
  "3": {
    "inputs": {
      "width": 1024,
      "height": 576,
      "video_frames": 14,
      "motion_bucket_id": 127,
      "fps": 6,
      "augmentation_level": 0,
      "clip_vision": ["1", 1],
      "init_image": ["2", 0],
      "vae": ["1", 2]
    },
    "class_type": "SVD_img2vid_Conditioning"
  },
  "4": {
    "inputs": {
      "seed": 12345,
      "steps": 20,
      "cfg": 8,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["1", 0],
      "positive": ["3", 0],
      "negative": ["3", 1],
      "latent_image": ["3", 2]
    },
    "class_type": "KSampler"
  },
  "5": {
    "inputs": { "samples": ["4", 0], "vae": ["1", 2] },
    "class_type": "VAEDecode"
  },
  "6": {
    "inputs": { "filename_prefix": "SVD_video", "images": ["5", 0] },
    "class_type": "SaveImage"
  }
}

2. 节点逻辑拆解（核心是 ImageOnlyCheckpointLoader 的连接）

表格

节点 ID	节点类型	核心作用	关键连接（和节点 1 的关联）
1	ImageOnlyCheckpointLoader	加载 SVD 模型	输出 3 个组件，供下游节点调用
2	LoadImage	加载初始图像（视频第一帧）	无直接关联，输出给节点 3
3	SVD_img2vid_Conditioning	视频条件构建核心	1. clip_vision: ["1", 1] → 用节点 1 的图像编码器提特征2. vae: ["1", 2] → 用节点 1 的解码器做图像预处理3. init_image: ["2", 0] → 初始图像
4	KSampler	生成视频帧 latent 数据	1. model: ["1", 0] → 用节点 1 的主模型驱动生成2. positive/negative/latent_image: 来自节点 3 的条件输出
5	VAEDecode	把 latent 转成视频帧图像	vae: ["1", 2] → 用节点 1 的解码器解码
6	SaveImage	保存所有视频帧	接收节点 5 的图像输出，后续可合并为 MP4

3. 关键参数说明（节点 3 是视频生成的核心）

节点 SVD_img2vid_Conditioning 的参数直接决定视频效果：

• width/height：视频分辨率，SVD 推荐 1024×576/576×1024
• video_frames：生成的视频帧数，SVD 最大 14 帧、SVD-XT 最大 25 帧
• motion_bucket_id：运动幅度控制，值越大，视频画面运动越剧烈（推荐 50-200）
• fps：视频帧率，默认 6，决定视频播放速度
• augmentation_level：图像增强程度，0 为无增强，值越大画面变化越大

四、Python API 调用完整流程

1. 步骤总览

1. 确认 SVD 模型已放入 models/checkpoints 目录
2. 编写上述 JSON 工作流
3. 提交工作流并获取任务 ID
4. 等待生成完成后，下载视频帧并合并为 MP4

2. 完整 Python 代码

python

运行

import requests
import json
import os
from PIL import Image
import cv2
import numpy as np

# ComfyUI 基础地址
COMFYUI_URL = "http://127.0.0.1:8188"

# 1. 定义图转视频工作流
video_workflow = {
  "1": {
    "inputs": { "ckpt_name": "svd.safetensors" },
    "class_type": "ImageOnlyCheckpointLoader"
  },
  "2": {
    "inputs": { "image": "start_frame.png", "upload": "image" },
    "class_type": "LoadImage"
  },
  "3": {
    "inputs": {
      "width": 1024,
      "height": 576,
      "video_frames": 14,
      "motion_bucket_id": 127,
      "fps": 6,
      "augmentation_level": 0,
      "clip_vision": ["1", 1],
      "init_image": ["2", 0],
      "vae": ["1", 2]
    },
    "class_type": "SVD_img2vid_Conditioning"
  },
  "4": {
    "inputs": {
      "seed": 12345,
      "steps": 20,
      "cfg": 8,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["1", 0],
      "positive": ["3", 0],
      "negative": ["3", 1],
      "latent_image": ["3", 2]
    },
    "class_type": "KSampler"
  },
  "5": {
    "inputs": { "samples": ["4", 0], "vae": ["1", 2] },
    "class_type": "VAEDecode"
  },
  "6": {
    "inputs": { "filename_prefix": "SVD_video", "images": ["5", 0] },
    "class_type": "SaveImage"
  }
}

# 2. 提交工作流
def submit_video_workflow(workflow):
    response = requests.post(
        f"{COMFYUI_URL}/api/prompt",
        json={"prompt": workflow}
    )
    return response.json()["prompt_id"]

# 3. 获取生成的视频帧文件名
def get_video_frames(prompt_id):
    while True:
        history = requests.get(f"{COMFYUI_URL}/api/history/{prompt_id}").json()
        if prompt_id in history and "outputs" in history[prompt_id]:
            outputs = history[prompt_id]["outputs"]
            frames = []
            for node in outputs.values():
                if "images" in node:
                    frames = [img["filename"] for img in node["images"]]
            return sorted(frames)  # 按帧顺序排序
        # 等待生成完成
        import time
        time.sleep(2)

# 4. 将视频帧合并为 MP4 视频
def frames_to_video(frames_dir, frame_files, fps=6, output_name="output_video.mp4"):
    # 读取第一帧获取分辨率
    first_frame = cv2.imread(os.path.join(frames_dir, frame_files[0]))
    height, width = first_frame.shape[:2]
    # 定义视频编码器
    fourcc = cv2.VideoWriter_fourcc(*"mp4v")
    video_writer = cv2.VideoWriter(output_name, fourcc, fps, (width, height))
    # 逐帧写入
    for frame_file in frame_files:
        frame_path = os.path.join(frames_dir, frame_files)
        frame = cv2.imread(frame_path)
        video_writer.write(frame)
    video_writer.release()
    print(f"视频已保存为 {output_name}")

# ------------------- 执行主流程 -------------------
if __name__ == "__main__":
    # 提交任务
    prompt_id = submit_video_workflow(video_workflow)
    print(f"任务 ID: {prompt_id}")
    # 获取视频帧
    frame_files = get_video_frames(prompt_id)
    print(f"生成 {len(frame_files)} 帧: {frame_files}")
    # 合并为视频（ComfyUI 输出目录默认是 output）
    frames_to_video("./output", frame_files, fps=6)

五、避坑指南（新手必看）

1. 模型文件必须正确

   • 必须用视频生成模型（SVD/SVD-XT），不能用 SD1.x/SDXL 等文生图模型，否则会报错「缺少 CLIP_VISION」。
   • 文件名必须和 checkpoints 目录下完全一致（含 .safetensors 后缀）。

2. 节点连接不能错索引

   • 下游节点要 CLIP_VISION 时，必须连 节点 1 的索引 1，而不是索引 0 或 2。
   • SVD_img2vid_Conditioning 必须同时传入 clip_vision+vae+init_image，缺一不可。

3. 视频帧数和分辨率匹配

   • SVD 模型最大支持 14 帧，超过会报错；SVD-XT 最大 25 帧。
   • 分辨率推荐 1024×576 或 576×1024，非 16:9 比例可能导致画面拉伸。

4. 运动幅度参数调优

   • motion_bucket_id 是核心：值太小（<50）视频几乎不动；值太大（>200）画面会剧烈抖动、失真。

六、效果优化技巧

• 想让视频运动更自然：降低 motion_bucket_id（如 80-120），提高 steps（如 25-30）。
• 想让视频细节更清晰：降低 augmentation_level（设为 0），提高 cfg 值（如 9-10）。
• 想生成更长视频：换用 SVD-XT 模型，将 video_frames 设为 25，fps 设为 8。