libtv-skill-pro#

Fork of @haofanwang/libtv-skill — 在原版基础上扩展高级工作流与功能矩阵层。Source / Issues: https://github.com/Qiuxiangxiang/libtv-skill-pro

LibTV (liblib.tv) 是 LiblibAI 推出的 AI 视频创作平台。本 skill 让 Agent 通过统一入口 libtv.py 完成生成 / 编辑 / 修饰 / 模型路由的全链路。

快速开始（3 分钟跑通第一个 case）#

bash

# 1. 拿 access key：https://www.liblib.tv → 用户中心 → API / 开发者
export LIBTV_ACCESS_KEY=your_key_here

# 2. 看完整命令清单
python3 {baseDir}/scripts/libtv.py --help

# 3. 跑第一个 case（dry-run 预览，不烧积分）
python3 {baseDir}/scripts/libtv.py model with lib-nano-pro \
  "白色短毛猫坐在窗台上" --ratio 1:1 --resolution 2K --dry-run

# 4. 去掉 --dry-run 真实生成（≈14 积分，≈60s）
python3 {baseDir}/scripts/libtv.py model with lib-nano-pro \
  "白色短毛猫坐在窗台上" --ratio 1:1 --resolution 2K
# → 返回 sessionId，再用 poll 等结果，download 取本地

python3 {baseDir}/scripts/libtv.py poll <SESSION_ID>
python3 {baseDir}/scripts/libtv.py download <SESSION_ID> --output-dir ~/Downloads/cat

5 个完整 case 见 examples/（图像 / 视频 / 编辑 / 多步链 / 批量）。

推荐入口： libtv.py <subcommand>#

所有功能聚合在一个入口，Agent 路由更顺：

text

python3 libtv.py flow       <preset> "<topic>" [--ref URL]
python3 libtv.py node       <action> "<topic>" [--ref URL]
python3 libtv.py edit       <modifier> "<desc>" [--target URL] [--session-id SID]
python3 libtv.py model      list|with <model> "<prompt>" [params]

python3 libtv.py session    "<message>"               # 创建会话/发消息（底层）
python3 libtv.py query      <SID>                     # 查询会话进展
python3 libtv.py upload     <local_file>              # 上传到 OSS
python3 libtv.py download   <SID> [--output-dir DIR]  # 下载结果

python3 libtv.py batch      --file tasks.txt --workers 5
python3 libtv.py monitor    <SID> --poll --extract-urls
python3 libtv.py poll       <SID>
python3 libtv.py template   <name> "<topic>"
python3 libtv.py export     <SID> --format html
python3 libtv.py history    list|add|show|get|remove
python3 libtv.py project    list|current|switch|use|remove|describe

旧路径 python3 scripts/<name>.py ... 仍可用（向后兼容）。新代码统一用 libtv.py。

决策树（路由判断）#

收到用户需求时，按以下顺序匹配：

用户输入走哪条路径用户提供了本地文件（图/视频/音频路径）先 upload 拿 OSS URL，再发到下一步模糊一句话「画只猫 / 做个 MV」session 让后端 Agent 路由（最省心）明确想要 LibTV 某个入口（"做个角色三视图"）flow <preset>明确想用某个模型（"用 Seedance 出视频"）model with <model>想在已生成内容上改风格 / 加运镜edit <modifier> --session-id SID一次发 10+ 任务batch --file tasks.txt --workers 5完整短剧 / MV / 角色设计预设template <name>等结果 / 查进度poll（简单等）或 monitor（看过程）取结果download <SID>

永远先 --dry-run 预览：每个生成类子命令（flow/node/edit/model）都支持 --dry-run，会输出 JSON 显示 will-send prompt 而不调 API。

已知模型（用 libtv.py model list 查最新）#

