chanjing-video-compose

蝉镜视频合成

機能説明

蝉镜の動画合成 Open API を呼び出します。公開／カスタムアバターの一覧表示、素材のアップロード、テキストまたは音声によるデジタルヒューマンの駆動、タスクのポーリングを行います。ユーザーが明示的に要求した場合は、スクリプトで完成動画をダウンロードします。このスキルのスクリプトは、ffmpeg/ffprobe に依存しません（ワンクリック動画作成のオーケストレーションとは異なります）。認証情報と権限の境界については、同じディレクトリにある manifest.yaml を参照してください。

実行要件

• python3 と同じリポジトリ内の scripts/*.py
• ffmpeg/ffprobe のゲートはありません

環境変数と機械可読な宣言

• 環境変数のキー名と説明：manifest.yaml（environment セクション）および本文
• 変数、認証情報モデル、コンプライアンスに関する permissions、clientPermissions、agentPolicy：manifest.yaml

使用コマンド

• ClawHub（slug はレジストリに準拠）：clawhub run chanjing-video-compose
• このリポジトリ：python skills/chanjing-video-compose/scripts/create_task.py …（Standard Workflow を参照）

---

登録とレビュー（唯一の信頼できる情報源）

認証情報、primaryEnv の省略、任意の env、ffmpeg のゲートなし（このスキルを単独で使用する場合）などについては、manifest.yaml を参照してください。この記事では、When to Use 以降に手順と API の説明を記載します。

このスキルを使う場面

ユーザーが次の操作を求めている場合に、このスキルを使用します。

• デジタルヒューマンの動画合成タスクを作成する
• テキストでデジタルヒューマンを登場させる
• ローカル音声でデジタルヒューマン動画を駆動する
• 公開またはカスタムのデジタルヒューマンアバターを検索する
• 動画合成の結果をポーリングする
• ユーザーが明示的に求めた場合に、最終動画をローカルにダウンロードする

「実写動画をアップロードしてリップシンクさせる」という要件に近い場合は、chanjing-avatar を優先して使用し、混在させないでください。

前提条件

このスキルを実行する前に、まず chanjing-credentials-guard を使って AK/SK と Token の検証を完了する必要があります。

このスキルは guard と以下を共有します。

• ~/.chanjing/credentials.json
• https://open-api.chanjing.cc

認証情報がない場合、スクリプトは蝉镜のログインページを自動で開き、設定コマンドを案内します。

レビューとセキュリティ（認証情報と境界）

Purpose / Credentials / Persistence に関する個別の説明は manifest.yaml を参照してください。以下は SKILL 本文での補足です。

• create_task.py --callback：URL を指定すると、蝉镜がそのエンドポイントにタスク結果をプッシュする場合があります。信頼性と到達可能性を自分で評価してください。

標準ワークフロー

1. まずユーザーにデジタルヒューマンのソースを明確に選んでもらいます。common（公開デジタルヒューマン）または customised（カスタムデジタルヒューマン）から選択します。
2. list_figures.py --source <common|customised> を呼び出します（--json を推奨。公開ソースでは --page-size を大きくするか、ページ送りを利用できます）。利用可能なアバターを取得し、候補の中で name、各 figure の type と解像度、audio_man_id、audio_name（ある場合）をタスクの人物設定と照らし合わせて比較してから、person.id を選びます。比較せずに一覧の先頭から数件をデフォルトで選ぶことは禁止です。
3. 公開デジタルヒューマンを選択した場合は、さらに figure_type（選択した figures[].type と一致）を確認します。例：sit_body / whole_body / circle_view。ユーザーに特別な要望がない場合は、若々しく活気のあるアバターを優先します（名称／audio_name が若者、学生、元気さなどを示すもの）。題材に成熟した雰囲気や中高年の雰囲気が必要な場合は、その条件に合わせて選び直します。
4. テキスト駆動を使う場合は、audio_man_id を決定します。
5. タスクの作成前に、字幕の設定を必ずユーザーに確認します。show（字幕を表示）または hide（字幕を非表示）から選択してもらいます。
6. ユーザーが show を選び、カスタムのスタイルや位置を指定していない場合は、公式ドキュメントで推奨されているデフォルト値をそのまま使います。字幕の位置やスタイルを調整したいとユーザーが明示した場合にのみ、subtitle_config のパラメーターを追加で確認します。
7. ユーザーが字幕の位置をカスタマイズする場合は、座標の原点が左上であることを説明し、subtitle_config 関連のパラメーターを補足します。
8. ローカル音声または背景画像を使う場合は、先に upload_file.py を呼び出して file_id を取得します。
9. create_task.py を呼び出して動画合成タスクを作成し、video_id を取得します。
10. poll_task.py を呼び出し、成功するまでポーリングして video_url を取得します。
11. ユーザーがローカルへの保存を明示的に求めた場合にのみ、download_result.py を呼び出します。

対応 API

このスキルが現在対応している API：

• GET /open/v1/list_common_dp
• POST /open/v1/list_customised_person
• POST /open/v1/create_video
• GET /open/v1/video
• GET /open/v1/common/create_upload_url
• GET /open/v1/common/file_detail

スクリプト

スクリプトのディレクトリ：

• skills/chanjing-video-compose/scripts/

スクリプト	説明
_auth.py	認証情報を読み込み、access_token を取得または更新します
list_figures.py	`--source common
upload_file.py	音声または背景素材をアップロードし、ファイルが利用可能になるまでポーリングした後、file_id を出力します
create_task.py	動画合成タスクを作成します。公開デジタルヒューマンを使用する場合は --figure-type ... を追加できます。字幕は `--subtitle show
poll_task.py	動画の詳細を完了するまでポーリングし、デフォルトで video_url を出力します
download_result.py	最終動画を outputs/video-compose/ にダウンロードします

使用例

例 1：公開デジタルヒューマンをテキストで駆動

# 1. 先列公共数字人
python skills/chanjing-video-compose/scripts/list_figures.py --source common

# 2. 用公共数字人创建文本驱动视频
VIDEO_ID=$(python skills/chanjing-video-compose/scripts/create_task.py \
  --person-id "C-ef91f3a6db3144ffb5d6c581ff13c7ec" \
  --figure-type "sit_body" \
  --audio-man "C-0ae461135d8a4eb2b59c853162ea9848" \
  --subtitle "show" \
  --subtitle-x 31 \
  --subtitle-y 1521 \
  --subtitle-width 1000 \
  --subtitle-height 200 \
  --subtitle-font-size 64 \
  --subtitle-stroke-width 7 \
  --text "你好，这是一个蝉镜视频合成测试。")

# 3. 轮询到完成，拿到 video_url
python skills/chanjing-video-compose/scripts/poll_task.py --id "$VIDEO_ID"

例 2：カスタムデジタルヒューマンをローカル音声のアップロードで駆動

python skills/chanjing-video-compose/scripts/list_figures.py --source customised

AUDIO_FILE_ID=$(python skills/chanjing-video-compose/scripts/upload_file.py \
  --service make_video_audio \
  --file ./input.wav)

VIDEO_ID=$(python skills/chanjing-video-compose/scripts/create_task.py \
  --person-id "C-ef91f3a6db3144ffb5d6c581ff13c7ec" \
  --subtitle "hide" \
  --audio-file-id "$AUDIO_FILE_ID")

python skills/chanjing-video-compose/scripts/poll_task.py --id "$VIDEO_ID"

例 3：最終動画を明示的にダウンロード

python skills/chanjing-video-compose/scripts/download_result.py \
  --url "https://example.com/output.mp4"

ダウンロードのルール

ダウンロードは明示的な操作であり、デフォルトでは実行しません。

• poll_task.py の成功後、まず video_url を返します
• 結果ファイルを自動でダウンロードしないでください
• ユーザーが「ローカルにダウンロード」「outputs に保存」「ファイルに保存」と明示した場合にのみ、download_result.py を実行します

アバター選択ルール

デジタルヒューマンを選択する際は、次のルールに従います。

• プラットフォームに登録済みの人物ライブラリを使う場合は、まず公開デジタルヒューマンを使用します：list_figures.py --source common
• ユーザー自身がトレーニングまたはアップロードして作成した人物を使う場合は、まずカスタムデジタルヒューマンを使用します：list_figures.py --source customised
• 公開デジタルヒューマンで動画を作成する場合は、選択した形態に応じて --figure-type <type> を指定できます
• カスタムデジタルヒューマンを使用する場合、figure_type は不要です

Subtitle Rule

字幕遵循这条规则：

• 不要默认假设用户要字幕或不要字幕
• 创建任务前，必须先明确询问用户选择：show 或 hide
• 若由 chanjing-one-click-video-creation 的 run_render.py 调用 create_task.py，以当次 workflow.json 根级 subtitle_required 为准（默认 false → --subtitle hide；true → show 及推荐样式），无需为该一键成片路径再单独追问字幕开关，除非用户在需求里明确要求改字幕策略
• 用户选择保留字幕时，调用 create_task.py --subtitle show
• 若用户未指定字幕位置或样式，直接使用官方推荐默认值；create_task.py 在未传 --subtitle-color 时默认白字 color=#FFFFFF：1080p 为 x=31 y=1521 width=1000 height=200 font_size=64 stroke_width=7 asr_type=0；4K 画布为 x=80 y=2840 width=2000 height=1000 font_size=150 stroke_width=7 asr_type=0（两组均含 color=#FFFFFF）
• 用户选择隐藏字幕时，调用 create_task.py --subtitle hide 或兼容旧用法 --hide-subtitle
• 若用户要求调整字幕位置或样式，可继续传 --subtitle-x / --subtitle-y / --subtitle-width / --subtitle-height / --subtitle-font-size / --subtitle-color / --subtitle-stroke-color / --subtitle-stroke-width / --subtitle-font-id / --subtitle-asr-type
• 坐标基于左上角原点；字幕区域不能超出 screen_width / screen_height
• 如果用户只说“要字幕”但没指定位置，不必再追问具体数值；除非用户明确要调位置，否则直接走默认值

Output Convention

默认本地输出目录：

• outputs/video-compose/

Additional Resources

更多接口细节见：

• skills/chanjing-video-compose/reference.md
• skills/chanjing-video-compose/examples.md