[Skill 名] libtv-skill

agent-im 会話（画像生成 / 動画生成）

agent-im の OpenAPI を通じて、会話の作成、メッセージの送信（画像生成、動画生成、動画編集など）、画像/動画ファイルのアップロード、および会話メッセージの進捗状況の照会を行います。

LibTV は LiblibAI が提供する AI 動画制作プラットフォームで、人間のクリエイターと Agent の両方のために設計されています。Agent は Skill エントリを通じてタスクを理解し、モデルを呼び出し、ワークフローを自動的に編成します。

プラットフォームの主要機能：

• 生成：テキストから画像、テキストから動画、画像から動画、動画の続きの生成
• 編集：部分的な修正、要素の置換、ショットの調整、スタイル転送
• 複雑な制作：一言で完全な短編ドラマを生成（脚本→絵コンテ→完成品）、既存の動画スタイルを再現して TVCM/プロモーションビデオを作成、音楽からMVを生成、製品紹介ビデオの制作
• モデル：Seedance 2.0、Kling 3.0/O3、Wan 2.6、NanoBanana、Midjourney、Seedream 5.0 などのトップモデル

ユーザーのすべての制作および編集要求は、自然言語メッセージの送信によって完了し、Agent が自律的にワークフローを編成します。複雑なタスク（短編ドラマ、MV）は時間がかかるため、忍耐強くポーリングする必要があります。

機能

1. 会話の作成 / メッセージの送信 - 新しい会話を作成するか、既存の会話にメッセージを送信します（例：「アニメ動画を生成して」「紙の船をハートに変えて」）
2. 会話の進捗状況の照会 - sessionId に基づいてその会話のメッセージリストを取得し、画像生成/動画生成の結果をポーリングするために使用します
3. プロジェクトの切り替え - 現在の accessKey にバインドされているプロジェクトを新しいプロジェクトに切り替えます。以降の create_session は新しい projectUuid を使用します
4. ファイルのアップロード - 画像または動画ファイルを OSS にアップロードし、アクセス可能な OSS アドレスを返します（既存の動画/画像を編集する際に事前にアップロードする必要があります）
5. 結果のダウンロード - 会話中に生成された画像/動画を一括でローカルにダウンロードし、URL を自動的に抽出し、名前を付けます

前提条件

export LIBTV_ACCESS_KEY="your-access-key"

オプション：OPENAPI_IM_BASE または IM_BASE_URL、デフォルトは https://im.liblib.tv です。

追加の依存関係は不要で、Python 標準ライブラリのみを使用します。

使用方法

1. 会話の作成 / メッセージの送信

# 新しい会話を作成し、「アニメ動画を生成して」を送信
python3 {baseDir}/scripts/create_session.py "アニメ動画を生成して"

# 既存の会話にメッセージを送信
python3 {baseDir}/scripts/create_session.py "もう一枚風景画を生成して" --session-id SESSION_ID

# 会話の作成/バインドのみで、メッセージは送信しない
python3 {baseDir}/scripts/create_session.py

2. 会話の進捗状況の照会

# 会話メッセージリストの照会
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. プロジェクトの切り替え

# 現在の accessKey にバインドされているプロジェクトを切り替える（以降の会話作成は新しいプロジェクトを使用する）
python3 {baseDir}/scripts/change_project.py

4. ファイルのアップロード

ユーザーが参照ファイルアドレスを提供した場合、アップロードを実行します。画像、動画のみをサポートし、ファイルサイズは 200MB 未満である必要があります。

# 画像のアップロード
python3 {baseDir}/scripts/upload_file.py /path/to/image.png

# 動画のアップロード
python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

5. 結果のダウンロード

生成が完了した後、会話内のすべての画像/動画を一括でローカルにダウンロードできます。

# 会話からすべての結果を自動的に抽出しダウンロード
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

典型的なワークフロー

これらのワークフローを理解することで、上記のスクリプトを正しく組み合わせてユーザーの要求を完了できます。

シナリオ 1：ユーザーが画像/動画の生成を要求（最も一般的）

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（キャンバスリンク）

生成完了後、自動的にダウンロードを実行し、ユーザーからの追加要求は不要です。ダウンロードディレクトリとプレフィックスは、タスクの意味に基づいて自動的に命名されます（例：絵コンテは storyboard、キャラクター設定は character など）。

シナリオ 2：ユーザーが画像/動画を提供し、編集/修正を要求（例：「紙の船をハートに変えて」）

1. upload_file.py /path/to/video.mp4  →  OSS URL を取得
2. create_session.py "周りの紙の船をすべて白い紙のハートに変えて 参考動画：{oss_url}"
3. 以降はシナリオ 1 のステップ 2-5 と同じ

ユーザーがファイルパス + 編集指示を与えた場合 = まずファイルをアップロードし、次に編集指示と OSS URL を一緒に送信します。

シナリオ 3：ユーザーが参照画像/動画を提供し、新しいコンテンツの生成を要求

1. upload_file.py /path/to/ref.png  →  OSS URL を取得
2. create_session.py "参照画像に基づいてxxxを生成して、参照画像：{oss_url}"
3. 以降はシナリオ 1 のステップ 2-5 と同じ

