产品文档

选择下方分类查看详细的使用说明

温馨提示: subtitleBase、subtitleDynamic、chromaSub、staticSub、subtitleTimeline、Video2TextAsync、imgUpscale、imgBgRemove、imgBgRemovePro、imgSpot、getImgText、textRes、videoRes、imageModel、imageModelPro、genVideo、cloudCut、templateVideoHighlight、templatePraise、templateHighlightByText 为高级插件，其余均为会员插件

文档分类

云剪辑工具 cloudCut

一、插件简介

插件名称：插件地址 cloudCut

插件功能：cloudCut 智能剪辑服务，通过 API 快速渲染视频，支持图片、视频、GIF、音频、纯色形状等多种媒体类型，提供过渡效果、图层叠加、位置调整等专业功能。

三、顶层参数

字段类型必填默认值说明
widthnumber✅-视频宽度（像素）
heightnumber✅-视频高度（像素）
layersarray✅-图层数组

四、图层 (layers)

每个图层包含一组按时间排列的媒体项 (items)。

"layers": [
  {
    "items": [
      { "type": "image", "url": "...", "startTime": 0, "duration": 5 },
      { "type": "image", "url": "...", "startTime": 5, "duration": 5 }
    ]
  }
]

图层特性：

  • 后面的图层在上方（layers[1] 会覆盖 layers[0]，以此类推）
  • 数组越靠后的图层，显示优先级越高
  • 同一图层内的 items 按时间顺序播放

示例 - 图层顺序：

"layers": [
  {
    "items": [
      { "type": "solid", "color": "transparent", "borderWidth": 5, "borderColor": "#ff0000", "startTime": 0, "duration": 10 }
    ]
  },
  {
    "items": [
      { "type": "image", "url": "background.jpg", "startTime": 0, "duration": 10 }
    ]
  }
]

在这个例子中，圆形标记会显示在背景图片的上方。

五、媒体项 (items) 必需参数

字段类型说明
urlstring媒体文件的 URL（solid 类型不需要）
typestring媒体类型："image", "video", "gif", "audio", "solid"
startTimenumber开始时间（秒）

六、支持的媒体类型

1. 图片image

{
  "type": "image",
  "url": "https://example.com/photo.jpg",
  "startTime": 0,
  "duration": 5
}
字段类型必填默认值说明
durationnumber❌3显示时长（秒）
✨ 自动全屏显示✨ 保持宽高比

2. 视频video

{
  "type": "video",
  "url": "https://example.com/clip.mp4",
  "startTime": 0
}
字段类型必填默认值说明
durationnumber❌自动播放时长（秒），默认使用视频实际时长
✨ 自动全屏显示✨ 保持宽高比✨ 包含音频

3. GIF 动图gif

{
  "type": "gif",
  "url": "https://example.com/animation.gif",
  "startTime": 0,
  "duration": 3
}
字段类型必填默认值说明
durationnumber❌2显示时长（秒），建议提供
✨ 自动循环播放

4. 音频audio

{
  "type": "audio",
  "url": "https://example.com/music.mp3",
  "startTime": 0
}
字段类型必填默认值说明
durationnumber❌自动播放时长（秒），默认匹配视频总时长
✨ 自动匹配所有视觉图层的总时长

5. 纯色形状solid

创建各种形状的图形标记，如圆形、矩形、圆角矩形等

{
  "type": "solid",
  "startTime": 0,
  "duration": 5,
  "position": {
    "x": 100,
    "y": 100,
    "width": 800,
    "height": 600
  },
  "color": "#ff0000",
  "borderWidth": 5,
  "borderColor": "#000000",
  "borderRadius": 20,
  "fadeIn": 0.5,
  "fadeOut": 0.5
}
字段类型必填默认值说明
durationnumber❌3显示时长（秒）
positionobject❌全屏位置和尺寸
colorstring❌#ffffff填充颜色（十六进制或 "transparent"）
borderWidthnumber❌0边框宽度（像素），0 表示无边框
borderColorstring❌#000000边框颜色（十六进制格式）
borderRadiusnumber❌0圆角半径（像素），设为宽度/2 创建圆形
opacitynumber❌1整体不透明度（0-1）
rotationnumber❌0旋转角度（度，顺时针）
fadeInnumber❌0淡入时长（秒）
fadeOutnumber❌0淡出时长（秒）
✨ 标记和强调✨ 圆形指示器✨ 背景遮罩✨ 装饰元素

