video-generation

動画生成

mode="video" を指定して generate_media を使用すると、動画を生成できます。利用可能な API キーに基づいて、システムが最適なバックエンドを自動選択します。

クイックスタート

# Simple text-to-video (auto-selects backend)
generate_media(prompt="A robot walking through a city", mode="video")

# Specify backend and duration
generate_media(prompt="Ocean waves crashing on rocks", mode="video",
               backend_type="google", duration=8)

# With aspect ratio
generate_media(prompt="A timelapse of clouds", mode="video",
               backend_type="grok", aspect_ratio="16:9", duration=10)

バックエンドの比較

バックエンド	デフォルトモデル	長さの範囲	デフォルトの長さ	解像度	API キー
Grok（優先順位 1）	grok-imagine-video	1～15 秒	5 秒	480p、720p	XAI_API_KEY
Google Veo（優先順位 2）	veo-3.1-generate-preview	4～8 秒	8 秒	720p、1080p、4K（size を使用）；デフォルトは 16:9	GOOGLE_API_KEY
OpenAI Sora（優先順位 3）	sora-2	4、8、または 12 秒（離散値）	4 秒	標準	OPENAI_API_KEY

主なパラメーター

パラメーター	説明	例
prompt	動画のテキストによる説明	"A drone flying over mountains"
backend_type	特定のバックエンドを指定します	"grok"、"google"、"openai"
model	デフォルトモデルを上書きします	"veo-3.1-generate-preview"
duration	動画の長さ（秒）	8（バックエンドの制限内に調整されます）
aspect_ratio	動画のアスペクト比	"16:9"、"9:16"、"1:1"
size	解像度（Grok：480p/720p；Veo：720p/1080p/4k）	"720p"、"1080p"、"4k"
input_images	画像から動画を生成するためのソース画像	["starting_frame.jpg"]
video_reference_images	スタイル／コンテンツのガイド画像（Veo、最大 3 枚）	["ref1.png", "ref2.png"]
negative_prompt	除外する内容（Veo）	"blurry, low quality"

動画の長さの処理

バックエンドごとに動画の長さの制約が異なります。generate_media は、指定された長さを自動的に制限内に調整します。

• Grok：連続範囲は 1～15 秒（範囲内に調整）
• Google Veo：連続範囲は 4～8 秒（範囲内に調整）、デフォルトのアスペクト比は 16:9
• OpenAI Sora：離散値のみ（4、8、または 12 秒）—最も近い有効な値に調整

動画の長さが調整されると、警告がログに記録されます。

画像から動画を生成

3 つすべての動画バックエンドが input_images を使って既存の画像から動画を開始できます。

generate_media(
    prompt="Animate this scene with gentle movement",
    mode="video",
    input_images=["scene.jpg"],
    duration=5
)

input_images の最初の画像が使用されます。追加の画像は無視されます。

生成時間

動画の生成は画像より大幅に時間がかかります。すべてのバックエンドでポーリングが使用されます。

• Grok：SDK がポーリングを内部で処理します（タイムアウトは最大 10 分）
• Google Veo：20 秒ごとにカスタムポーリングを実行します（最大 10 分）
• OpenAI Sora：2 秒ごとにカスタムポーリングを実行します

Veo 3.1：ネイティブ音声

Veo 3.1 は、プロンプトの内容から音声（セリフ、効果音、環境音）を自動生成します。追加のパラメーターは不要です。音を説明するだけです。

• セリフ：プロンプト内で引用符を使用します（"Hello," she said.）
• 効果音：音を説明します（tires screeching, engine roaring）
• 環境音：雰囲気を説明します（eerie hum resonates through the hallway）

Veo 3.1：動画延長の制約

veo_vid_* ID を指定して continue_from で動画を延長する場合：

• 解像度は 720p に固定されます（延長に関する API 要件）
• 対応するアスペクト比は 16:9 と 9:16 のみです
• 1 回の延長で最大 7 秒追加されます（API の上限：20 回の延長、合計約 141 秒）
• 生成された動画は、有効期限が切れるまで 2 日間保持されます

長い動画の制作

