minimax-multimodal-toolkit

MiniMax マルチモーダルツールキット

MiniMax API を介して音声、音楽、動画、画像を生成します。MiniMax マルチモーダルのユースケース（音声＋音楽＋動画＋画像）に対応する統合エントリーポイントです。カスタム音声向けの音声クローンと音声デザイン、キャラクター参照による画像生成のほか、音声／動画の形式変換、結合、トリミング、抽出を行う FFmpeg ベースのメディアツールを備えています。

セットアップと設定

前提条件

brew install ffmpeg jq              # macOS
sudo apt install ffmpeg jq          # Linux (Debian/Ubuntu)
bash scripts/check_environment.sh   # verify environment

Python や pip は不要です。すべてのスクリプトは curl、ffmpeg、jq、xxd を使用する純粋な bash で動作します。

注： TTS の音声バブル変換（.mp3 → .opus）には ffmpeg が必要です。ffmpeg がない場合、TTS 音声はネイティブ音声バブルではなく、ファイル添付として送信されます。

API の設定

MiniMax は、地域ごとに異なる 2 つのサービスエンドポイントを提供しています。

地域	API ホスト
中国本土（中国大陆）	https://api.minimaxi.com
グローバル（全球）	https://api.minimax.io

OpenClaw の場合 — スキルディレクトリに .env ファイルを作成します（スクリプトが自動的に読み込むため、シェルでのエクスポートは不要です）。

~/.openclaw/workspace/skills/minimax-multimodal-toolkit/.env

MINIMAX_API_KEY=sk-cp-...
MINIMAX_API_HOST=https://api.minimaxi.com

または、openclaw.json で設定します。

"skills": {
  "entries": {
    "minimax-multimodal-toolkit": {
      "env": {
        "MINIMAX_API_HOST": "https://api.minimaxi.com",
        "MINIMAX_API_KEY": "sk-cp-..."
      }
    }
  }
}

その他の環境の場合 — スクリプトを実行する前に、環境変数を設定します。

export MINIMAX_API_HOST="https://api.minimaxi.com"
export MINIMAX_API_KEY="your-key-here"

キーは sk-api- または sk-cp- で始まり、https://platform.minimaxi.com（中国）または https://platform.minimax.io（グローバル）から取得できます。

重要 — 認証情報がない場合： スクリプトを実行する前に、MINIMAX_API_HOST と MINIMAX_API_KEY の両方が設定されていることを確認してください。 どちらかが設定されていない場合は、ユーザーに地域と API キーを尋ね、上記のいずれかの方法で設定できるようサポートしてください。

出力と送信

出力ディレクトリ

生成したファイルはすべて、スキルディレクトリではなく、エージェントの現在の作業ディレクトリにある minimax-output/ に保存する必要があります。 スクリプトを呼び出す際は必ず、ここを指定する明示的な --output / -o 引数を含めてください。出力引数を省略したり、スクリプトのデフォルトに頼ったりしないでください。

ルール：

1. スクリプトを実行する前に、エージェントの作業ディレクトリに minimax-output/ があることを確認します（必要であれば mkdir -p minimax-output で作成します）。
2. エージェントの作業ディレクトリからの絶対パスまたは相対パスを常に使用します：--output minimax-output/video.mp4
3. スキルディレクトリに cd してスクリプトを実行しないでください。 エージェントの作業ディレクトリから、スクリプトのフルパスを使って実行します。
4. 中間ファイル／一時ファイル（音声セグメント、動画セグメント、抽出したフレーム）は、自動的に minimax-output/tmp/ に配置されます。不要になったら削除できます：rm -rf minimax-output/tmp

Feishu への送信（ネイティブバブル）

メディアファイルの生成後は、必ず message ツールを使ってネイティブ Feishu バブルとして送信してください。

message action=send media=<file-path>

メディアの送信に [[reply_to_current]] を使用しないでください。必ず media パラメーターを指定して message ツールを使用してください。

メディアの種類	形式	備考
画像	PNG/JPG/WebP	そのまま送信
動画	.mp4	そのまま送信
音楽	.mp3	そのまま送信
TTS／音声	必ず先に .opus に変換してください	MP3 は音声バブルではなく、ファイル添付として送信されます

TTS 音声 — ネイティブ音声バブルにするために変換が必要です：

ffmpeg -i output.mp3 -c:a libopus -b:a 128k -y output.opus
message action=send media=output.opus

プランの上限とクォータ

