Voxスタイル解説動画パイプライン
1つのトピックから、ナレーション・字幕・BGM付きの完全な解説動画を生成します。パイプラインは6つのステージで構成され、各ステージが次のステージの成果物を生成します。ナレーションはアニメーションの前に生成されます。なぜなら、VO（ボイスオーバー）の長さがすべてのタイミング決定の基準となるからです。
TOPIC → 1.スクリプト → 2.ナレーション → 3.キーフレーム → 4.アニメーション → 5.音楽 → 6.アセンブリ
(Claude) (xAI TTS) (Seedream) (Omni Flash) (MiniMax) (ffmpeg)
前提条件
ATLASCLOUD_API_KEY環境変数が設定されていること（atlascloud.ai で取得可能。サインアップ時に無料クレジットあり）ffmpegとffprobeがインストールされていること（libass による字幕焼き込みに対応）- Python 3.10 以上、
requestsライブラリがインストールされていること - 60秒の動画あたり約3～8ドルのAPIクレジット（コスト表は
references/atlas-cloud-api.mdを参照）
API呼び出しを行う前に、現在のエンドポイントパスとモデルIDを https://www.atlascloud.ai/docs で必ず確認してください。メディアモデルのAPIは急速に進化します。references/atlas-cloud-api.md のパターンは2026年7月時点で検証済みです。
プロジェクト構造
すべての動画でこのレイアウトを作成し、それを維持してください。各ステージはこの構造から読み取り、書き込みを行います。
project/
├── brief.md # トピック、角度、目標尺、ターゲットオーディエンス
├── script.json # ビートごとのナレーション、ショットの説明、キャプション
├── audio/
│ ├── vo/ # beat_01.mp3 ... beat_NN.mp3
│ ├── vo_durations.json
│ └── music.mp3
├── frames/ # keyframe_01.png ... style_anchor.png
├── clips/ # clip_01.mp4 ... (無音アニメーションクリップ)
├── subs/ # captions.ass
└── final/ # film.mp4
ステージ1 — スクリプト
これはあなた自身で書くものです。API呼び出しはありません。このステージが品質を最も左右します。優れたスクリプトと平均的なビジュアルの組み合わせの方が、その逆よりも優れた結果を生みます。
下書きの前に references/vox-style-guide.md（ライティングセクション）を読んでください。基本ルール：
- ビートとして構成する。 ビート = 1つのナレーションパラグラフ（1～3文、8～14秒の発話時間）+ 1つのビジュアル。60秒の動画は6～8ビート。3分なら16～22ビート。
- Voxの物語アーク： 冒頭のフック（驚くべき具体的な事実や質問）→ コンテクスト（「Xを理解するには、まず…に戻る必要があります」）→ 1つの明確なスレッドで説明を展開 → 複雑さやひねり → フックを再定義する解決。
- 語り口： 二人称の歓迎（「あなたはおそらく…を見たことがあるでしょう」）、歴史的な物語には現在形、抽象的な表現よりも具体的な数字、短い断定調の文。「この動画では〜について説明します」のような前置きは避ける。
- 1ビートにつき1つのアイデア。 1文で2つ目の概念が導入されたら、ビートを分割する。
script.json を書く：
{
"title": "Tang Golden Age",
"topic": "How Tang Dynasty China built the world's largest city",
"style_seed": "mixed-media paper collage, ink-wash Chinese mountains, vermillion red and aged cream palette",
"accent_color": "#C0392B",
"beats": [
{
"id": 1,
"narration": "In the seventh century, Tang China built Chang'an — the largest, richest city on Earth. The whole world came to its gates.",
"visual": "Emperor Taizong enthroned at center as paper cutout, court figures flanking, pagodas and ink-wash mountains behind, red seal stamp upper right reading 盛唐",
"caption_text": null,
"motion": "slow push-in on emperor, clouds drift left, subtle parallax between cutout layers"
}
]
}
caption_text は画面上のキネティックタイポグラフィ（重要な統計や用語）用です。ほとんどのビートでは null のままにしておきます。ナレーションの字幕はアセンブリ段階で処理されます。motion はステージ4のアニメーションプロンプトになります。
ステージ2 — ナレーション（xAI TTS v1）
ビートごとに1つの音声ファイルを生成し、その長さを測定します。これらの長さが動画全体のマスタークロックとなります。
ビートごとにAtlas Cloudの音声エンドポイントを呼び出します（モデル：xAI TTS v1 — 正確なリクエスト形式と音声選択のガイダンスは references/atlas-cloud-api.md を参照）。動画全体で1つの音声を選びます。Voxのレジスター：落ち着いた、温かみのある、少し皮肉が効いた感じ — 「映画予告編」的な声は避けます。
生成後、すべてのファイルをプローブし、audio/vo_durations.json を書き込みます：
ffprobe -v error -show_entries format=duration -of csv=p=0 audio/vo/beat_01.mp3
{"beats": [{"id": 1, "file": "audio/vo/beat_01.mp3", "duration": 9.83}], "total": 61.2}
総尺が動画の企画書の要件に合っているか確認します。ビートが長すぎる場合はナレーションを短くし、そのビートのみ再生成します。
ステージ3 — キーフレーム（Seedream 5.0 Pro）
ビートごとに1つのキーフレームを、一貫したビジュアルスタイルで生成します。一貫性が難しい課題です。スタイルアンカーパターンで解決します：
- アンカーを生成する。 ビート1（通常はタイトル/フックフレーム）には
bytedance/seedream-v5.0-pro/text-to-imageを使用します。プロンプトはreferences/vox-style-guide.md（ビジュアル文法セクション）のスタイルブロック + ビートのvisual+ 動画のstyle_seedとaccent_colorから構築します。16:9、2Kをリクエストします。 - アンカーを確認してから次に進む。 スタイルが適切になるまで再生成します。他のすべてのフレームはこれを継承します。
- 編集モデルで残りのフレームを生成する。
bytedance/seedream-v5.0-pro/editをアンカーを参照画像として使用します（最大10参照までサポート。アンカー＋必要に応じて前のフレーム）。プロンプト：「参照画像の正確なアートスタイル、パレット、ペーパーコラージュ加工、ボーダーフレーミングを維持。新しいシーン：{beat.visual}」
これにより、人間のアートディレクターがするように、動画全体でパレット、テクスチャ、フレーミングが固定されます。
すべてのプロンプトはスタイルサフィックス（スタイルガイド参照）で終わる必要があります。これによりVoxルックがエンコードされます：白いボーダー付きペーパーカットアウト、ハーフトーンドット、テープ片、大胆でフラットな幾何学アクセント、広めのマージン、単一のアクセントカラー。
caption_text が設定されているフレーム：Seedreamに太字のコンデンスドサンセリフでテキストをレンダリングするよう指示します。Seedream 5.0 Proのタイポグラフィレンダリングは強力です。1フレームあたり5語以内に抑えます。
ステージ4 — アニメーション（Gemini Omni Flash）
各キーフレームを画像から動画へとアニメーション化します。ターゲットとなるクリップ長 = そのビートのVO長 + 0.5秒の余裕（モデルの対応増分に切り上げ）。
コラージュ美学のためのモーションプロンプトは控えめに — これが最もよくある失敗モードです。Voxルックは「モーショングラフィックス」であり、「実写映像」ではありません。適切なモーション語彙：
- スロープッシュイン/プルアウト（2Dカメラ、3Dドリーではない）
- カットアウトレイヤー間のパララックスドリフト
- 雲や煙の横方向のドリフト
- 紙要素がフレーム端からスライドインして静止
- ハーフトーンドットやテクスチャの微かなきらめき
- 1つの要素だけがアニメーション（旗がはためく、水がさざ波立つ）し、他はすべて静止
すべてのプロンプトで明示的に禁止：「カメラ揺れなし、3D回転なし、顔やテキストのモーフィングなし、スタイルドリフトなし、要素はフラットなペーパーカットアウトのまま」
各生成タスクを完了までポーリングし、clips/clip_NN.mp4 にダウンロードします。生成は時々失敗したりドリフトしたりします。各クリップを確認し、テキストが歪んだりスタイルが崩れたりした場合は再生成します。約15%の再生成率を予算に組み込みます。
ステージ5 — 音楽（MiniMax Music 2.6）
動画全体で1つのインストゥルメンタルBGMを生成します。is_instrumental: true をリクエスト — ボーカルはナレーションと競合します。
プロンプトの公式：{ムード} {ジャンルに近いテクスチャー}、{テンポ}、{楽器編成}、{アーク}。歴史作品の例：「瞑想的なシネマティックアンダースコア、フェルトピアノとソフトストリングスに軽いパーカッションパルス、90bpm、まばらからフルへと徐々に盛り上がる、ドキュメンタリースタイル」。楽器編成を主題に合わせます（唐時代の作品には古筝/笛のテクスチャー、テクノロジートピックにはアナログシンセパルス）。
Music 2.6は固定長の曲を生成します。トラックが動画より短い場合はアセンブリ時にクロスフェードでループ。長い場合はフェードアウトでトリミングします。音楽のアークが動画のアークと衝突しないように — 中間のドロップが静かなビートに重なると違和感があるため、結果を動画の形状に対して試聴します。
ステージ6 — アセンブリ（ffmpeg、ローカル）
完全なレシピは references/ffmpeg-assembly.md を参照。手順：
- 各クリップをそのビートのVO長に収める（トリミングまたは最終フレームをホールド）、1920x1080 30fpsにノーマライズ。
- クリップを順番に連結。
- VOトラックをビートオーディオを0.5秒のギャップで連結して作成（ビデオタイミングに合わせる）。
subs/captions.assをスクリプトから生成 — Voxスタイルの焼き込み字幕：太字サンセリフ、白文字に太い黒アウトライン、画面下部中央、最大2行、句の境界でナレーションを分割し、各チャンクをビートのウィンドウ内にタイミング配置。- 音声ミックス： VOはフルレベル、音楽はナレーション下で -12～-15dBにダッキング（サイドチェインコンプレッションまたはシンプルなボリュームオートメーション — レシピは参照ファイル）。
- 字幕＋クレジットを焼き込み（「Made with ...」を右下に小さく表示、任意）、エンコード：H.264、CRF 18、AAC 192k、
-movflags +faststart。
最終QCパスを納品前に行う： (a) 字幕/VOの同期ずれ、(b) 音楽がナレーションを圧迫していないか、(c) クリップのモーションが目に見えてループしていないか、(d) フレーム間のスタイルドリフト。問題の発生元のステージで修正し、アセンブリでごまかさない。
オーケストレーションの注意点
- 初回はステージを厳密に順番に実行。以降は、すべての状態がプロジェクトファイルに保存されているため、任意のステージを単独で再実行可能。
- API生成は低速（動画クリップ：各1～4分）。すべてのアニメーションタスクを同時に送信し、その後ポーリング — 逐次処理しない。
- 送信したすべてのプロンプトを
prompts.logファイルに保存 — 再現性が重要で、ユーザーは単一のビートを微調整・再生成したくなる。 - コストはビート数に比例。ステージ3（最初の有料ステージ）の前にユーザーに概算コストを提示：
ビート数 × ($0.10 画像 + 約$1.20 10秒クリップあたり) + 約$0.50 音声。
参考文献
references/vox-style-guide.md— ステージ1とステージ3の前に読むこと。ビジュアル文法、ライティングボイス、プロンプトテンプレート。references/atlas-cloud-api.md— ステージ2の前に読むこと。エンドポイント、モデルID、非同期タスクパターン、ポーリングコード、コスト。references/ffmpeg-assembly.md— ステージ6の前に読むこと。収め、連結、字幕、ダッキング、エンコードのレシピ。