SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslibtv-skill

libtv-skill

Agents & models

View repository

Updated 10-15 23:59

About this skill

agent-im session (image generation / video generation)

Create sessions, send messages (image generation, video generation, video editing, etc.), upload image/video files, and query session message progress through agent-im's OpenAPI.

LibTV is an AI video creation platform launched by LiblibAI, designed for both human creators and Agents. Agents understand tasks, call models, and automatically orchestrate workflows through the Skill entry point.

Platform core capabilities:

  • Generation: text-to-image, text-to-video, image-to-video, video continuation
  • Editing: partial modification, element replacement, shot adjustment, style transfer
  • Complex creation: generate a complete short drama from one sentence (script → storyboard → final cut), replicate the style of an existing video to make a TVC/promotional film, generate an MV from music, produce a product showcase video
  • Models: top models such as Seedance 2.0, Kling 3.0/O3, Wan 2.6, NanoBanana, Midjourney, Seedream 5.0

All of the user's creation and editing needs are fulfilled by sending natural language messages, and the Agent will autonomously orchestrate the workflow. Complex tasks (short dramas, MVs) take a long time and require patient polling.

Features

  1. Create session / send message - Create a new session or send a message to an existing session (such as "generate an anime video" or "replace the paper boat with a heart")
  2. Query session progress - Pull the message list of the session based on sessionId, used to poll image/video generation results
  3. Switch project - Switch the project bound to the current accessKey to a new project, and subsequent create_session will use the new projectUuid
  4. Upload file - Upload an image or video file to OSS and return an accessible OSS address (required to first upload when editing an existing video/image)
  5. Download results - Batch download the images/videos generated in the session to the local machine, automatically extracting URLs and naming them

Prerequisites

export LIBTV_ACCESS_KEY="your-access-key"

Optional:OPENAPI_IM_BASE or IM_BASE_URL, default https://im.liblib.tv。

No additional dependencies need to be installed; only the Python standard library is used.

Usage

1. Create session / send message

# 创建新会话并发送「生一个动漫视频」
python3 {baseDir}/scripts/create_session.py "生一个动漫视频"

# 向已有会话发送消息
python3 {baseDir}/scripts/create_session.py "再生成一张风景图" --session-id SESSION_ID

# 只创建/绑定会话，不发消息
python3 {baseDir}/scripts/create_session.py

2. Query session progress

# 查询会话消息列表
python3 {baseDir}/scripts/query_session.py SESSION_ID

# 增量拉取（只返回 seq 大于 N 的消息）
python3 {baseDir}/scripts/query_session.py SESSION_ID --after-seq 5

# 附带项目地址（传入 create_session 返回的 projectUuid，结果中带 projectUrl）
python3 {baseDir}/scripts/query_session.py SESSION_ID --project-id PROJECT_UUID

3. Switch project

# 切换当前 accessKey 绑定的项目（后续创建会话将使用新项目）
python3 {baseDir}/scripts/change_project.py

4. Upload file

When the user provides a reference file address, upload it; only images and videos are supported, and the file size must be under 200M.

# 上传图片
python3 {baseDir}/scripts/upload_file.py /path/to/image.png

# 上传视频
python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

5. Download results

After generation is complete, all images/videos in the session can be batch downloaded to the local machine.

# 从会话自动提取并下载所有结果
python3 {baseDir}/scripts/download_results.py SESSION_ID

# 指定输出目录
python3 {baseDir}/scripts/download_results.py SESSION_ID --output-dir ~/Desktop/my_project

# 指定文件名前缀（如 storyboard_01.png, storyboard_02.png ...）
python3 {baseDir}/scripts/download_results.py SESSION_ID --prefix "storyboard"

# 直接下载指定 URL 列表（不需要 session_id）
python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./output

Typical workflows

Only by understanding these workflows can the above scripts be correctly combined to fulfill user needs.

Scenario 1: The user requests image/video generation (most common)

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

After generation is completeautomatically execute download, without requiring an additional user request. The download directory and prefix are automatically named according to the task semantics (for example, storyboardfor storyboards, character for character settings, etc.).

Scenario 2: The user provides an image/video and requests editing modifications (e.g., "replace the paper boat with a heart")

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

The user provided a file path + editing instruction = first upload the file, then send the editing instruction together with the OSS URL.

Scenario 3: The user provides a reference image/video and requests generating new content

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

Scenario 4: Append a new request in an existing session

1. create_session.py "新的描述" --session-id SESSION_ID
2. 后续同场景 1 的步骤 2-5