类型模型适用LLMgvlm-3.1剧本/广告词/品牌文案/提示词改写图像lib-nano-pro快速生图、图生图、高清化图像nano-banana平面海报/插画（Google Gemini 系）图像midjourney美学风/插画/海报图像seedream-5.0写实/电影感（豆包系）视频seedance-2.0-vip文生/图生视频、短片（默认）视频kling-3.0写实人像、动作连贯视频kling-o3高质量长视频视频wan-2.6多镜头长视频（通义万相）

模型参数： --ratio 16:9 --resolution 720P|2K --duration 5s --count "1张"

错误响应（v0.4.0+ 结构化）#

所有 API 错误以 JSON 写到 stderr，便于 Agent 程序化处理：

json

{
  "error": {
    "kind": "INVALID_ACCESS_KEY",
    "http_code": 401,
    "message": "accessKey 不存在或无效",
    "raw": "{...}"
  }
}

错误 kind 清单： INVALID_ACCESS_KEY / FORBIDDEN_OR_INSUFFICIENT_CREDITS / NOT_FOUND / TIMEOUT / RATE_LIMITED / SERVER_ERROR / BAD_GATEWAY / SERVICE_UNAVAILABLE / GATEWAY_TIMEOUT / NETWORK_ERROR / INTERRUPTED / UNKNOWN。

16 类能力详解#

详细说明继续保留以便深度使用，但 优先看 examples/ 和决策树。

1. 创建会话 / 发送消息 — libtv.py session#

bash

# 自然语言发消息（后端 Agent 自己路由模型）
python3 libtv.py session "生一个动漫视频"

# 续聊已有会话
python3 libtv.py session "再来一张风景图" --session-id SID

2. 查询会话进展 — libtv.py query#

bash

python3 libtv.py query SID --after-seq 5       # 增量拉取
python3 libtv.py query SID --project-id PUUID  # 附带项目地址

3. 上传文件 — libtv.py upload#

支持图片 / 视频，≤ 200MB。返回 OSS URL。

bash

python3 libtv.py upload /path/to/image.png
python3 libtv.py upload /path/to/video.mp4

4. 下载结果 — libtv.py download#

bash

python3 libtv.py download SID --output-dir ~/Downloads/proj --prefix scene
python3 libtv.py download --urls URL1 URL2 --output-dir ./out   # 直接给 URL 列表

5. 批量任务 — libtv.py batch#

bash

python3 libtv.py batch --file tasks.txt --workers 5 --output result.json
python3 libtv.py batch -m "猫" -m "狗" -m "鸟"

6. 实时监控 — libtv.py monitor#

bash

python3 libtv.py monitor SID --poll --interval 15 --extract-urls
python3 libtv.py monitor SID --poll --format json --output log.json

7. 简化轮询 — libtv.py poll#

bash

python3 libtv.py poll SID                            # 默认 8s 间隔，10 分钟超时
python3 libtv.py poll SID --interval 5 --timeout 300
python3 libtv.py poll SID --quiet                    # 只输出最终结果

8. 工作流模板 — libtv.py template#

bash

python3 libtv.py template --list
python3 libtv.py template storyboard "科幻城市的故事"
python3 libtv.py template short_drama "友情故事"
python3 libtv.py template music_video "悲伤钢琴曲"

8 个模板：storyboard / character_design / video_generation / image_generation / style_transfer / short_drama / music_video / product_showcase

9. 结果导出 — libtv.py export#

bash

python3 libtv.py export SID --format html --output report.html
python3 libtv.py export SID --format markdown --output report.md
python3 libtv.py export SID --urls-only

10. 会话历史 — libtv.py history#

bash

python3 libtv.py history list
python3 libtv.py history add SID --desc "项目描述"
python3 libtv.py history get 1     # 拿到 sessionId（脚本用）
python3 libtv.py history remove 1

11. 项目管理 — libtv.py project#

bash

python3 libtv.py project list                # 列本地记录
python3 libtv.py project current             # 当前项目
python3 libtv.py project switch --desc "短剧 A"   # 创建新项目
python3 libtv.py project use PUUID           # 切到指定项目
python3 libtv.py project describe PUUID "MV"
python3 libtv.py project remove PUUID