重要 — コンテンツを生成する前に、必ずユーザーのプラン上限を確認してください。 ユーザーのクォータが使い切られているか、不足している場合は、続行する前に警告してください。

標準プラン

機能	Starter	Plus	Max
M2.7（チャット）	600 リクエスト/5 時間	1,500 リクエスト/5 時間	4,500 リクエスト/5 時間
Speech 2.8	—	4,000 文字/日	11,000 文字/日
image-01	—	50 枚/日	120 枚/日
Hailuo-2.3-Fast 768P 6s	—	—	2 本/日
Hailuo-2.3 768P 6s	—	—	2 本/日
Music-2.5	—	—	4 曲/日（各 5 分以内）

高速プラン

機能	Plus-HS	Max-HS	Ultra-HS
M2.7-highspeed（チャット）	1,500 req/5h	4,500 req/5h	30,000 req/5h
Speech 2.8	9,000 chars/day	19,000 chars/day	50,000 chars/day
image-01	100 images/day	200 images/day	800 images/day
Hailuo-2.3-Fast 768P 6s	—	3 videos/day	5 videos/day
Hailuo-2.3 768P 6s	—	3 videos/day	5 videos/day
Music-2.5	—	7 songs/day (≤5 min each)	15 songs/day (≤5 min each)

主なクォータ制限：

• 動画の解像度：768Pのみ — どのプランでも1080Pは利用できません
• 動画の長さ：6s — すべてのプランのクォータは6秒単位でカウントされます
• 動画のクォータは非常に限られています（プランにより1日2～5本）— 動画を生成する前に、必ずユーザーに確認してください

主な機能

機能	説明	エントリーポイント
TTS	複数の声や感情表現によるテキスト読み上げ合成	scripts/tts/generate_voice.sh
音声クローン	音声サンプル（10s～5min）から声をクローン	scripts/tts/generate_voice.sh clone
音声デザイン	テキストによる説明からカスタム音声を作成	scripts/tts/generate_voice.sh design
音楽生成	歌詞付きの曲やインストゥルメンタルトラックを生成	scripts/music/generate_music.sh
画像生成	テキストから画像、キャラクター参照による画像から画像の生成	scripts/image/generate_image.sh
動画生成	テキストから動画、画像から動画、被写体参照、テンプレート	scripts/video/generate_video.sh
長尺動画	クロスフェードを使った複数シーンの連結動画	scripts/video/generate_long_video.sh
メディアツール	音声・動画の形式変換、結合、トリミング、抽出	scripts/media_tools.sh

TTS（テキスト読み上げ）

エントリーポイント：scripts/tts/generate_voice.sh

🎙 音声の選択（初回利用時）

初めてTTSを呼び出すときは、ユーザーに音声を選んでもらいます。次の選択肢を提示してください。

おすすめ：

• chunzhen_xuedi — 純真な後輩男子（素直で爽やか、日常使いに適しています）

その他の選択肢：

voice_id	名前	雰囲気
female-shaonv	少女	活発で若々しい
female-yujie	お姉さん	成熟していて優雅
female-tianmei	甘くかわいらしい女性	穏やかで柔らかい
male-qn-qingse	青春まっただ中の青年	学園ものの青春らしさ
male-qn-badao	強引な青年	傲慢で強気
badao_shaoye	強引な若旦那	俺様社長風
junlang_nanyou	ハンサムな彼氏	明るく温かい

全リストは references/tts-voice-catalog.md にあります

設定方法： ユーザーが選んだら、その選択を記憶し、以降のすべてのTTS呼び出しで -v <voice_id> を使用してください。

重要：単一音声と複数セグメント — 適切な方法を選択してください

ユーザーの意図	方法
単一音声／複数キャラクターは不要	tts コマンド — テキスト全体を1回の呼び出しで生成します
複数のキャラクター／ナレーターとセリフ	segments.json を使う generate コマンド

デフォルトの動作： ユーザーが単に音声の生成を依頼し、複数の声やキャラクターに言及していない場合は、適切な単一の音声を使って tts コマンドを直接実行してください。テキストをセグメントに分割したり、複数セグメントのパイプラインを使ったりせず、テキスト全体を1回の呼び出しで tts に渡してください。

複数セグメントの generate を使うのは、次の場合に限ります。

• ユーザーが複数の声やキャラクターを明示的に必要としている
• テキストをナレーターとキャラクターのセリフに分ける必要がある
• テキストが 10,000文字 を超える（リクエストごとのAPI上限）— この場合は、同じ声を使ってセグメントに分割してください