シナリオ 4：既存の会話に新しい要求を追加

1. create_session.py "新しい記述" --session-id SESSION_ID
2. 以降はシナリオ 1 のステップ 2-5 と同じ

ポーリング戦略

• 間隔：8秒ごとに1回照会
• 増分取得：初回は --after-seq 0 を使用し、以降は前回取得した最大 seq 値を使用
• 完了判断：messages に assistant メッセージが出現し、content に結果の URL（画像/動画アドレス）が含まれている場合
• タイムアウト：3分間連続してポーリングしても結果がない場合、ユーザーに「生成に時間がかかっています。後でプロジェクトキャンバスリンクから確認できます」と伝え、ポーリングを続行しない
• エラーリトライ：単一の照会が失敗した場合、1回リトライ可能。3回連続で失敗した場合は停止し、ユーザーに通知

出力形式

create_session の戻り値：

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

query_session の戻り値：

{
  "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 の戻り値：

{
  "projectUuid": "新プロジェクトUUID",
  "projectUrl": "https://www.liblib.tv/canvas?projectId=新プロジェクトUUID"
}

upload_file の戻り値：

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

download_results の戻り値：

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

最終的にユーザーに表示する際（OpenClaw）

• 動画アドレス：query_session が返す messages 内の assistant メッセージの content または結果内の動画/画像 URL、つまり「返された結果」から取得します。
• プロジェクトアドレス：create_session が返す projectUrl を使用するか、https://www.liblib.tv/canvas?projectId= + projectUuid を自分で連結します。進捗状況を照会する際に --project-id PROJECT_UUID を渡すと、query_session が直接 projectUrl を返すため、一緒に表示するのに便利です。

タスク完了時には、動画/画像の結果リンク + プロジェクトキャンバスリンク（projectUrl） を同時に提供します。 プロセス中は、プロジェクトキャンバスリンク（projectUrl） を提供しないでください。

核心原則：ユーザー側は創作せず、伝達のみを行う

あなた（ユーザー側 Agent）の役割は運び屋であり、創作者ではありません。バックエンドには、要求の理解、絵コンテの分解、ワークフローの編成、モデルの選択、プロンプトの作成を担当する専門の Agent がいます。あなたがすべきことは3つだけです。

1. アップロード：ユーザーがローカルファイルを提供 → upload_file.py で OSS URL を取得
2. 伝達：ユーザーの元の記述 + OSS URL をそのまま create_session.py に送信
3. 受け取り：結果をポーリング → ローカルにダウンロード → ユーザーに表示

絶対にやってはいけないこと：

• ユーザーのプロンプトを拡張、洗練、翻訳しない（ユーザーが「絵コンテの推敲を手伝って」と言ったら、そのまま「絵コンテの推敲を手伝って」と伝え、自分で絵コンテ表を書いてから個別に送信しない）
• タスクのステップを自分で分解しない（例：「9枚の絵コンテ画像を生成して」を9回の独立したリクエストに分解しない）
• ショットの記述、ストーリーの推敲、スタイルの分析を自分で編成しない
• メッセージに自分で作成したプロンプトを追加しない（例：「超リアルなスタイル、映画のようなライティング、8K解像度」のような記述詞）

バックエンドの Agent は、モデルの能力、パラメータ設定、プロンプトエンジニアリングにおいて、ユーザー側よりもはるかに専門的です。ユーザー側が越権行為をすると、生成品質が低下するだけでなく、弱いモデルに切り替えることはさらに悲惨です。

正しい例：

ユーザーが言いました：「今後のストーリーを推敲して、絵コンテを爆発的に出して、16:9の9コマの画像を生成して。新しいタスクを作成して。」
ユーザーが参照画像を提供しました：/path/to/ref.png

→ upload_file.py /path/to/ref.png  →  oss_url を取得
→ create_session.py "今後のストーリーを推敲して、絵コンテを爆発的に出して、16:9の9コマの画像を生成して。参照画像：{oss_url}"
→ ポーリング → ダウンロード → 表示

誤った例：

❌ ユーザー側が自分で9コマの絵コンテ表（対峙、交戦、危機...）を先に作成
❌ そして自分で作成した記述をバックエンドに送信
❌ または9回の create_session に分解して個別に送信

注意事項

• 認証方法はリクエストヘッダー Authorization: Bearer <LIBTV_ACCESS_KEY> です
• 会話作成時に message を渡さない場合、会話の作成/バインドのみを行い、SendMessage は呼び出されません
• 会話照会時に --after-seq を使用して増分取得を行うと、新しいメッセージ（assistant の返信や画像/動画生成結果を含む）のポーリングに便利です
• プロジェクトキャンバスアドレスは https://www.liblib.tv/canvas?projectId= + projectUuid で固定です
• プロジェクト切り替え後、Redis キャッシュが更新され、次回の create_session は新しい projectUuid を使用します
• ファイルのアップロードは画像（image/*）と動画（video/*）タイプのみをサポートし、その他のタイプは拒否されます。ファイルサイズは 200MB 未満である必要があります
• アップロードが返す OSS アドレスの形式は `