現在の API では、1 クリップあたり最大 15 秒（Grok）に制限されており、ほとんどのバックエンドでは 4〜8 秒です。30 秒を超える連続動画を 1 回の呼び出しで生成する方法はありません。実証済みのアプローチは次のとおりです。

1. ショットリストを計画する — 動画を 6〜8 秒のセグメントに分割し、各ショットで使う具体的なカメラ表現を指定します
2. クリップを並列生成する — background=True を使って、すべてのセグメントを同時に開始します
3. Remotion で合成する（以下を参照）— 生成した映像の上にプログラムによるアニメーションを重ねます
4. 音声でつなぐ — ナレーションまたは音楽を 1 本にまとめたトラックで、クリップ間の映像の切り替わりを滑らかにします

映像の一貫性を保つため、すべてのプロンプトで同じスタイルアンカー（例：「BBC Earth のドキュメンタリー映像」）を使い、照明や色の描写にも一貫性を持たせてください。

例、トランジションの種類、尺の戦略を含む制作ガイド全文：references/production.md を参照してください。

ハイブリッドワークフロー：AI 映像＋Remotion アニメーション

最良の結果は、どちらか一方を選ぶのではなく、AI 生成映像と Remotion のプログラムによるアニメーションを組み合わせることで得られます。

AI 動画生成では、プログラムによるレンダリングだけでは実現できない、フォトリアルで映画のような映像を生成できます。Remotion では、AI 生成では確実に制御できない、精密なタイポグラフィ、モーショングラフィックス、オーバーレイ、トランジションを作成できます。両方を組み合わせて使いましょう。

ルール：先に生成し、後で合成する

1. 映画的またはフォトリアルなショット（環境、製品のデモ、雰囲気のある映像）には、AI クリップを生成する
2. Remotion でそれらのクリップを映像の基盤として使う — <Video> または <OffthreadVideo> の背景レイヤーとして読み込みます
3. プログラムで作成した要素を上に合成する — タイポグラフィ、モーショングラフィックス、ロゴ、データオーバーレイ、トランジション、字幕を重ねます
4. 不足部分を Remotion のアニメーションだけで補う — タイトルカード、イントロシーケンス、AI 映像が不要なモーショングラフィックスのみのセグメントなどを作成します

生成したクリップを破棄しない

AI 生成クリップの作成には、実際の費用と時間がかかります。生成した映像を放棄して、プログラムによるレンダリングだけに切り替えないでください。 これはよくある失敗パターンです。エージェントがクリップを生成した後、軽微なアーティファクト（例：パターンの繰り返し、わずかな歪み）に気づき、OpenCV／PIL／moviepy によるレンダリングだけに完全に切り替えて、生成にかけた予算を無駄にしてしまいます。

代わりに、次のように対応してください。

状況	誤ったアプローチ	正しいアプローチ
生成したクリップに軽微なアーティファクトがある	クリップを破棄し、OpenCV で一からレンダリングする	クリップを背景として使い、オーバーレイやモーショングラフィックスでアーティファクトを隠す
生成したクリップがイメージと完全には一致しない	再生成するか、使用を諦める	タイポグラフィやエフェクトを上に合成し、視聴者の注意を誘導する
テキストやロゴを正確に配置する必要がある	AI 生成を省き、プログラムによる手法だけを使う	雰囲気のある映像を生成し、Remotion でテキストを重ねる
AI 映像が必要なショットと不要なショットがある	すべてに同じ手法を使う	AI 映像を使ったショットと、Remotion のアニメーションだけを使ったショットを組み合わせる

コストへの配慮

generate_media(mode="video") の呼び出しには、それぞれ高い費用がかかります。生成する前に計画してください。

• 生成を始める前に、どのショットに AI 映像が必要かを決めてください — すべてのショットに必要なわけではありません
• 使用する映像だけを生成してください — うまくいくものがあることを期待して、試しに 8 本のクリップを生成しないでください
• 生成した映像を確認して活用してください — read_media で各クリップを分析してから、実際の映像に合わせて Remotion の構成を計画します
• 未使用のクリップ 5 本より、うまく合成した良質なクリップ 1 本のほうが優れています — 生成数よりも合成の品質に投資してください