単一音声の生成

# Generate TTS with chosen voice
bash scripts/tts/generate_voice.sh tts "你想说的话" -v chunzhen_xuedi -o minimax-output/output.mp3

# Convert to .opus (required for native Feishu voice bubble)
ffmpeg -i minimax-output/output.mp3 -c:a libopus -b:a 128k -y minimax-output/output.opus

# Send as native voice bubble
message action=send media=minimax-output/output.opus

複数セグメントの生成（複数音声／オーディオブック／ポッドキャスト）

完全なワークフロー — 以下のすべての手順を順番に実行してください。

1. segments.json を作成する — 声の割り当てとともにテキストをセグメントに分割します（形式とルールは以下を参照）
2. generate コマンドを実行する — segments.json を読み込み、TTS APIで各セグメントの音声を生成してから、クロスフェードで1つの出力ファイルに結合します

# Step 1: Write segments.json to minimax-output/
# (use the Write tool to create minimax-output/segments.json)

# Step 2: Generate audio from segments.json — this is the CRITICAL step
# It generates each segment individually and merges them into one file
bash scripts/tts/generate_voice.sh generate minimax-output/segments.json \
  -o minimax-output/output.mp3 --crossfade 200

# Step 3: Convert and send
ffmpeg -i minimax-output/output.mp3 -c:a libopus -b:a 128k -y minimax-output/output.opus
message action=send media=minimax-output/output.opus

手順2を省略しないでください。 segments.json を作成しただけでは何も起こりません。実際に音声を生成するには、必ず generate コマンドを実行してください。

音声の管理

# List all available voices
bash scripts/tts/generate_voice.sh list-voices

# Voice cloning (from audio sample, 10s–5min)
bash scripts/tts/generate_voice.sh clone sample.mp3 --voice-id my-voice

# Voice design (from text description)
bash scripts/tts/generate_voice.sh design "A warm female narrator voice" --voice-id narrator

音声処理

bash scripts/tts/generate_voice.sh merge part1.mp3 part2.mp3 -o minimax-output/combined.mp3
bash scripts/tts/generate_voice.sh convert input.wav -o minimax-output/output.mp3

TTS モデル

モデル	備考
speech-2.8-hd	推奨、感情の自動マッチング
speech-2.8-turbo	高速版
speech-2.6-hd	前世代、手動感情指定
speech-2.6-turbo	前世代、高速版

segments.json フォーマット

セグメント間のデフォルトクロスフェード: 200ms（--crossfade 200）。

[
  { "text": "Hello!", "voice_id": "female-shaonv", "emotion": "" },
  { "text": "Welcome.", "voice_id": "male-qn-qingse", "emotion": "happy" }
]

speech-2.8 モデルでは emotion を空のままにしてください（テキストから自動マッチングされます）。

重要: マルチセグメント台本生成のルール（オーディオブック、ポッドキャストなど）

オーディオブック、ポッドキャスト、その他複数キャラクターのナレーション用の segments.json を生成する場合、ナレーションテキストとキャラクターのセリフを、それぞれ異なるボイスを持つ別々のセグメントに分割する必要があります。

ルール: ナレーションとセリフは常に別々のセグメントにします。

"Tom said: The weather is great today!" のような文は、2 つのセグメントに分割する必要があります:

• セグメント 1（ナレーターボイス）: "Tom said:"
• セグメント 2（キャラクターボイス）: "The weather is great today!"

例 — ナレーター + 2 キャラクターのオーディオブック:

[
  { "text": "Morning sunlight streamed into the classroom as students filed in one by one.", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "Tom smiled and turned to Lisa:", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "The weather is amazing today! Let's go to the park after school!", "voice_id": "tom-voice", "emotion": "happy" },
  { "text": "Lisa thought for a moment, then replied:", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "Sure, but I need to drop off my backpack at home first.", "voice_id": "lisa-voice", "emotion": "" },
  { "text": "They exchanged a smile and went back to listening to the lecture.", "voice_id": "narrator-voice", "emotion": "" }
]

主要な原則:

1. ナレーターは、一貫した中立的なナレーターボイスを全体を通して使用します
2. 各キャラクターには専用の voice_id があり、そのキャラクターのすべてのセリフを通して一貫して維持されます
3. セリフの境界で分割します — "He said:" はナレーター、引用された内容はキャラクターです
4. ナレーションテキストとキャラクターのセリフを1 つのセグメントに統合しないでください
5. 既存の voice_id を持たないキャラクターについては、まずボイスクローニングまたはボイスデザインを使用して作成し、作成した voice_id をセグメントで参照してください