形状类型：

矩形：borderRadius: 0
圆角矩形：borderRadius: 10-50（取决于尺寸）
圆形：borderRadius = 宽度的一半，且宽高相等
空心形状：color: "transparent" + borderWidth > 0
示例 1：实心圆形标记
{
  "type": "solid",
  "startTime": 2,
  "duration": 3,
  "position": {
    "x": 400,
    "y": 800,
    "width": 200,
    "height": 200
  },
  "color": "#ff0000",
  "opacity": 0.7,
  "borderRadius": 100,
  "fadeIn": 0.5,
  "fadeOut": 0.5
}

效果：红色半透明圆形，带淡入淡出效果

示例 2：空心圆圈（推荐用于标记）
{
  "type": "solid",
  "startTime": 0,
  "duration": 5,
  "position": {
    "x": 400,
    "y": 800,
    "width": 300,
    "height": 300
  },
  "color": "transparent",
  "borderWidth": 10,
  "borderColor": "#ff0000",
  "borderRadius": 150,
  "fadeIn": 0.3,
  "fadeOut": 0.3
}

效果：红色空心圆圈，适合用于突出显示

示例 3：带动画的标记
{
  "type": "solid",
  "startTime": 1,
  "duration": 2,
  "position": {
    "x": 500,
    "y": 900,
    "width": 150,
    "height": 150
  },
  "color": "transparent",
  "borderWidth": 8,
  "borderColor": "#00ff00",
  "borderRadius": 75,
  "fadeIn": 0.4,
  "fadeOut": 0.6
}

效果：绿色圆圈，慢慢淡入，更慢地淡出

七、位置和尺寸 (position)

默认行为：所有图片、视频、GIF、solid 都会全屏显示。如需自定义位置和大小，可使用 position 参数。

{
  "type": "image",
  "url": "https://example.com/photo.jpg",
  "startTime": 0,
  "duration": 5,
  "position": {
    "x": 100,
    "y": 100,
    "width": 800,
    "height": 600
  }
}
字段类型必填说明
xnumber✅左上角 X 坐标（像素）
ynumber✅左上角 Y 坐标（像素）
widthnumber✅宽度（像素）
heightnumber✅高度（像素）

常见布局示例

居中小窗口

画布：1920x1080

"position": {
"x": 460,
"y": 290,
"width": 1000,
"height": 500
}
画中画 - 右下角

画布：1920x1080

"position": {
"x": 1440,
"y": 780,
"width": 400,
"height": 225
}
左侧分屏

画布：1920x1080

"position": {
"x": 0,
"y": 0,
"width": 960,
"height": 1080
}

注意：音频 item 不需要 position 参数；solid 类型通常需要 position 参数来指定形状的位置和大小

八、过渡效果 (transition)

在相邻的两个 items 之间创建转场动画。

{
  "type": "image",
  "url": "...",
  "startTime": 6,
  "duration": 6,
  "transition": {
    "type": "flip",
    "direction": "from-left",
    "duration": 1
  }
}
字段类型必填默认值说明
typestring✅-过渡类型
directionstring❌from-left方向（部分类型支持）
durationnumber❌0.5过渡时长（秒）

过渡类型

类型说明支持方向
fade淡入淡出-
slide滑动from-left, from-right, from-top, from-bottom
wipe擦除from-left, from-right, from-top, from-bottom
flip翻转from-left, from-right
clockWipe时钟擦除-
iris光圈-

注意：

  • 第一个 item 不支持 transition（前面没有 item）
  • 过渡会导致总时长缩短（两个片段重叠）

九、核心功能特性

●多图层叠加

支持无限图层叠加，后面的图层显示在上方，可创建复杂的视频效果

●丰富的媒体类型

支持图片、视频、GIF、音频、纯色形状等多种媒体类型

●专业过渡效果

提供 6 种过渡效果：淡入淡出、滑动、擦除、翻转、时钟擦除、光圈

●精确位置控制

支持自定义媒体的位置、大小、旋转、透明度等属性

●图形标记功能

可创建圆形、矩形、圆角矩形等形状，支持空心、实心、淡入淡出等效果

●自动音频匹配

音频自动匹配视频总时长，无需手动计算

十、应用场景

🎬

图片幻灯片