Polling strategy

  • Interval: query once every 8 seconds
  • Incremental fetch: use --after-seq 0for the first time, and use the maximum seq value obtained last time for subsequent times
  • Completion determination: an assistant message appears in messages and its content contains a result URL (image/video address)
  • Timeout: if there is still no result after 3 minutes of continuous polling, tell the user "generation is taking a long time; you can check later via the project canvas link" and stop polling
  • Error retry: a single query failure can be retried once; if there are 3 consecutive failures, stop and inform the user

Output format

create_session Returns:

{
  "projectUuid": "aa3ba04c5044477cb7a00a9e5bf3b4d0",
  "sessionId": "90f05e0c-...",
  "projectUrl": "https://www.liblib.tv/canvas?projectId=aa3ba04c5044477cb7a00a9e5bf3b4d0"
}

query_session Returns:

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

（projectUrl Only exists when --project-id is passed in)

change_project Returns:

{
  "projectUuid": "新项目UUID",
  "projectUrl": "https://www.liblib.tv/canvas?projectId=新项目UUID"
}

upload_file Returns:

{
  "url": "https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}.png"
}

download_results Returns:

{
  "output_dir": "/Users/xxx/Downloads/libtv_results",
  "downloaded": ["/Users/xxx/Downloads/libtv_results/01.png", "..."],
  "total": 9
}

When finally presenting to the user (OpenClaw)

  • Video address: from the query_session returned by messages , the content of the assistant message or the video/image URL in the result, i.e., "the returned result".
  • Project address: use the create_session returned by projectUrl, or concatenate it yourself as https://www.liblib.tv/canvas?projectId= + projectUuid. When querying progress, if --project-id PROJECT_UUID，query_session is passed in, it will directly return projectUrl, making it convenient to display together.

When the task is completed, provide both:Video/image result link + Project canvas link (projectUrl). During the process, do not provide Project canvas link (projectUrl)。

Core principle: the user side does not create, it only relays messages

Your (user-side Agent's) responsibility is to be aporter, not a creator. The backend has a dedicated Agent responsible for understanding requirements, breaking down storyboards, orchestrating workflows, selecting models, and writing prompts. You only need to do three things:

  1. Upload: the user provided a local file → upload_file.py get the OSS URL
  2. Relay: send the user's original description + OSS URL unchanged to create_session.py
  3. Pick up: poll for the result → download it locally → show it to the user

Things you must absolutely not do:

  • Do not expand, polish, or translate the prompt on behalf of the user (if the user says "help me derive the storyboard", just pass along "help me derive the storyboard"; do not first write a storyboard table yourself and then send it item by item)
  • Do not break down task steps yourself (e.g., splitting "generate 9 storyboard images" into 9 independent requests)
  • Do not orchestrate shot descriptions, plot derivation, or style analysis yourself
  • Do not add prompts you made up to the message (such as descriptive words like "hyper-realistic style, cinematic lighting, 8K resolution")

The backend Agent is far more professional than the user side when it comes to model capabilities, parameter configuration, and prompt engineering. Overstepping on the user side will only reduce generation quality, and switching to a weak model would be a disaster.

Correct example:

用户说：「帮我推演后续的故事，来个分镜大爆炸，帮我出一个16:9的九宫格的图。新建一个任务。」
用户给了参考图：/path/to/ref.png

→ upload_file.py /path/to/ref.png  →  拿到 oss_url
→ create_session.py "帮我推演后续的故事，来个分镜大爆炸，帮我出一个16:9的九宫格的图。参考图：{oss_url}"
→ 轮询 → 下载 → 展示

Error example:

❌ 用户侧自己先写了个九宫格分镜表（对峙、交锋、危机...）
❌ 然后把自己编的描述发给后端
❌ 或者拆成9次 create_session 分别发送

Notes

  • The authentication method is the request header Authorization: Bearer <LIBTV_ACCESS_KEY>
  • When creating a session, if you do not pass message, only the session is created/bound, and SendMessage will not be called
  • When querying a session, you can use --after-seq for incremental fetching, which is convenient for polling new messages (including assistant replies and image/video generation results)
  • The project canvas address is fixed as:https://www.liblib.tv/canvas?projectId= + projectUuid
  • After switching projects, the Redis cache will be updated, and the next create_session will use the new projectUuid
  • File uploads only support images (image/) and videos (video/) types; other types will be rejected, and the file size must be under 200MB
  • The OSS address format returned by the upload is https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}{ext}
  • During the generation process, only tell the user "generation in progress"; do not provide the projectUrl in advance. After the task is completed, provide both:Result link (image/video URL) + Project canvas link (projectUrl)