Skill 安装

VectCut Skill 把当前服务的真实 HTTP 接口封装成一份 Codex skill，只调用你自己的服务，只包含当前服务真实存在的接口。

下载

下载 vectcut-skill.zip

安装到 Codex

解压后确认目录结构如下，SKILL.md 必须直接位于 vectcut-api 目录下：

vectcut-api/
  SKILL.md
  agents/
    openai.yaml
  scripts/
    vectcut_client.py
    sync_draft_materials.py
  references/
    api_reference.md
    material_sync.md
    workflows.md

Windows 放到：

%USERPROFILE%\.codex\skills\vectcut-api

macOS 或 Linux 放到：

~/.codex/skills/vectcut-api

配置

skill 从环境变量读取服务地址和密钥，不会把真实域名、服务器 IP 或 API Key 写进文件。

PowerShell 当前会话：

$env:VECTCUT_BASE_URL="https://your-domain.example/api"
$env:VECTCUT_API_KEY="<你的 API Key>"

需要长期保存时，可以在系统环境变量里设置同名变量。

使用

安装后在 Codex 里直接说：

使用 vectcut-api 创建一条 1080x1920 草稿，先获取视频时长，再添加视频和标题，最后导出草稿。

也可以直接运行 skill 自带的客户端：

python scripts/vectcut_client.py duration "https://example.com/clip.mp4"
python scripts/vectcut_client.py types get_transition_types
python scripts/vectcut_client.py create --width 1080 --height 1920

复杂任务优先使用 scripts/vectcut_client.py 里的 VectCutClient，参数说明见 references/api_reference.md。

本地素材和 URL 素材

服务端只保存草稿结构，不会下载或转存素材。素材来源必须明确选择一种，两种模式不会自动互相兜底：

• --source local：只使用本地素材目录、本地素材清单或 --material-map 指定的文件。
• --source url：只下载草稿 assets[].url 中的素材，不读取本地目录和本地清单。

本地图片可以直接登记到草稿，不需要上传到服务器：

from vectcut_client import VectCutClient

client = VectCutClient()
draft_id = client.create_draft(width=1080, height=1920)["draft_id"]
client.add_local_image(
    draft_id,
    r"D:\素材\封面.jpg",
    start=0,
    end=5,
)

本地视频或音频必须提供已知的 duration 或 end。需要服务端自动获取时长时，改用 URL 调用 get_duration：

media = client.get_duration("https://example.com/clip.mp4")
duration = media["duration"]
client.add_video(
    draft_id,
    "https://example.com/clip.mp4",
    start=0,
    end=duration,
    duration=duration,
)

同步本地草稿：

python scripts/sync_draft_materials.py `
  --source local `
  --draft-id "dfd_cat_xxx" `
  --draft-root "C:\Users\<你>\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft" `
  --materials-dir "D:\素材"

如果本地文件名和草稿 URL 文件名不一致，显式映射：

python scripts/sync_draft_materials.py `
  --source local `
  --draft-id "dfd_cat_xxx" `
  --materials-dir "D:\素材" `
  --material-map "1=D:\素材\封面.jpg" `
  --material-map "__VECTCUT_ASSET_0002__=D:\素材\片段.mp4"

先查看草稿素材序号、名称、URL 和占位符：

python scripts/sync_draft_materials.py --draft-id "dfd_cat_xxx" --list-assets