Libtv Video

LibTV - Image & Video Generation (Seedance 2.0)

Generate AI images and videos through one bundled LibTV skill, powered by Seedance 2.0. Supports text-to-image, image-to-image, text-to-video, and image-to-video workflows, via both Nexu-managed Seedance execution and direct LibTV execution with a user-owned sk-libtv-... key.

Key routing:

• mgk_... keys use Nexu-managed Seedance through https://seedance.nexu.io/
• sk-libtv-... keys use direct LibTV OpenAPI through https://im.liblib.tv

Delivery architecture (currently Feishu only):

• create-session captures OPENCLAW_CHANNEL_TYPE + OPENCLAW_CHAT_ID, persists them as the session's delivery block, forks a detached wait-and-deliver background process via subprocess.Popen(..., start_new_session=True), and returns immediately with a single-line JSON submit confirmation on stdout.
• The forked waiter polls the upstream LibTV API (Seedance gateway or direct LibTV) and, on terminal success, shells out to feishu_send_video.py — the same proven helper used by medeo-video — which downloads each result URL, uploads it to Feishu's file API, and posts a native media message to the originating chat.
• The waiter's output is captured in $NEXU_HOME/libtv-waiter-<id>.log for post-hoc debugging. A delivered_at timestamp is persisted when the Feishu helper reports success, so re-invoking wait-and-deliver on a delivered session is a safe no-op.

No sessions_spawn, no subagent model-speech contract, no HTTP notification callback, no stale routing fields. Delivery is a direct HTTP call using stable per-user identifiers (open_id / chat_id) that never go stale the way the old account_id did.

Multi-channel support is a follow-up: adding Discord / Slack / WeChat means dropping a new <channel>_send_video.py helper next to feishu_send_video.py and adding one branch in _deliver_results.

Requirements

• Python 3.8+
• apiKey configured in ~/.nexu/libtv.json
• default videoRatio configured in ~/.nexu/libtv.json or implicit default 16:9
• mgk_... keys target https://seedance.nexu.io/
• sk-libtv-... keys target https://im.liblib.tv

First-Time Setup

If the user has not configured an API Key, guide them to:

1. Choose the correct key type:
   • Nexu-managed key: mgk_...
   • personal LibTV key: sk-libtv-...
2. Run: python3 scripts/libtv_video.py setup --api-key <your_key> --video-ratio 16:9
3. Run: python3 scripts/libtv_video.py check to confirm the configuration is correct

To change only the default ratio later:

python3 scripts/libtv_video.py update-ratio --video-ratio 9:16

Pre-Generation Check (must run before each generation)

1. Run python3 scripts/libtv_video.py check
2. Interpret the output:
   • "API Key not configured" → guide the user to contact the admin for a key, then run setup
   • Nexu-managed key valid with remaining uses → proceed with generation
   • direct LibTV key configured → proceed with generation
   • "Key expired / exhausted" → guide the user to contact the admin, run update-key
   • "Cannot connect to gateway" or "Cannot connect to direct LibTV API" → suggest checking network connectivity
3. Only proceed with generation after check passes

Core Principle: Relay, Don't Create

You are a messenger, not a creator. The backend agent handles model selection, prompt engineering, and workflow orchestration. Your job is three things only:

1. Upload: User provides a local file → upload to get OSS URL
2. Relay: Pass the user's original description + OSS URL verbatim to create-session
3. Collect: Poll for results → download → present to user

Never do these:

• Don't rewrite, expand, translate, or embellish the user's prompt
• Don't break tasks into multiple sessions (e.g. don't split "generate 9 storyboards" into 9 calls)
• Don't add your own prompt engineering (e.g. "ultra-realistic, cinematic lighting, 8K")
• Don't arrange shots, plan storylines, or analyze styles yourself

Video / Image Generation (async, non-blocking)

CRITICAL: always pass --channel and --chat-id

Before running create-session you must extract the originating channel and the user's stable identifier from the inbound message metadata block and pass them as CLI args. Without these the background waiter cannot deliver the finished video back to the user automatically; the user will have to ask for the result manually.

• For Feishu: the inbound user message has an untrusted metadata JSON block containing sender_id. That value is the stable open_id (always starts with ou_). Pass it as --chat-id and pass --channel feishu.

Example extraction and invocation:

Conversation info (untrusted metadata):
{
  "message_id": "om_x100...",
  "sender_id": "ou_33314772052f837a3cb2f919aa4605de",
  ...
}

becomes:

python3 scripts/libtv_video.py create-session "user's video description" \
  --channel feishu \
  --chat-id ou_33314772052f837a3cb2f919aa4605de

The stdout JSON returned by create-session includes a deliverable flag. If it is false, your --channel / --chat-id were missing and the user will have to ask you for the result later.

Text-Only Generation

python3 scripts/libtv_video.py create-session "user's video description" \
  --channel feishu --chat-id <ou_xxx from inbound metadata>

Message rules:

• Nexu-managed mgk_... mode appends the Seedance 2.0 hint unless the user already chose a model
• direct sk-libtv-... mode follows the upstream relay discipline and does not add the Seedance model hint
• both modes relay the configured video ratio, defaulting to 16:9

Image+Text Generation (image-to-video)

# 1. Upload the image first
python3 scripts/libtv_video.py upload --file /path/to/image.png
# Output: url=https://libtv-res.liblib.art/...

# 2. Create session with the image URL in the message
python3 scripts/libtv_video.py create-session "user's description reference: {oss_url}"

Continue in Existing Session

python3 scripts/libtv_video.py create-session "new description" \
  --session-id SESSION_ID \
  --channel feishu --chat-id <ou_xxx from inbound metadata>

After Submission

1. create-session returns immediately without blocking and prints a single-line JSON {"status":"submitted", "sessionId", "projectUuid", "projectUrl", "channel", "deliverable", "note"} to stdout.
2. Reply to the user immediately using the note field as a hint: "Your video task has been submitted and is now generating. I'll notify you when it finishes."
3. Do not wait — resume normal conversation.
4. Under the hood, create-session has forked a detached wait-and-deliver background process that polls the upstream API for you.
5. When the job finishes, the background waiter delivers each result URL as a native video message directly to the originating Feishu chat via feishu_send_video.py. You do not need to speak the result yourself.
6. If deliverable is false (no channel context captured), the user will need to ask for the result explicitly via query-session or recover.

When the User Asks "Is my video ready?"

1. Run python3 scripts/libtv_video.py query-session SESSION_ID
   • If you don't remember the session_id, run python3 scripts/libtv_video.py recover to see all sessions
2. Reply based on the output:
   • Result URLs found → send the video/image links directly to the user
   • No results yet → "Your video is still being generated, please wait a moment"
   • Error or timeout → relay the error message and suggest retrying

Session Recovery (after memory loss / agent restart)

If you don't remember whether a video was previously generated:

1. Run python3 scripts/libtv_video.py recover
2. It reads historical sessions from the local persistence file and queries the correct backend for latest status
3. Completed sessions → send the result URLs to the user directly
4. Still in progress → inform the user it's still generating and keep the periodic heartbeat schedule

Presenting Results

When generation completes, show both:

• Result links (video/image URLs)
• Project canvas link (projectUrl)

Do NOT show the project canvas link while generation is in progress.