数字人视频生成は何をしますか？

这个技能做什么

入力は3つ——台本、顔写真、音声サンプル——で、本人が出ている縦型口述動画を出力します。本人の声をクローンして台本を読み上げさせ、Seedance 2.0-miniで写真の人物が音声に合わせて口を動かし、Sunoで生成したBGMを付け、キーワードハイライトとカラオケ進行付きのリッチ字幕を焼き込み、最後にffmpegで合成します。すべてドキュメント化された公開APIのみを使用し、Pythonとffmpegが動作する任意のAIエージェントで実行可能で、特定のクライアントに依存しません。

このパイプラインの各パラメータと落とし穴はすべて実際のプロジェクトで検証済み（references/ 参照）。机上の空論ではありません。

開始前必須確認する入力

台本: プロジェクトルートに script.md として保存。1行1文、「1. 台詞」「2. 台詞」の形式。文はセグメント生成の単位で、1文が15秒を超える場合は2文に分割。
顔写真: assets/ に配置。縦型9:16が最適（例: 1152×2048）。写真の品質が最終的な動画の品質を大きく左右します: 正面、均一な照明、サングラスやマスクなし。ユーザーに適切な写真がない場合は、GPT Image 2で生成し（references/api-reference.md 参照）、ユーザーにイメージを確認してもらってから動画ステージに進みます。
音声サンプル: assets/ に15～30秒のクリーンな音声（BGMなし、リバーブなし）。Fish Audioの声クローンに使用。
2つのAPIキー: Fish Audio用とAPIMART用。環境変数で渡し、ファイルへの書き込みやコマンドエコーへの表示は禁止。スクリプトは環境変数から読み取り、キーがない場合はヒントを表示して終了。ディスクに保存されません。

コストとアカウント

構成要素	モード	コスト（元）	モデルソース	備考	招待リンク
人物画像	GPT image 2	0.1	APIMART API	写真がない場合のみ生成	https://apimart.ai/register?aff=QVui
動画	Seedance 2.0-mini	10	APIMART API	720x1280、秒単位課金	https://apimart.ai/register?aff=QVui
BGM	Suno	0.35	APIMART API	インストゥルメンタルモード、1回2曲
声クローン	s2.1-pro-free	0	Fish Audio API	無料枠、voice_id 永久再利用	https://fish.audio/?aff=X7QT3YAX3N4Q4
字幕	whisperx small	0	ローカル実行	一度だけ環境セットアップ

実測ベース: Seedance 2.0-mini 720p 約0.039ドル/秒、30秒動画で約12元。Fish Audio クローンにはアカウント残高が必要（0/0残高の場合は403エラー）だが、TTSは無料枠で無料。 Sunoは1曲0.05ドル。完成動画1本の実コストは約10～13元。

5ステージのフロー

各ステージにはゲートがあり、条件を満たさないと次のステージへ進みません。状態は output/state.json に保存され、スクリプトは中断・再開可能です。

Stage A 音声（Fish Audio）

python scripts/avatar_voice.py clone: 音声サンプルをアップロードしてプライベートクローンモデルを作成、voice_id を取得。
python scripts/avatar_voice.py tts: script.md に従って文単位でWAVを合成。
python scripts/avatar_voice.py fixwav: ストリーミングWAVのファイルヘッダを修正（Fishが返すヘッダの長さが実際より大きいため、修正しないと一部のデコーダーで音声が途切れる）。
python scripts/avatar_voice.py qc: 各文の長さ、平均音量、クリッピングをチェック。

ゲート: 全文の音量が -30dBFS 以上、クリッピングなし。推定長さは参考であり、絶対目標ではない——長さを合わせるための速度変更は明確に禁止（鉄則参照）。ユーザーが試聴して自分の声に似ているか確認してから通過。

Stage B 動画（Seedance 2.0-mini）