音楽生成

エントリポイント: scripts/music/generate_music.sh

重要: インストゥルメンタル vs 歌詞 — どちらをいつ使うか

シナリオ	モード	アクション
動画 / ボイス / ポッドキャスト用の BGM	インストゥルメンタル（デフォルト）	--instrumental をそのまま使用し、ユーザーに尋ねないでください
ユーザーが明示的に「音楽を作成」/「曲を作成」を求める	まずユーザーに尋ねる	インストゥルメンタルか歌詞付きかを尋ねてください

動画やボイスコンテンツに BGM を追加する場合は、常にデフォルトでインストゥルメンタルモード（--instrumental）を使用してください。ユーザーに尋ねないでください — BGM がメインコンテンツと競合するボーカルを持つべきではありません。

ユーザーが主要なタスクとして明示的に音楽の作成/生成を求める場合は、次のどちらを希望するか尋ねてください:

• インストゥルメンタル（純粋な音楽、ボーカルなし）
• 歌詞付き（ボーカル付きの曲 — ユーザーが提供するか、あなたが歌詞作成を手伝います）

# Instrumental (for BGM or when user chooses instrumental)
bash scripts/music/generate_music.sh \
  --instrumental \
  --prompt "ambient electronic, atmospheric" \
  --output minimax-output/ambient.mp3 --download
message action=send media=minimax-output/ambient.mp3

# Song with lyrics (when user chooses vocal music)
bash scripts/music/generate_music.sh \
  --lyrics "[verse]\nHello world\n[chorus]\nLa la la" \
  --prompt "indie folk, melancholic" \
  --output minimax-output/song.mp3 --download
message action=send media=minimax-output/song.mp3

音楽モデル

デフォルトモデル: music-2.5

music-2.5 は --instrumental を直接サポートしていません。インストゥルメンタル音楽が必要な場合、スクリプトは自動的に回避策を適用します:

• 歌詞を [intro] [outro]（空の構造タグ、実際のボーカルなし）に設定し、プロンプトに pure music, no lyrics を追加します

これにより、手動での介入を必要とせずにインストゥルメンタルスタイルの出力が生成されます。いつでも --instrumental を使用でき、残りはスクリプトが処理します。

画像生成

エントリポイント: scripts/image/generate_image.sh

モデル: image-01 — テキストプロンプトからのフォトリアルな画像生成、キャラクター参照による image-to-image もオプションで可能です。

重要: モード選択 — t2i vs i2i

ユーザーの意図	モード
テキスト記述から画像を生成（デフォルト）	t2i — text-to-image
キャラクター参照写真を使って画像を生成（同じ人物を維持）	i2i — image-to-image

デフォルトの動作: ユーザーが参照写真に言及せずに画像の生成/作成を求めた場合は、t2i モード（デフォルト）を使用します。i2i モードは、ユーザーがキャラクター参照画像を提供した場合、または既存の人物の外見に基づいて画像を生成することを明示的に求めた場合にのみ使用してください。

重要：アスペクト比 — ユーザーのコンテキストから推測してください

常に 1:1 をデフォルトにしないでください。ユーザーのリクエストを分析し、最適なアスペクト比を選んでください。

ユーザーの意図／コンテキスト	推奨比率	解像度
头像、アイコン、ソーシャルメディアのプロフィール画像、avatar、icon、profile pic	1:1	1024×1024
風景、バナー、デスクトップ壁紙、landscape、banner、desktop wallpaper	16:9	1280×720
従来の写真、クラシックな比率、classic photo	4:3	1152×864
写真作品、雑誌の表紙、photography、magazine	3:2	1248×832
縦向きの人物写真、ポスター、portrait photo、poster	2:3	832×1248
縦長のポスター、書籍の表紙、tall poster、book cover	3:4	864×1152
スマートフォンの壁紙、ソーシャルメディアのストーリー、phone wallpaper、story、reel	9:16	720×1280
超ワイドのパノラマ、シネマスコープ、panoramic、cinematic ultrawide	21:9	1344×576
特別な要望が指定されていない場合／曖昧な場合	1:1	1024×1024

重要：画像枚数 — 複数の画像を生成する場合

ユーザーの意図	枚数（-n）
デフォルト／画像を1枚リクエスト	1（デフォルト）
ユーザーが「几张」「多张」「一些」／「a few」「several」と言っている	3
ユーザーが「多种方案」「备选」／「variations」「options」と言っている	3～4
ユーザーが枚数を明示している	指定された枚数（1～9）を使用