ポストプロダクション：常に Remotion を使用する

単純な連結を超える編集が必要な動画では、ポストプロダクションのデフォルトツールとして Remotion を使用してください。 キャプション、タイトル、トランジション、オーバーレイ、モーショングラフィックスなど、プロフェッショナルな仕上がりを目指す動画に必要な作業はすべて含まれます。これらの作業に、生の ffmpeg の drawtext や手動のフィルターチェーンを使用しないでください。Remotion と比べて、仕上がりが素人っぽくなります。

組み立てる動画クリップがある場合は、Remotion のスキルを読み込み、使用してください。 プロフェッショナルな成果物を作るうえで、これは必須です。

Remotion スキルの読み込み

詳細なルールとコード例を確認するには、スキルを読み込んでください。

• ローカルパス（クイックスタートでインストールした場合）：.agent/skills/remotion/SKILL.md
• リモートリポジトリ（インストールしていない場合）：https://github.com/remotion-dev/skills

Remotion でできること

機能	Remotion	生の ffmpeg
スタイル付きアニメーションキャプション	CSS スタイル、単語単位の強調表示、アニメーション	drawtext — 見栄えが悪く、エスケープ処理も大変
タイトルカード／ローワーサード	React コンポーネント、自由なフォント／レイアウト	手動配置、フォントに制限あり
シーンのトランジション	タイミングカーブ、スプリングアニメーション、カスタムエフェクト	基本的な xfade（フェード、ワイプ）
モーショングラフィックス	React／CSS／Three.js／Lottie のエコシステムをフル活用	不可能
ライトリーク／オーバーレイエフェクト	組み込みの @remotion/light-leaks	複雑なフィルターチェーン
テキストアニメーション	タイポグラフィエフェクト、文字単位のアニメーション	実現困難
AI 映像＋オーバーレイ	クリップを <Video> として読み込み、React コンポーネントを上に重ねる	求める品質での実現は不可能

ffmpeg だけで十分な場合

次の用途に限り、Remotion を使わずに ffmpeg を使用してください。

• キャプション、タイトル、トランジションのないクリップの連結（ハードカットのみ）
• 音声のミキシング／ダッキング（ffmpeg または Pydub）
• LUT ファイルを使ったカラーグレーディング（lut3d フィルター）
• 簡単な形式変換やリサイズ

ワークフロー

1. generate_media で AI クリップを生成する（並列、バックグラウンドモード）。映画のような／フォトリアルな品質が必要なショットに使用します。
2. read_media でクリップを確認する。手元の素材を評価し、実際の映像に合わせて構成を計画します。
3. generate_media(mode="audio") で音声（ナレーション、音楽）を生成する。
4. Remotion のスキルを読み込み、Remotion プロジェクトをセットアップする。
5. Remotion で合成する：AI クリップを <Video> の背景レイヤーとして読み込み、タイポグラフィ／モーショングラフィックス／キャプションを重ね、タイトルカードやトランジションにはアニメーションのみのセグメントを追加します。
6. Remotion のヘッドレスレンダラーでレンダリングする。

読み込むべき Remotion の主なルールファイル

特定の作業に取り組む際は、Remotion スキルから関連するルールファイルを読み込んでください。

• キャプション／字幕：rules/subtitles.md、rules/display-captions.md、rules/transcribe-captions.md
• トランジション：rules/transitions.md
• テキストアニメーション：rules/text-animations.md
• ライトリーク：rules/light-leaks.md
• 音声：rules/audio.md、rules/audio-visualization.md
• シーケンス／タイムライン：rules/sequencing.md、rules/trimming.md
• 3D モーショングラフィックス：rules/3d.md
• アニメーション／タイミング：rules/animations.md、rules/timing.md

さらに細かく制御するには？

• バックエンドごとの解像度、長さの詳細、注意点：references/backends.md を参照してください。
• 動画の続き、リミックス、画像から動画への変換：references/editing.md を参照してください。
• マルチショット制作、トランジション、映画的なワークフロー：references/production.md を参照してください。