python scripts/avatar_video.py upload-image: 顔画像をAPIMARTにアップロードし、公開URLを取得。
python scripts/avatar_video.py host-audio: 各文のWAVを tmpfiles.org でホストし、/dl/ の実際の直リンクを取得（APIMARTには音声アップロードエンドポイントがありません。直リンクは60分で期限切れになるため、アップロード後すぐに送信）。
python scripts/avatar_video.py submit: 文単位で送信。コアパラメータ generate_audio=False（動画は無音、口の動きは外部音声で駆動——これがデジタルヒューマン路線のスイッチ）。duration は音声長さを切り上げ、1セグメントのコスト見積もりが1ドルを超えると自動停止。
python scripts/avatar_video.py poll + download: ポーリングしてダウンロード。

ゲート: フレーム抽出で人物が崩れていないか、顔が変わっていないかを確認。口の動きがあることを確認。音声を変更した場合はこのステージを再実行する必要があります——古い動画の口の動きは古い音声に合わせて駆動されているため、音声トラックを直接差し替えても同期しません。

Stage C BGM（Suno）

台本を読み込んで音楽ブリーフを作成（スタイル/ムード/BPM/エネルギーカーブ/回避事項）。フォーマットは references/prompts.md 参照。
python scripts/avatar_bgm.py generate: インストゥルメンタルモードで2曲の候補を生成。
python scripts/avatar_bgm.py mix: トリミング、フェードイン/アウト、音量をボーカルの約-16dBに抑え、サイドチェインコンプレッションでダッキングし、最終動画にミックス。
ユーザーが試聴して1曲を選択。音楽の好みは主観的なため、自動化は「合格候補を出す」ところまで。選曲は人間に任せる。

Stage D 字幕（ASSリッチスタイル、ローカル無料）

オンラインサービスに依存せず、ASS/libass を使用してプロ級の字幕エフェクトを実現。avatar_caption.py の6つの機能（すべてフレーム単位でピクセルを検証済み、机上の説明ではありません）:

機能	設定方法	説明
Cue グループ化	`script.md` の台詞に `
キーワードハイライト	`spec.keywords`	例: `AI`→シアン、`5000人`→ゴールド、日中英の単語を全体一致でハイライト
カラオケ逐次進行	`spec.karaoke.enabled`	読み上げた単語だけハイライト、読み終えた単語は戻らない
デュアルテキスト	`spec.dual_text`	「じゅっかい」と言いながら画面には「10块」と表示、口語と表記を分離
時間範囲スタイル変更	`spec.emphasis`	指定した3～6秒間、より大きなフォントサイズや別の色で強調
中英2トラック＋レイアウトアニメーション	`spec.points`	中国語メイントラック＋英語キーポイントトラック、`\fad` フェードイン、`\t` スケールポップアップ

python scripts/avatar_caption.py spec    # output/caption-spec.json テンプレートを出力
python scripts/avatar_caption.py all     # ASS を生成し、digital-human-captioned.mp4 に焼き込み

字幕テキストの優先順位: --srt で指定 > whisperx の output/digital-human.srt > voice/qc.json の長さ + script.md の原文。台詞の原文がある場合はそれを優先（--prefer-script を追加）。ASR書き起こしよりも正確で、whisperxのインストールが不要。

libass の2つの重要な約束事（両方ともハマった経験あり、references/pitfalls.md 参照）: カラオケの未読色は SecondaryColour、読んだ色は PrimaryColour で固定。\k の単位はセンチ秒で、その合計はそのCueの長さと等しくなければならない。パーセンテージで指定するとカラオケが1秒で終わってしまう。

ユーザーが剪映などで字幕を付ける場合は、このステージをスキップできますが、納品時にその旨を明確に伝える必要があります。

Stage E 合成と品質チェック

4つの動画セグメントを音声長さに合わせてトリムし、1080×1920にリサイズ、30fps、音声トラックはStage AのTTS（動画の組み込み音声は破棄）、ffmpegで合成。合成コマンドのテンプレートは references/prompts.md。品質チェック: 総長さと各セグメントの合計が一致しているか、波形と音声にオフセットがないか、クリッピングがないか、完全にデコードできるか。

鉄則（すべて実際の失敗から得られた教訓）

atempo などで音声を引き伸ばして時間を稼ぐことを禁止。引き伸ばすと話す速度が遅くなり、聞き心地が悪くなる。速度を調整する場合は、Fish TTSのネイティブ prosody.speed パラメータで再録音する（例: s3=0.85、s4=0.9）か、自然な長さをそのまま受け入れる。
APIキーはプロセスメモリにのみ保存。環境変数で渡し、スクリプトの atexit で消去。出力にキー文字列が現れた場合は、すべてプレースホルダーに置き換える。プロジェクトファイル、レポート、ログにキーを残してはならない。
同じ操作ラベルで連続2回失敗したら停止し、理由を報告する。無限リトライはしない。HTTP 401の場合は即時停止（キーの問題）。1セグメントのコスト見積もりが1ドル超で停止。
推定長さは参考であり、目標ではない。実行者のQC基準は「数を合わせる」ためのものではない。
ユーザーの聴感を自動統計より優先。長さ、音量、クリッピングをすべてクリアしていても、聴感に問題があれば問題。ユーザーが10秒目からおかしいと言ったら、その時点から遡って調査する。
人間による承認を得ていないものを完成品と呼んではならない。納品時に、どの項目をチェック済みで、どの項目をチェックしていないかを明確にリストアップする。

環境の落とし穴クイックリファレンス

Windowsでこのパイプラインを実行する場合、確認済みの4つの落とし穴があります。実行前に references/pitfalls.md を読んでください: Pythonのリクエストは trust_env=False に設定しないとプロキシに誤接続、サンドボックスと実際のファイルシステムは別のビュー、tmpfilesの直リンクは表示ページから解析、FishのストリーミングWAVヘッダは修正が必要。各落とし穴には根本原因と修正方法が記載されています。

スクリプトの使用

export APIMART_API_KEY=... FISH_API_KEY=...   # またはスクリプトのプロンプトで入力
python scripts/avatar_voice.py all     # Stage A 全フロー
python scripts/avatar_video.py all     # Stage B 全フロー
python scripts/avatar_bgm.py all       # Stage C
python scripts/avatar_caption.py all   # Stage D（キー不要）

スクリプト	ステージ	キー要否	説明
avatar_voice.py	A	Fish Audio	声クローン、文単位TTS、WAVヘッダ修正、品質チェック
avatar_video.py	B	APIMART	画像アップロード、音声ホスティング、リップシンク動画送信、ポーリングダウンロード
avatar_bgm.py	C	APIMART（generate 要、mix 不要）	Suno BGM候補生成、サイドチェインコンプレッションミックス
avatar_caption.py	D	不要	リッチスタイル字幕生成と焼き込み
avatar_compose.py	E	不要	連結、リサイズ、書き起こし、最終チェック

スクリプトはカレントディレクトリから script.md と assets/ を読み取り、output/ に出力、状態は output/state.json に保存。中断後、同じコマンドを再実行すると続行。各スクリプトは --help でサブコマンドを確認可能。

セキュリティ境界（他者に配布する際の約束）

スクリプトは4つのドキュメント化されたエンドポイントのみに接続: api.fish.audio、api.apimart.ai、tmpfiles.org、およびローカルの ffmpeg/whisperx。テレメトリ、自動更新、匿名統計は一切なし。
プロジェクトディレクトリ外のパスは一切読み書きしない。
APIキーはプロセスメモリにのみ保持され、終了時に消去。ディスクに書き込まれるすべてのテキストはキーパターンフィルターを通過。
パッケージ全体は全文監査可能: SKILL.md + references/ + scripts/。バイナリ、実行可能インストール手順なし。

数字人视频生成