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:

bashCopy code
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:

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

becomes:

bashCopy code
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

bashCopy code
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)

bashCopy code
# 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

bashCopy code
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.

URL Rules

The valid result URL prefixes are:

• https://libtv-res.liblib.art/sd-gen-save-img/
• https://libtv-res.liblib.art/claw/

Any other domain (for example medeo-res.liblib.art) is not a final result URL and must be ignored.

Always present the URL exactly as extracted by the script. Do not:

• Rewrite or transform URLs
• Use proxy/cache domain URLs as results
• Fabricate URLs by guessing paths

The extract_result_urls() function in the script extracts only valid libtv-res.liblib.art result URLs. Trust its output.

Multi-Session Discipline (CRITICAL)

When running multiple video generations concurrently, you MUST follow these rules strictly:

1. Track Every Session Separately

Maintain a clear mapping for each generation request:

• User request (what the user asked for, e.g. "scene 1: palace", "scene 2: garden")
• Session ID (returned by create-session)
• Project UUID (returned by create-session)

2. Never Mix Sessions

Before presenting results, always verify:

• The result URLs came from the correct session ID for that specific request
• Do NOT copy-paste URLs from one session's output into another session's reply

3. Label Results Clearly

When presenting results from multiple concurrent sessions, always label which result belongs to which request:

Copy code
Scene 1 (palace): [video URL from session A]
Scene 2 (garden): [video URL from session B]

4. Handle Partial Completion

If some sessions complete before others:

• Present completed results immediately, clearly labeled
• Note which sessions are still in progress
• Do NOT hold all results until every session finishes

Error Handling

When any command returns an error:

1. Read the message after "❌" in the output and relay it to the user as-is
2. Do not fabricate or translate error messages
3. Provide action suggestions based on the error type:

Mandatory Guard Checklist

This skill has a hard anti-hallucination rule. The model must verify each step before it can describe that step as successful.

Submit step checks:

• confirm ~/.nexu/libtv.json exists and contains a non-empty apiKey
• confirm the key starts with either mgk_ or sk-libtv-
• confirm mgk_... keys target https://seedance.nexu.io/ unless a deliberate local test override is set
• confirm sk-libtv-... keys target https://im.liblib.tv unless a deliberate local test override is set
• never route a personal sk-libtv-... key through the Nexu Seedance gateway
• confirm the effective video ratio is set, defaulting to 16:9
• confirm create-session returns a real sessionId
• confirm create-session returns a real projectUuid
• confirm the accepted session was persisted locally with matching session_id, project_uuid, status=submitted
• after submit, use the note field from create-session stdout to acknowledge the submission to the user

Background delivery checks (handled by the detached waiter, not by the model):

• confirm success only when at least one result URL is extracted from the valid LibTV result domain
• the waiter persists delivered_at after feishu_send_video.py returns success; re-running wait-and-deliver on a delivered session is a safe no-op
• if feishu_send_video.py fails, the error is logged to $NEXU_HOME/libtv-waiter-<session-id>.log; the result URLs remain persisted locally so the user can ask query-session to retrieve them
• if terminal polling times out, the session's status is set to timeout; the user will have to ask later via query-session or recover

Output rule:

• If any guard check fails, stop and return the explicit guard-check error
• Never claim a video is ready until the terminal success checks have passed
• Never invent session ids, project ids, URLs, or completion state

Command Reference

Script path for all commands: scripts/libtv_video.py