テキストから画像を生成する例

# Basic text-to-image
bash scripts/image/generate_image.sh \
  --prompt "A cat sitting on a rooftop at sunset, cinematic lighting, warm tones, photorealistic" \
  -o minimax-output/cat.png
message action=send media=minimax-output/cat.png

# Landscape with inferred aspect ratio
bash scripts/image/generate_image.sh \
  --prompt "Mountain landscape with misty valleys, photorealistic, golden hour" \
  --aspect-ratio 16:9 \
  -o minimax-output/landscape.png
message action=send media=minimax-output/landscape.png

# Phone wallpaper (portrait 9:16)
bash scripts/image/generate_image.sh \
  --prompt "Aurora borealis over a snowy forest, vivid colors, magical atmosphere" \
  --aspect-ratio 9:16 \
  -o minimax-output/wallpaper.png
message action=send media=minimax-output/wallpaper.png

# Multiple variations
bash scripts/image/generate_image.sh \
  --prompt "Abstract geometric art, vibrant colors" \
  -n 3 \
  -o minimax-output/art.png
message action=send media=minimax-output/art.png

# With prompt optimizer
bash scripts/image/generate_image.sh \
  --prompt "A man standing on Venice Beach, 90s documentary style" \
  --aspect-ratio 16:9 --prompt-optimizer \
  -o minimax-output/beach.png
message action=send media=minimax-output/beach.png

# Custom dimensions (must be multiple of 8)
bash scripts/image/generate_image.sh \
  --prompt "Product photo of a luxury watch on marble surface" \
  --width 1024 --height 768 \
  -o minimax-output/watch.png
message action=send media=minimax-output/watch.png

画像から画像へ（キャラクター参照）

参照写真を使って、同じキャラクターが登場する新しいシーンの画像を生成します。正面を向いた人物のポートレートを1枚使用すると、最良の結果が得られます。対応形式：JPG、JPEG、PNG（最大10MB）。

# Character reference — place same person in a new scene
bash scripts/image/generate_image.sh \
  --mode i2i \
  --prompt "A girl looking into the distance from a library window, warm afternoon light" \
  --ref-image face.jpg \
  --aspect-ratio 16:9 \
  -o minimax-output/girl_library.png
message action=send media=minimax-output/girl_library.png

# Multiple character variations
bash scripts/image/generate_image.sh \
  --mode i2i \
  --prompt "A woman in a red dress at a gala event, elegant, cinematic" \
  --ref-image face.jpg -n 3 \
  -o minimax-output/gala.png
message action=send media=minimax-output/gala.png

アスペクト比の参照表

比率	解像度	最適な用途
1:1	1024×1024	デフォルト、アバター、アイコン、ソーシャルメディア
16:9	1280×720	風景、バナー、デスクトップ壁紙
4:3	1152×864	クラシックな写真、プレゼンテーション
3:2	1248×832	写真、雑誌レイアウト
2:3	832×1248	人物のポートレート、ポスター
3:4	864×1152	書籍の表紙、縦長のポスター
9:16	720×1280	スマートフォンの壁紙、ソーシャルメディアのストーリー／リール
21:9	1344×576	超ワイドのパノラマ、シネマスコープ

主なオプション

オプション	説明
--prompt TEXT	画像の説明。最大1500文字（必須）
--aspect-ratio RATIO	アスペクト比（上の表を参照）。ユーザーのコンテキストから推測してください
--width PX / --height PX	カスタムサイズ。512～2048、8の倍数で指定し、両方を一緒に指定する必要があります。両方を指定した場合、--aspect-ratio が優先されます
-n N	生成する画像の枚数。1～9（デフォルトは1）
--seed N	再現性を得るための乱数シード。同じシードと同じパラメーターを使用すると、類似した結果になります
--prompt-optimizer	API によるプロンプトの自動最適化を有効にします
--ref-image FILE	i2i モード用のキャラクター参照画像（ローカルファイルまたは URL、JPG/JPEG/PNG、最大10MB）
--no-download	ファイルをダウンロードせず、画像 URL を出力します
--aigc-watermark	生成画像に AIGC ウォーターマークを追加します

動画生成

重要：単一セグメントと複数セグメント — 適切なスクリプトを選択してください