本地状态： ~/.libtv_projects.json。

12. 预设流程 — libtv.py flow#

bash

python3 libtv.py flow story_script "机器人来到唐朝"
python3 libtv.py flow character_views "穿汉服的赛博朋克少女"
python3 libtv.py flow keyframe_to_video "拔剑出鞘" --ref OSS_URL
python3 libtv.py flow audio_to_video "暗黑风 MV" --ref OSS_URL

13. 节点能力 — libtv.py node#

bash

# 文本节点
python3 libtv.py node text_to_video_prompt "一只猫在屋顶看月亮"
python3 libtv.py node image_caption --ref IMG_URL
python3 libtv.py node text_to_music "悲伤、钢琴、60秒"

# 图片节点
python3 libtv.py node image_to_image "改赛博朋克风" --ref IMG_URL
python3 libtv.py node image_upscale --ref IMG_URL

# 视频节点
python3 libtv.py node first_last_frame "拔剑过程" --ref start.png --ref2 end.png
python3 libtv.py node reference_video "保留主体演绎新场景" --ref ref.png

14. 修饰器 — libtv.py edit#

bash

python3 libtv.py edit style "宫崎骏吉卜力" --target URL --session-id SID
python3 libtv.py edit camera "无人机环绕" --target "场景" --session-id SID
python3 libtv.py edit character_lib "孙悟空" --target "花果山" --session-id SID
python3 libtv.py edit mark "纸船换爱心" --target URL --session-id SID
python3 libtv.py edit focus "右上角月亮" --target URL --session-id SID

15. 模型路由 — libtv.py model#

bash

python3 libtv.py model list
python3 libtv.py model list --kind video
python3 libtv.py model with seedance-2.0-vip "..." --ratio 16:9 --duration 5s
python3 libtv.py model with lib-nano-pro "..." --ratio 1:1 --resolution 2K

16. dry-run（v0.4.0+）#

所有生成类子命令（flow/node/edit/model）支持 --dry-run：输出将发送的 prompt 但 不调 API、不烧积分。

bash

python3 libtv.py flow story_script "..." --dry-run
python3 libtv.py model with seedance-2.0-vip "..." --duration 5s --dry-run

用户侧 Agent 的核心原则#

你（用户侧 Agent）是 搬运工，不是创作者。后端 LibTV Agent 有专业的模型选择 / prompt 工程 / 工作流编排能力。

• 能传话就别替用户写 prompt：用户说"帮我推演分镜"，就调 session "帮我推演分镜"，不要自己先编个分镜表
• 能用 flow/ model 显式入口就别让后端猜：用户说"用 Seedance 做 5 秒视频"时，直接 model with seedance-2.0-vip --duration 5s
• 永远先 --dry-run 检查 prompt：调真 API 前一次 dry-run 能省很多冤枉积分
• 下载到本地后向用户展示：results URL + projectUrl 两个都给

输出格式（v0.4.0+ 全 JSON）#

所有 stdout 输出都是 JSON，便于 Agent 程序化解析：

json

// session / flow / node / edit / model 等生成类
{"projectUuid":"...", "sessionId":"...", "projectUrl":"...", "message_sent":"..."}

// dry-run
{"dry_run":true, "preset":"...", "would_send":"...", ...}

// list 类（model list / project list / history list 等仍输出表格，便于人类查看）

错误以 JSON 写 stderr（见上面"错误响应"）。

注意事项#

• 鉴权方式： Authorization: Bearer <LIBTV_ACCESS_KEY>
• 项目画布地址： https://www.liblib.tv/canvas?projectId=<projectUuid>
• 上传 OSS 地址格式： https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}{ext}
• 文件大小限制：200MB
• 生成中只给用户"正在生成"提示；完成后同时给 结果 URL + projectUrl
• 本地状态： ~/.libtv_projects.json（项目）+ ~/.libtv_session_history.json（会话历史）