VectCutAPI

主题

大模型用法 ​

这份说明用于让大模型直接理解接口的调用顺序、参数关系和返回处理方式。接口地址以当前部署为准，下面用 BASE_URL 表示。

先记住四件事 ​

  1. 所有请求都带 X-API-Key，只有 /health 不需要。
  2. 时间单位是秒，不是毫秒。
  3. GET 接口只用来查询类型和元数据，不修改草稿。
  4. POST 接口用来创建草稿、添加素材、添加效果或保存草稿。

推荐调用顺序 ​

text
create_draft
  -> get_duration（视频/音频需要时长时）
  -> 查询所需类型（GET）
  -> 添加视频/图片/音频/文字/字幕
  -> 添加转场、蒙版、关键帧、特效、贴纸、滤镜
  -> query_script 检查结构
  -> export_draft 或 save_draft

create_draft 返回的 output.draft_id 是后续所有操作的句柄。除创建新草稿外，后续 POST 都要把同一个 draft_id 传回去。

素材来源规则 ​

素材来源必须由用户明确选择，不能在本地素材和 URL 之间自动切换。

  • 本地图片：使用 add_local_image() 或 skill 的 local-add 登记本地路径，服务端只收到占位 URL。
  • 本地视频/音频：可以使用，但必须提供已知的 duration 或 end。
  • 需要自动查询时长：只使用 URL，调用 get_duration；不要把本地路径传给 get_duration。
  • 同步本地草稿时：--source local 只复制本地文件；--source url 只下载 URL。
  • 本地文件名和 URL 文件名不一致时，使用 --material-map 显式指定对应关系。

按功能选择接口 ​

我想做什么先查询再执行
加转场GET /get_transition_typesPOST /add_video 或 POST /add_image，传 transition
新建时加蒙版GET /get_mask_typesPOST /add_video 或 POST /add_image，传 mask_type
给已有片段加蒙版GET /get_mask_typesPOST /add_masks
加蒙版关键帧先调用 POST /add_masksPOST /add_mask_keyframes
加画面关键帧无POST /add_video_keyframe
加特效GET /get_video_scene_effect_types 或 GET /get_video_character_effect_typesPOST /add_effect
加贴纸POST /search_stickerPOST /add_sticker
加滤镜GET /get_filter_typesPOST /add_filter
加花字GET /get_text_effectsPOST /add_text，传 effect_effect_id
关键词高亮无POST /add_text_style，再把 text_styles 传给 POST /add_text
美颜、美型、美妆、美体无POST /add_beauty
获取素材时长无POST /get_duration

接口功能速查 ​

接口功能方法
get_text_animations文本动画本服务已拆成 GET /get_text_intro_types、GET /get_text_outro_types、GET /get_text_loop_anim_types
get_text_effects花字效果GET 或 POST
get_image_animations图片动画复用 GET /get_intro_animation_types、GET /get_outro_animation_types
add_masks给已有片段添加蒙版POST
add_mask_keyframes蒙版位置、大小、羽化、旋转关键帧POST
add_beauty美颜、美型、美妆、美体POST
add_text_style生成关键词高亮样式POST

获取视频或音频时长 ​

视频和音频的 end、duration 都使用秒。素材在远端时，先调用 POST /get_duration，不要凭感觉填写时长。

get_duration 只支持 URL，不支持本地文件路径。本地视频或音频必须由用户提供已知的 duration 或 end；如果用户要求自动获取时长，应改用 URL。

json
{
  "url": "https://example.com/clip.mp4"
}

url 和 video_url 都可以，传其中一个即可。接口会用 ffprobe 探测真实时长，最多重试 3 次，每次超时 10 秒。

成功返回：

json
{
  "success": true,
  "output": {
    "duration": 12.345,
    "format": "mp4"
  },
  "error": ""
}

拿到时长后再添加素材：

json
{
  "draft_id": "dfd_cat_xxx",
  "video_url": "https://example.com/clip.mp4",
  "start": 0,
  "end": 12.345,
  "duration": 12.345
}

end 表示截取到源素材的第几秒，duration 表示素材真实总时长。音频同理。没有先获取时长时，服务端会把视频元数据时长先记为 0，等本地下载器处理时再补真实时长；需要服务端草稿立即有正确时间轴时，应当先调用 get_duration。

转场和蒙版 ​

转场在创建片段时通过 add_video 或 add_image 的参数传入。蒙版既可以在创建片段时传入，也可以稍后通过 add_masks 给已有片段添加。

json
{
  "draft_id": "dfd_cat_xxx",
  "video_url": "https://example.com/clip.mp4",
  "start": 0,
  "end": 5,
  "transition": "叠化",
  "transition_duration": 0.5,
  "mask_type": "线性",
  "mask_center_x": 0.5,
  "mask_center_y": 0.5,
  "mask_size": 1.0,
  "mask_feather": 0.0
}

transition 和 mask_type 的值必须先通过对应的 GET 接口查询，不要凭空编造。

蒙版和蒙版关键帧 ​

先给已有片段添加蒙版：

json
{
  "draft_id": "dfd_cat_xxx",
  "segment_ids": ["a1b2c3d4e5f6"],
  "name": "圆形",
  "X": 0,
  "Y": 0,
  "width": 720,
  "height": 720,
  "feather": 20,
  "rotation": 0
}

然后添加蒙版关键帧。offset 的单位是秒，和本服务其他时间参数一致：