ユーザーの意図	使用するスクリプト
デフォルト／特別なリクエストなし	scripts/video/generate_video.sh（単一セグメント、6秒、768P）
ユーザーが「長い動画」「複数シーン」「ストーリー」を明示的にリクエストした場合、または長さが10秒を超える場合	scripts/video/generate_long_video.sh（複数セグメント）

デフォルトの動作： ユーザーが長い動画または複数シーンの動画を明示的にリクエストしない限り、常に単一セグメントの generate_video.sh を使用し、長さは6秒、解像度は768P にしてください。自動的に複数セグメントに分割しないでください。6秒の動画1本が標準の出力です。generate_long_video.sh は、複数シーンまたはより長いコンテンツが明らかに必要な場合にのみ使用してください。

エントリーポイント（単一動画）：scripts/video/generate_video.sh エントリーポイント（長尺／複数シーン）：scripts/video/generate_long_video.sh

動画モデルの制約（必ず従ってください）

モデルごとの対応解像度と再生時間：

モデル	解像度	再生時間
MiniMax-Hailuo-2.3	768P のみ	6s または 10s
MiniMax-Hailuo-2.3-Fast	768P のみ	6s または 10s
MiniMax-Hailuo-02	512P、768P（デフォルト）	6s または 10s
T2V-01 / T2V-01-Director	720P	6s のみ
I2V-01 / I2V-01-Director / I2V-01-live	720P	6s のみ
S2V-01 (ref)	720P	6s のみ

主なルール：

• デフォルト：6s + 768P — プランの割り当て量は6秒単位で計算されます。ユーザーが明示的に10sを希望しない限り、6sを使用してください
• 1080Pには対応していません — すべてのプランで非対応です。Hailuo-2.3/2.3-Fastでは必ず768Pを使用してください
• 旧モデル（T2V-01、I2V-01、S2V-01）は720P、6sのみ対応しています

⚠️ 再生時間とアカウントプラン： MiniMax-Hailuo-2.3は6sまたは10sに対応していますが、一部のアカウントは6sのみに対応しています。 「token plan not support model, MiniMax-Hailuo-2.3-10s-768p」というエラーが発生した場合は、--duration 6に切り替えてください。 10sの動画生成を試す前に、必ずユーザーのプラン制限を確認してください。

重要：プロンプトの最適化（動画を生成する前に必ず実施）

動画生成スクリプトを呼び出す前に、必ずreferences/video-prompt-guide.mdを読み、そこに記載された内容を適用してユーザーのプロンプトを最適化してください。ユーザーの説明文をそのまま--promptに渡してはいけません。

最適化の手順：

1. プロフェッショナルな構成を適用する：主な被写体 + シーン + 動き + カメラワーク + 雰囲気

   • 悪い例："A puppy in a park"
   • 良い例："A golden retriever puppy runs toward the camera on a sun-dappled grass path in a park, [跟随] smooth tracking shot, warm golden hour lighting, shallow depth of field, joyful atmosphere"

2. [指令]構文を使ってカメラの指示を追加します：[推进]、[拉远]、[跟随]、[固定]、[左摇]など

3. 美的な細部を盛り込む：照明（ゴールデンアワー、ドラマチックなサイドライト）、カラーグレーディング（暖色系、シネマティック）、テクスチャ（ほこりの粒子、雨粒）、雰囲気（親密、壮大、穏やか）

4. 6～10秒の動画では、主要な動作を1～2個に絞ります。出来事を詰め込みすぎないでください

5. i2vモード（画像から動画への変換）の場合：画像ですでに視覚的な情報が確立されているため、プロンプトでは動きと変化のみに焦点を当てます。画像の内容を再度説明しないでください。

   • 悪い例："A lake with mountains"（画像の内容を繰り返しているだけ）
   • 良い例："Gentle ripples spread across the water surface, a breeze rustles the distant trees, [固定] fixed camera, soft morning light, peaceful and serene"

6. 複数セグメントからなる長尺動画の場合：各セグメントのプロンプトは、それぞれ単独で意味が通るように最適化してください。i2vのセグメント（セグメント2以降）では、直前のセグメントの最終フレームからの動きや変化を記述します。

# Text-to-video (default: 6s, 768P)
bash scripts/video/generate_video.sh \
  --mode t2v \
  --prompt "A golden retriever puppy bounds toward the camera on a sunlit grass path, [跟随] tracking shot, warm golden hour, shallow depth of field, joyful" \
  --output minimax-output/puppy.mp4
message action=send media=minimax-output/puppy.mp4