快速制作带过渡效果的图片幻灯片视频，配上背景音乐

📚

教学视频

在视频上添加标记圆圈、箭头等元素，突出重点内容

🛍️

产品展示

制作产品展示视频，使用标记功能突出产品特点

📱

社交媒体内容

快速生成适合各平台的竖屏、横屏、方形视频

🎨

创意视频

利用多图层叠加和过渡效果，制作创意视频内容

📊

数据可视化

使用纯色形状和图层功能，制作动态数据展示视频

十一、完整的真实调用示例

coze调取示例

{
  "apiKey": "76caed4ead074de39d6b6a4d9b41f6d9",
  "height": 1920,
  "width": 1080,
  "layers": [
    {
      "items": [
        {
          "duration": 2.5,
          "position": {
            "height": 224,
            "width": 224,
            "x": 50,
            "y": 1580
          },
          "startTime": 0,
          "type": "gif",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif"
        },
        {
          "duration": 2.5,
          "position": {
            "height": 273,
            "width": 273,
            "x": 706,
            "y": 1522
          },
          "startTime": 3,
          "type": "gif",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif"
        },
        {
          "duration": 2.5,
          "position": {
            "height": 302,
            "width": 302
          },
          "startTime": 6,
          "type": "gif",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif"
        }
      ]
    },
    {
      "items": [
        {
          "duration": 3,
          "startTime": 0,
          "type": "image",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image1.png"
        },
        {
          "duration": 3,
          "startTime": 3,
          "transition": {
            "direction": "from-left",
            "duration": 0.5,
            "type": "wipe"
          },
          "type": "image",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image2.png"
        },
        {
          "duration": 3,
          "startTime": 6,
          "transition": {
            "direction": "from-left",
            "duration": 0.5,
            "type": "iris"
          },
          "type": "image",
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image3.png"
        }
      ]
    },
    {
      "items": [
        {
          "duration": 0,
          "startTime": 0,
          "type": "audio",
          "url": "https://ff-editor.s3.ap-southeast-1.amazonaws.com/1cc0b7fc-a6f1-4ded-8ff6-fee9b96c1c3d"
        }
      ]
    }
  ]
}
{
  "aboutUrl": "https://framefuture.com/",
  "code": 0,
  "errorMessage": "成功",
  "outputSizeInBytes": 4002907,
  "outputUrl": "https://media.framefuture.cn/editor-export-1762068220833-nc68686.mp4",
  "traceId": "5da6bd9f-1a58-4acd-b9e8-414839897c12"
}

API请求示例

curl --request POST \
  --url https://agent.framefuture.com/minimalist/api/smart-clip/render \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 76caed4ead074de39d6b6a4d9b41f6d9' \
  --data '{
  "width": 1080,
  "height": 1920,
  "layers": [
    {
      "items": [
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif",
          "type": "gif",
          "startTime": 0,
          "duration": 5,
          "position": {
            "x": 50,
            "y": 1580,
            "width": 224,
            "height": 224
          }
        },
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif",
          "type": "gif",
          "startTime": 5,
          "duration": 5,
          "position": {
            "x": 706,
            "y": 1522,
            "width": 273,
            "height": 273
          }
        },
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/demo-oi.gif",
          "type": "gif",
          "startTime": 10,
          "duration": 5,
          "position": {
            "x": 724,
            "y": 81,
            "width": 302,
            "height": 302
          }
        }
      ]
    },
    {
      "items": [
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image1.png",
          "type": "image",
          "startTime": 0,
          "duration": 6
        },
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image2.png",
          "type": "image",
          "startTime": 6,
          "duration": 6,
          "transition": {
            "type": "clockWipe",
            "direction": "from-left",
            "duration": 1
          }
        },
        {
          "url": "https://framefuturedemo.oss-cn-beijing.aliyuncs.com/9x16-image3.png",
          "type": "image",
          "startTime": 12,
          "duration": 5,
          "transition": {
            "type": "iris",
            "direction": "from-left",
            "duration": 1
          }
        }
      ]
    },
    {
      "items": [
        {
          "url": "https://ff-editor.s3.ap-southeast-1.amazonaws.com/1cc0b7fc-a6f1-4ded-8ff6-fee9b96c1c3d",
          "type": "audio",
          "startTime": 0,
          "duration": 0
        }
      ]
    }
  ]
}'
{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "390eab24-f8ba-4d11-93bc-817776d49150",
  "apiId": "smart-clip",
  "outputUrl": "https://media.framefuture.cn/editor-export-1762132016222-z4d23eh.mp4",
  "outputSizeInBytes": 7914581,
  "outputName": "editor-export-1762132016222-z4d23eh.mp4",
  "cost": 0.04666666666666667,
  "billingDescription": "智能剪辑服务 - 渲染时长: 11.37秒, 输出大小: 7.55MB",
  "renderTimeInSeconds": 11.367,
  "created": 1762132027
}

