🎬 libtv-skills
AI Agent Skills for LibLib.tv — 让你的 AI Agent 轻松调用 LibTV 的生图、生视频等 AIGC 能力。
✨ 简介
libtv-skills 是一组面向 AI Agent 的技能包（Skills），通过 LibLib.tv 的 OpenAPI 提供 AI 生图、AI 生视频 等 AIGC 能力。Agent 可以通过这些技能创建会话、发送创作指令、查询生成进展，并获取最终的图片/视频结果。
本项目遵循 OpenClaw 技能规范，可被支持该规范的 AI Agent 平台直接识别和调用。
📦 技能列表
| 技能 | 描述 | 脚本 |
|---|
| libtv-skill | Agent-IM 会话技能 — 创建会话、发送生图/生视频消息、上传文件、查询进展、批量下载结果 | create_session.py query_session.py change_project.py upload_file.py download_results.py |
📥 快速安装
通过 npx skills 一键安装技能到你的项目中：
# 交互式选择要安装的技能
npx skills add libtv-labs/libtv-skills
# 直接安装指定技能
npx skills add libtv-labs/libtv-skills --skill libtv-skill
安装完成后，设置环境变量即可使用：
export LIBTV_ACCESS_KEY="your-access-key"
🎉 就这么简单！ 技能文件会被添加到你的项目中，AI Agent 将自动识别并调用，无需手动执行任何脚本。
可选配置（一般无需修改）：
| 变量 | 必填 | 默认值 | 说明 |
|---|
LIBTV_ACCESS_KEY | ✅ | — | LibTV API 鉴权密钥 |
OPENAPI_IM_BASE | ❌ | https://im.liblib.tv | IM 服务地址 |
IM_BASE_URL | ❌ | https://im.liblib.tv | IM 服务地址（备选） |
🛠️ 手动使用 / 调试
如果你需要手动调用脚本或调试，点击展开查看详细用法
前置要求
- Python 3.6+（仅使用标准库，无需安装额外依赖）
LIBTV_ACCESS_KEY 环境变量已设置
创建会话 & 发送生成指令
# 创建新会话，发送「生一个动漫视频」
python3 skills/libtv-skill/scripts/create_session.py "生一个动漫视频"
# 向已有会话追加消息
python3 skills/libtv-skill/scripts/create_session.py "再生成一张风景图" --session-id <SESSION_ID>
# 只创建/绑定会话，不发消息
python3 skills/libtv-skill/scripts/create_session.py
输出示例：
{
"projectUuid": "aa3ba04c5044477cb7a00a9e5bf3b4d0",
"sessionId": "90f05e0c-5d08-4148-be40-e30fc7c7bedf",
"projectUrl": "https://www.liblib.tv/canvas?projectId=aa3ba04c5044477cb7a00a9e5bf3b4d0"
}
查询会话进展
# 查询会话消息列表
python3 skills/libtv-skill/scripts/query_session.py <SESSION_ID>
# 增量拉取（只返回 seq > N 的新消息，适合轮询）
python3 skills/libtv-skill/scripts/query_session.py <SESSION_ID> --after-seq 5
# 附带项目地址
python3 skills/libtv-skill/scripts/query_session.py <SESSION_ID> --project-id <PROJECT_UUID>
输出示例：
{
"messages": [
{ "id": "msg-xxx", "role": "user", "content": "生一个动漫视频" },
{ "id": "msg-yyy", "role": "assistant", "content": "..." }
],
"projectUrl": "https://www.liblib.tv/canvas?projectId=..."
}
切换项目
# 切换当前 accessKey 绑定的项目
python3 skills/libtv-skill/scripts/change_project.py
输出示例：
{
"projectUuid": "新项目UUID",
"projectUrl": "https://www.liblib.tv/canvas?projectId=新项目UUID"
}
上传文件
# 上传图片
python3 skills/libtv-skill/scripts/upload_file.py /path/to/image.png
# 上传视频
python3 skills/libtv-skill/scripts/upload_file.py /path/to/video.mp4
输出示例：
{
"url": "https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}.png"
}
下载结果
# 从会话自动提取并下载所有图片/视频
python3 skills/libtv-skill/scripts/download_results.py <SESSION_ID>
# 指定输出目录
python3 skills/libtv-skill/scripts/download_results.py <SESSION_ID> --output-dir ~/Desktop/my_project
# 指定文件名前缀（如 storyboard_01.png, storyboard_02.png ...）
python3 skills/libtv-skill/scripts/download_results.py <SESSION_ID> --prefix "storyboard"
# 直接下载指定 URL 列表（无需 session_id）
python3 skills/libtv-skill/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./output
输出示例：
{
"output_dir": "/Users/xxx/Downloads/libtv_results",
"downloaded": ["/Users/xxx/Downloads/libtv_results/01.png", "..."],
"total": 9
}
📁 项目结构
libtv-skills/
├── README.md
├── LICENSE
└── skills/
└── libtv-skill/ # Agent-IM 会话技能
├── SKILL.md # 技能描述文件（OpenClaw 规范）
└── scripts/
├── _common.py # 公共模块（鉴权、HTTP 请求、API 封装）
├── create_session.py # 创建会话 / 发送消息
├── query_session.py # 查询会话消息进展
├── change_project.py # 切换绑定项目
├── upload_file.py # 上传图片 / 视频文件到 OSS
└── download_results.py # 批量下载生成结果到本地
🔧 API 参考
鉴权
所有 API 请求通过 HTTP Header 进行 Bearer Token 鉴权：
Authorization: Bearer <LIBTV_ACCESS_KEY>
接口列表
| 方法 | 路径 | 说明 |
|---|
POST | /openapi/session | 创建会话 / 发送消息 |
GET | /openapi/session/:sessionId | 查询会话消息列表 |
POST | /openapi/session/change-project | 切换绑定项目 |
POST | /openapi/file/upload | 上传图片 / 视频文件到 OSS |
请求 & 响应
POST /openapi/session — 创建会话 / 发送消息
Request Body:
{
"sessionId": "（可选）已有会话 ID",
"message": "（可选）要发送的消息内容"
}
Response:
{
"data": {
"projectUuid": "aa3ba04c5044477cb7a00a9e5bf3b4d0",
"sessionId": "90f05e0c-5d08-4148-be40-e30fc7c7bedf"
}
}