# Image-to-video (prompt focuses on MOTION, not image content)
bash scripts/video/generate_video.sh \
  --mode i2v \
  --prompt "The petals begin to sway gently in the breeze, soft light shifts across the surface, [固定] fixed framing, dreamy pastel tones" \
  --first-frame photo.jpg \
  --output minimax-output/animated.mp4
message action=send media=minimax-output/animated.mp4

# Start-end frame interpolation (sef mode uses MiniMax-Hailuo-02)
bash scripts/video/generate_video.sh \
  --mode sef \
  --first-frame start.jpg --last-frame end.jpg \
  --output minimax-output/transition.mp4
message action=send media=minimax-output/transition.mp4

# Subject reference (face consistency, ref mode uses S2V-01, 6s only)
bash scripts/video/generate_video.sh \
  --mode ref \
  --prompt "A young woman in a white dress walks slowly through a sunlit garden, [跟随] smooth tracking, warm natural lighting, cinematic depth of field" \
  --subject-image face.jpg \
  --duration 6 \
  --output minimax-output/person.mp4
message action=send media=minimax-output/person.mp4

長尺動画（複数シーン）

複数シーンからなる長尺動画は、セグメントを連結して作成します。最初のセグメントはテキストから動画を生成（t2v）し、その後の各セグメントでは、前のセグメントの最終フレームを最初のフレームとして使用します（i2v）。セグメントはクロスフェードでつなぎ、滑らかに連続させます。デフォルトでは、各セグメントは6秒です。

ワークフロー：

1. セグメント1：t2v — 最適化したテキストプロンプトのみから生成します
2. セグメント2以降：i2v — 前のセグメントの最終フレームをfirst_frame_imageとして使用し、その終了時点からの動きと変化をプロンプトで記述します
3. すべてのセグメントを0.5秒のクロスフェードで連結し、ジャンプカットをなくします
4. オプション：AI生成のBGMを重ねます

各セグメントのプロンプトルール：

• 各セグメントのプロンプトは、プロフェッショナルな構成を使って個別に最適化する必要があります
• セグメント1（t2v）：被写体、シーン、カメラ、雰囲気を含むシーン全体の説明
• セグメント2以降（i2v）：前のセグメントの最終フレームから何が変化し、どう動くかに焦点を当てます。最初のフレームが視覚情報をすでに提供しているため、映像の説明を繰り返さないでください
• 視覚的な一貫性を保つため、照明、カラーグレーディング、スタイルを表すキーワードをセグメント間で統一します
• 各セグメントで扱う動作は6秒間のみです。内容を絞ってください

# Example: 3-segment story with optimized per-segment prompts (default: 6s/segment, 768P)
bash scripts/video/generate_long_video.sh \
  --scenes \
    "A lone astronaut stands on a red desert planet surface, wind blowing dust particles, [推进] slow push in toward the visor, dramatic rim lighting, cinematic sci-fi atmosphere" \
    "The astronaut turns and begins walking toward a distant glowing structure on the horizon, dust swirling around boots, [跟随] tracking from behind, vast desolate landscape, golden light from the structure" \
    "The astronaut reaches the structure entrance, a massive doorway pulses with blue energy, [推进] slow push in toward the doorway, light reflects off the visor, awe-inspiring epic scale" \
  --music-prompt "cinematic orchestral ambient, slow build, sci-fi atmosphere" \
  --output minimax-output/long_video.mp4
message action=send media=minimax-output/long_video.mp4

# With custom settings
bash scripts/video/generate_long_video.sh \
  --scenes "Scene 1 prompt" "Scene 2 prompt" \
  --segment-duration 6 \
  --resolution 768P \
  --crossfade 0.5 \
  --music-prompt "calm ambient background music" \
  --output minimax-output/long_video.mp4
message action=send media=minimax-output/long_video.mp4

BGMを追加する

bash scripts/video/add_bgm.sh \
  --video input.mp4 \
  --generate-bgm --instrumental \
  --music-prompt "soft piano background" \
  --bgm-volume 0.3 \
  --output minimax-output/output_with_bgm.mp4

テンプレート動画

bash scripts/video/generate_template_video.sh \
  --template-id 392753057216684038 \
  --media photo.jpg \
  --output minimax-output/template_output.mp4

動画モデル

モード	デフォルトモデル	デフォルトの長さ	デフォルトの解像度	備考
t2v	MiniMax-Hailuo-2.3	6s	768P	最新のテキストから動画への生成
i2v	MiniMax-Hailuo-2.3	6s	768P	最新の画像から動画への生成
sef	MiniMax-Hailuo-02	6s	768P	開始フレームと終了フレーム
ref	S2V-01	6s	720P	被写体の参照。6s のみ