十二、完整示例

最小示例

基础的图片展示

{
  "width": 1080,
  "height": 1920,
  "layers": [
    {
      "items": [
        {
          "url": "https://example.com/photo.jpg",
          "type": "image",
          "startTime": 0,
          "duration": 5
        }
      ]
    }
  ]
}

图片幻灯片 + 背景音乐

竖屏视频格式，3 张图片带过渡效果，配背景音乐

{
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "codec": "h264",
  "layers": [
    {
      "items": [
        {
          "url": "https://example.com/photo1.jpg",
          "type": "image",
          "startTime": 0,
          "duration": 6
        },
        {
          "url": "https://example.com/photo2.jpg",
          "type": "image",
          "startTime": 6,
          "duration": 6,
          "transition": {
            "type": "iris",
            "duration": 1
          }
        },
        {
          "url": "https://example.com/photo3.jpg",
          "type": "image",
          "startTime": 12,
          "duration": 6,
          "transition": {
            "type": "flip",
            "direction": "from-left",
            "duration": 1
          }
        }
      ]
    },
    {
      "items": [
        {
          "url": "https://example.com/music.mp3",
          "type": "audio",
          "startTime": 0
        }
      ]
    }
  ]
}

说明：

  • 竖屏视频格式 (9:16)
  • 3 张图片，每张 6 秒，带过渡效果
  • 音频自动匹配总时长（约 16 秒，考虑 2 秒过渡重叠）

示例 2：带图形标记的视频

在背景图片上添加两个标记圆圈，适合教学视频、产品展示

{
  "width": 1080,
  "height": 1920,
  "fps": 30,
  "codec": "h264",
  "layers": [
    {
      "items": [
        {
          "type": "solid",
          "startTime": 2,
          "duration": 3,
          "position": {
            "x": 390,
            "y": 810,
            "width": 300,
            "height": 300
          },
          "color": "transparent",
          "borderWidth": 10,
          "borderColor": "#ff0000",
          "borderRadius": 150,
          "fadeIn": 0.5,
          "fadeOut": 0.5
        },
        {
          "type": "solid",
          "startTime": 6,
          "duration": 3,
          "position": {
            "x": 740,
            "y": 560,
            "width": 200,
            "height": 200
          },
          "color": "transparent",
          "borderWidth": 8,
          "borderColor": "#00ff00",
          "borderRadius": 100,
          "fadeIn": 0.3,
          "fadeOut": 0.3
        }
      ]
    },
    {
      "items": [
        {
          "url": "https://example.com/background.jpg",
          "type": "image",
          "startTime": 0,
          "duration": 10
        }
      ]
    }
  ]
}

说明：

  • 第一层：背景图片（10 秒）
  • 第二层：两个标记圆圈
    • 红色圆圈：2-5 秒出现，带淡入淡出
    • 绿色圆圈：6-9 秒出现，快速淡入淡出
  • 适合用于教学视频、产品展示等需要标记重点的场景

示例 3：多层标记 + 动态效果

视频背景 + 遮罩 + 提示框，适合用于视频引导、开场效果等

{
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "codec": "h264",
  "layers": [
    {
      "items": [
        {
          "url": "https://example.com/video.mp4",
          "type": "video",
          "startTime": 0
        }
      ]
    },
    {
      "items": [
        {
          "type": "solid",
          "startTime": 0,
          "duration": 3,
          "position": {
            "x": 0,
            "y": 0,
            "width": 1920,
            "height": 1080
          },
          "color": "#000000",
          "opacity": 0.5,
          "fadeOut": 1
        }
      ]
    },
    {
      "items": [
        {
          "type": "solid",
          "startTime": 5,
          "duration": 2,
          "position": {
            "x": 810,
            "y": 440,
            "width": 300,
            "height": 200
          },
          "color": "#ff6b6b",
          "opacity": 0.8,
          "borderRadius": 20,
          "fadeIn": 0.3,
          "fadeOut": 0.3
        }
      ]
    }
  ]
}