json
{
  "draft_id": "dfd_cat_xxx",
  "keyframes": [
    {
      "segment_id": "a1b2c3d4e5f6",
      "offset": 0,
      "X": -100,
      "width": 500,
      "height": 500
    },
    {
      "segment_id": "a1b2c3d4e5f6",
      "offset": 2.5,
      "X": 100,
      "rotation": 45
    }
  ]
}

关键帧 ​

add_video_keyframe 支持单关键帧和多关键帧：

json
{
  "draft_id": "dfd_cat_xxx",
  "track_name": "video_main",
  "property_type": "alpha",
  "time": 0.0,
  "value": "1.0"
}

多关键帧使用 property_types、times、values 三个数组，数组长度必须一致。

蒙版关键帧是独立接口 add_mask_keyframes，不要和 add_video_keyframe 混用。

特效 ​

先选分类，再添加：

text
GET /get_video_scene_effect_types
GET /get_video_character_effect_types
POST /add_effect
json
{
  "draft_id": "dfd_cat_xxx",
  "effect_type": "星光",
  "effect_category": "scene",
  "start": 0,
  "end": 3
}

effect_category 只能是 scene 或 character。如果类型来自人物特效接口，就传 character。

贴纸 ​

先搜索剪映贴纸，再把返回的 sticker_id 交给 add_sticker：

text
POST /search_sticker
POST /add_sticker

搜索：

json
{
  "keywords": "生日快乐",
  "count": 5,
  "offset": 0
}

count 控制本次返回几条，默认建议先取 5 条。展示搜索结果时只展示 sticker_id、size、aspect_ratio、url、format 和数量，不展示预览图；用户选定后再把对应 sticker_id 传给 add_sticker。output.total 只是匹配总数，不代表本次全部返回。

添加：

json
{
  "draft_id": "dfd_cat_xxx",
  "sticker_id": "7069661365685832990",
  "start": 0,
  "end": 5,
  "transform_x": 0,
  "transform_y": 0,
  "scale_x": 1,
  "scale_y": 1
}

search_sticker 搜索的是服务器本地保存的剪映贴纸索引，不调用第三方 API。索引中的 ID 仍是剪映贴纸 ID；草稿不会下载或转存贴纸图片。

文字与字幕 ​

add_text 和 add_subtitle 用途不同：

接口用途输入
POST /add_text添加一条标题、说明或重点文字直接传 text
POST /add_subtitle批量添加整段视频字幕传 SRT 内容或 SRT 地址到 srt

只需要一条文字时用 add_text；有多条带时间码的字幕时用 add_subtitle。字幕参数名是 srt，不是 srt_url。

花字和关键词高亮 ​

先查询花字：

text
GET /get_text_effects?keyword=清新&count=5

把返回的 id 传给 add_text 的 effect_effect_id。

关键词高亮先调用 add_text_style：

json
{
  "text": "今天分享三个剪辑技巧",
  "keyword": "剪辑|技巧",
  "font_size": 12,
  "keyword_color": "#ff7100",
  "keyword_font_size": 15
}

再把返回的 text_styles 数组原样传给 add_text 的 text_styles。

美颜、美型、美妆、美体 ​

add_beauty 的四个分组都可以单独使用：

json
{
  "draft_id": "dfd_cat_xxx",
  "segment_ids": ["a1b2c3d4e5f6"],
  "skin": {
    "smooth": 50,
    "whitening": 30
  },
  "shape": {
    "small_face": 20,
    "slim": 30
  },
  "makeup": {
    "look": "淡人妆",
    "intensity": 80
  },
  "body": {
    "slim_waist": 30
  }
}

滑杆值为 0 时不写入；makeup.look 使用剪映中文妆容名。

滤镜 ​

先查询滤镜类型，再添加：

text
GET /get_filter_types
POST /add_filter
json
{
  "draft_id": "dfd_cat_xxx",
  "filter_type": "清透",
  "start": 0,
  "end": 5,
  "intensity": 80
}

intensity 范围是 0-100。不确定滤镜名称时，先调用 get_filter_types，从返回列表中选择 name。

返回处理 ​

所有接口统一返回：

json
{
  "success": true,
  "output": {},
  "error": ""
}

大模型应先判断 success。为 false 时读取 error，不要继续把空 output 当作成功结果。

常见错误 ​

错误原因处理
unauthorized缺少或填错 API Key检查 X-API-Key
Unknown filter type滤镜名称不在类型列表中先调用 get_filter_types
Unknown scene effect type特效分类或名称错误先查询对应特效类型
end must be greater than start时间范围无效保证 end > start
找不到草稿draft_id 丢失或写错使用 create_draft 返回的 ID

给 Agent 的简短系统提示 ​

text
你是剪映草稿编辑 Agent。先调用 create_draft 获取 draft_id。
GET 接口只查询类型，POST 接口才修改草稿。
转场通过 add_video 或 add_image 的参数传入；蒙版可用 add_masks。
画面关键帧用 add_video_keyframe，蒙版关键帧用 add_mask_keyframes。
特效、贴纸、滤镜、花字、美颜分别使用对应 POST 接口。
所有时间单位是秒。添加前先查询类型列表，不要编造类型名称。
视频或音频时长不确定时，先调用 get_duration，再用返回的 duration 设置 end 和 duration。
get_duration 只接受 URL；本地视频或音频必须提供已知的 duration 或 end。
本地素材和 URL 素材必须由用户明确选择，不能自动互相兜底。
完成后调用 query_script 检查，再调用 save_draft 或 export_draft。

个人自建服务

VectCutAPI