メディアツール（音声／動画処理）

エントリーポイント：scripts/media_tools.sh

フォーマット変換、連結、抽出、トリミング、音声のオーバーレイに対応した、FFmpeg ベースのスタンドアロンユーティリティです。MiniMax API を使って新しいコンテンツを生成せず、既存のメディアファイルを処理する必要がある場合に使用します。

動画フォーマット変換

# Convert between formats (mp4, mov, webm, mkv, avi, ts, flv)
bash scripts/media_tools.sh convert-video input.webm -o output.mp4
bash scripts/media_tools.sh convert-video input.mp4 -o output.mov

# With quality / resolution / fps options
bash scripts/media_tools.sh convert-video input.mp4 -o output.mp4 \
  --crf 18 --preset medium --resolution 1920x1080 --fps 30

音声フォーマット変換

# Convert between formats (mp3, wav, flac, ogg, aac, m4a, opus, wma)
bash scripts/media_tools.sh convert-audio input.wav -o output.mp3
bash scripts/media_tools.sh convert-audio input.mp3 -o output.flac \
  --bitrate 320k --sample-rate 48000 --channels 2

動画の連結

# Concatenate with crossfade transition (default 0.5s)
bash scripts/media_tools.sh concat-video seg1.mp4 seg2.mp4 seg3.mp4 -o merged.mp4

# Hard cut (no crossfade)
bash scripts/media_tools.sh concat-video seg1.mp4 seg2.mp4 -o merged.mp4 --crossfade 0

音声の連結

# Simple concatenation
bash scripts/media_tools.sh concat-audio part1.mp3 part2.mp3 -o combined.mp3

# With crossfade
bash scripts/media_tools.sh concat-audio part1.mp3 part2.mp3 -o combined.mp3 --crossfade 1

動画から音声を抽出

# Extract as mp3
bash scripts/media_tools.sh extract-audio video.mp4 -o audio.mp3

# Extract as wav with higher bitrate
bash scripts/media_tools.sh extract-audio video.mp4 -o audio.wav --bitrate 320k

動画のトリミング

# Trim by start/end time (seconds)
bash scripts/media_tools.sh trim-video input.mp4 -o clip.mp4 --start 5 --end 15

# Trim by start + duration
bash scripts/media_tools.sh trim-video input.mp4 -o clip.mp4 --start 10 --duration 8

動画に音声を追加（オーバーレイ／置き換え）

# Mix audio with existing video audio
bash scripts/media_tools.sh add-audio --video video.mp4 --audio bgm.mp3 -o output.mp4 \
  --volume 0.3 --fade-in 2 --fade-out 3

# Replace original audio entirely
bash scripts/media_tools.sh add-audio --video video.mp4 --audio narration.mp3 -o output.mp4 \
  --replace

メディアファイル情報

bash scripts/media_tools.sh probe input.mp4

スクリプトのアーキテクチャ

scripts/
├── check_environment.sh         # Env verification (curl, ffmpeg, jq, xxd, API key)
├── media_tools.sh               # Audio/video conversion, concat, trim, extract
├── tts/
│   └── generate_voice.sh        # Unified TTS CLI (tts, clone, design, list-voices, generate, merge, convert)
├── music/
│   └── generate_music.sh        # Music generation CLI
├── image/
│   └── generate_image.sh        # Image generation CLI (2 modes: t2i, i2i)
└── video/
    ├── generate_video.sh        # Video generation CLI (4 modes: t2v, i2v, sef, ref)
    ├── generate_long_video.sh   # Multi-scene long video
    ├── generate_template_video.sh # Template-based video
    └── add_bgm.sh              # Background music overlay

参考資料

API パラメーター、音声カタログ、プロンプトエンジニアリングの詳細については、以下を参照してください。

• tts-guide.md — TTS のセットアップ、音声管理、音声処理、セグメント形式、トラブルシューティング
• tts-voice-catalog.md — ID、説明、パラメーターのリファレンスを含む音声カタログ全体
• music-api.md — 音楽生成 API：エンドポイント、パラメーター、レスポンス形式
• image-api.md — 画像生成 API：テキストから画像への生成、画像から画像への生成、パラメーター
• video-api.md — 動画 API：エンドポイント、モデル、パラメーター、カメラ指示、テンプレート
• video-prompt-guide.md — 動画プロンプトエンジニアリング：数式、スタイル、画像から動画への生成のヒント