说明：

  • 第一层：视频背景
  • 第二层：黑色半透明遮罩（开始 3 秒），渐渐淡出
  • 第三层：红色圆角矩形提示框（5-7 秒）
  • 适合用于视频引导、开场效果等

十三、响应格式

✅ 成功响应 (200 OK)

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "390eab24-f8ba-4d11-93bc-817776d49150",
  "apiId": "smart-clip",
  "outputUrl": "https://media.framefuture.cn/editor-export-xxx.mp4",
  "outputSizeInBytes": 7914581,
  "outputName": "editor-export-xxx.mp4",
  "cost": 0.047,
  "billingDescription": "智能剪辑服务 - 渲染时长: 11.37秒, 输出大小: 7.55MB",
  "renderTimeInSeconds": 11.367,
  "created": 1762132027
}

❌ 错误响应 (400/500)

{
  "type": "error",
  "error": "错误信息"
}

十四、常见问题

Q1.视频总时长如何计算？

总时长 = 所有 items 的时长 - 过渡效果重叠的时长

示例：
  • 3 个图片，每个 6 秒 = 18 秒
  • 2 个过渡，每个 1 秒 = 3 秒重叠
  • 实际总时长 = 18 - 3 = 15 秒

Q2.音频如何匹配视频长度？

如果音频 item 不提供 duration，会自动匹配所有视觉图层的总时长（已考虑过渡重叠）

Q3.媒体文件有什么要求？

URL 必须公开可访问（支持 HTTP/HTTPS）

支持格式：
图片:JPG, PNG, WebP
视频:MP4, MOV, WebM
音频:MP3, WAV, AAC
GIF:标准 GIF
纯色形状 (solid):不需要 URL，通过代码生成

Q4.如何调整媒体位置和大小？

默认全屏显示。如需自定义位置，可使用 position 参数指定 x、y、width、height

Q5.如何创建圆形或空心形状？

使用 solid 类型：

  • 圆形: 设置 borderRadius 为宽度的一半（需要宽高相等）
  • 空心形状: 设置 color 为 "transparent"，并设置 borderWidth 和 borderColor

详见上方 纯色形状 (solid) 章节的示例。

Q6.如何实现淡入淡出效果？

所有视觉类型（image、video、gif、solid）都支持 fadeIn 和 fadeOut 参数

{
  "type": "solid",
  "fadeIn": 0.5,
  "fadeOut": 1.0
}
应用场景：
  • 平滑的标记出现/消失
  • 避免突兀的画面切换
  • 创建更专业的视觉效果
最佳实践：淡入 0.3-0.5 秒（快速出现），淡出 0.5-1.0 秒（缓慢消失）

Q7.图形标记最佳实践

空心圆圈用于标记

{
  "type": "solid",
  "color": "transparent",
  "borderWidth": 8-15,
  "borderRadius": 宽度/2
}

添加淡入淡出

淡入：0.3-0.5 秒（快速出现）；淡出：0.5-1.0 秒（缓慢消失）

调整透明度

强调标记：opacity: 0.8-1.0；柔和提示：opacity: 0.5-0.7

图层顺序

背景内容放在前面的 layer；标记放在后面的 layer（覆盖在上层）

十五、使用技巧与注意事项

💡图层顺序

后面的图层会覆盖前面的图层（layers[1] 覆盖 layers[0]），标记元素应放在后面的图层

💡视频时长计算

总时长 = 所有 items 的时长 - 过渡效果重叠的时长。例如：3个6秒的图片 + 2个1秒的过渡 = 16秒

💡音频自动匹配

如果音频不提供 duration，会自动匹配所有视觉图层的总时长（已考虑过渡重叠）

💡创建圆形标记

设置 borderRadius 为宽度的一半（需要宽高相等），空心圆圈设置 color 为 "transparent"

💡淡入淡出效果

建议淡入 0.3-0.5 秒（快速出现），淡出 0.5-1.0 秒（缓慢消失）

💡媒体文件要求

URL 必须公开可访问（支持 HTTP/HTTPS），确保文件格式正确

📚 相关文档

音视频合成工具

音视频文案提取类

Nano Banana 插件