{
  "messages": [
    {"id": "msg-xxx", "role": "user", "content": "生一个动漫视频"},
    {"id": "msg-yyy", "role": "assistant", "content": "..."}
  ],
  "projectUrl": "https://www.liblib.tv/canvas?projectId=..."
}

agent-im 会话（生图 / 生视频）

通过 agent-im 的 OpenAPI 创建会话、发送消息（生图、生视频、编辑视频等）、上传图片/视频文件，并查询会话消息进展。

LibTV 是 LiblibAI 推出的 AI 视频创作平台，同时为人类创作者和 Agent 设计。Agent 通过 Skill 入口理解任务、调用模型并自动编排工作流。

平台核心能力：

• - 生成：文生图、文生视频、图生视频、视频续写
• 编辑：局部修改、元素替换、镜头调整、风格迁移
• 复杂创作：一句话生成完整短剧（剧本→分镜→成片）、复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
• 模型：Seedance 2.0、Kling 3.0/O3、Wan 2.6、NanoBanana、Midjourney、Seedream 5.0 等顶级模型

用户的所有创作和编辑需求都通过发送自然语言消息来完成，Agent 会自主编排工作流。复杂任务（短剧、MV）耗时较长，需耐心轮询。

功能

1. 1. 创建会话 / 发消息 - 创建新会话或向已有会话发送一条消息（如「生一个动漫视频」「把纸船换成爱心」）
2. 查询会话进展 - 根据 sessionId 拉取该会话的消息列表，用于轮询生图/生视频结果
3. 切换项目 - 将当前 accessKey 绑定的项目切换到新项目，后续 create_session 将使用新 projectUuid
4. 上传文件 - 上传图片或视频文件到 OSS，返回可访问的 OSS 地址（编辑已有视频/图片时需要先上传）
5. 下载结果 - 将会话中生成的图片/视频批量下载到本地，自动提取 URL 并命名

前置要求

bash
export LIBTVACCESSKEY=your-access-key

可选：OPENAPIIMBASE 或 IMBASEURL，默认 https://im.liblib.tv。

无需安装额外依赖，仅使用 Python 标准库。

使用方法

1. 创建会话 / 发送消息

bash

创建新会话并发送「生一个动漫视频」

python3 {baseDir}/scripts/create_session.py 生一个动漫视频

向已有会话发送消息

python3 {baseDir}/scripts/createsession.py 再生成一张风景图 --session-id SESSIONID

只创建/绑定会话，不发消息

python3 {baseDir}/scripts/create_session.py

2. 查询会话进展

bash

查询会话消息列表

python3 {baseDir}/scripts/querysession.py SESSIONID

增量拉取（只返回 seq 大于 N 的消息）

python3 {baseDir}/scripts/querysession.py SESSIONID --after-seq 5

附带项目地址（传入 create_session 返回的 projectUuid，结果中带 projectUrl）

python3 {baseDir}/scripts/querysession.py SESSIONID --project-id PROJECT_UUID

3. 切换项目

bash

切换当前 accessKey 绑定的项目（后续创建会话将使用新项目）

python3 {baseDir}/scripts/change_project.py

4. 上传文件

当用户提供了参考的文件地址时，进行上传，仅支持图片、视频，文件大小必须在200M以下。

bash

上传图片

python3 {baseDir}/scripts/upload_file.py /path/to/image.png

上传视频

python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

5. 下载结果

生成完成后，可以将会话中的所有图片/视频批量下载到本地。

bash

从会话自动提取并下载所有结果

python3 {baseDir}/scripts/downloadresults.py SESSIONID

指定输出目录

python3 {baseDir}/scripts/downloadresults.py SESSIONID --output-dir ~/Desktop/my_project

指定文件名前缀（如 storyboard01.png, storyboard02.png ...）

python3 {baseDir}/scripts/downloadresults.py SESSIONID --prefix storyboard

直接下载指定 URL 列表（不需要 session_id）

python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./output

典型工作流

理解这些工作流，才能正确组合上面的脚本完成用户需求。

场景 1：用户要求生成图片/视频（最常见）

1. 1. createsession.py 用户的描述 → 拿到 sessionId + projectUuid
2. 每隔 8 秒调用 querysession.py SESSIONID --after-seq 0 轮询
3. 检查 messages：当出现 assistant 角色的消息且包含图片/视频 URL → 任务完成
4. 自动下载：downloadresults.py SESSION_ID --output-dir ~/Downloads/项目名 --prefix 有意义的前缀
5. 向用户展示：本地文件列表 + projectUrl（画布链接）

生成完成后自动执行下载，不需要用户额外请求。下载目录和前缀根据任务语义自动命名（如分镜用 storyboard，角色设定用 character 等）。

场景 2：用户提供图片/视频要求编辑修改（如把纸船换成爱心）

1. 1. uploadfile.py /path/to/video.mp4 → 拿到 OSS URL
2. createsession.py 把四周的纸船都换成白色的纸爱心 参考视频：{oss_url}
3. 后续同场景 1 的步骤 2-5

用户给了文件路径 + 编辑指令 = 先上传文件，再把编辑指令和 OSS URL 一起发送。

场景 3：用户提供参考图/视频要求生成新内容

1. 1. uploadfile.py /path/to/ref.png → 拿到 OSS URL
2. createsession.py 根据参考图生成xxx，参考图：{oss_url}
3. 后续同场景 1 的步骤 2-5

场景 4：在已有会话中追加新需求

1. 1. createsession.py 新的描述 --session-id SESSIONID
2. 后续同场景 1 的步骤 2-5

轮询策略

• - 间隔：每 8 秒查询一次
• 增量拉取：首次用 --after-seq 0，后续用上次拿到的最大 seq 值
• 完成判断：messages 中出现 assistant 消息且 content 包含结果 URL（图片/视频地址）
• 超时：连续轮询 3 分钟仍无结果，告知用户生成时间较长，可稍后通过项目画布链接查看，不再继续轮询
• 错误重试：单次查询失败可重试 1 次，连续 3 次失败则停止并告知用户

输出格式

create_session 返回：
json
{
projectUuid: aa3ba04c5044477cb7a00a9e5bf3b4d0,
sessionId: 90f05e0c-...,
projectUrl: https://www.liblib.tv/canvas?projectId=aa3ba04c5044477cb7a00a9e5bf3b4d0
}

query_session 返回：
json
{
messages: [
{id: msg-xxx, role: user, content: 生一个动漫视频},
{id: msg-yyy, role: assistant, content: ...}
],
projectUrl: https://www.liblib.tv/canvas?projectId=...
}

（projectUrl 仅在传入 --project-id 时存在）

change_project 返回：
json
{
projectUuid: 新项目UUID,
projectUrl: https://www.liblib.tv/canvas?projectId=新项目UUID
}

upload_file 返回：
json
{
url: https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}.png
}

download_results 返回：
json
{
outputdir: /Users/xxx/Downloads/libtvresults,
downloaded: [/Users/xxx/Downloads/libtv_results/01.png, ...],
total: 9
}

最终向用户展示时（OpenClaw）

• - 视频地址：来自 querysession 返回的 messages 中 assistant 消息的 content 或结果里的视频/图片 URL，即「返回的结果」。
• 项目地址：使用 createsession 返回的 projectUrl，或自行拼接 https://www.liblib.tv/canvas?projectId= + projectUuid。查询进展时