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:

```bash
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:

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

becomes:

```bash
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

```bash
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)

```bash
# 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-se