multimedia-backend-integrator

マルチメディアバックエンドインテグレーター

MassGen の統合 generate_media ツールに新しいメディア生成バックエンドを追加するためのリファレンスガイドです。

アーキテクチャの概要

_base.py          -- Registration: API keys, default models, priority lists
_selector.py      -- Auto-selection logic: picks best backend by key + priority
_image.py         -- Image backends: OpenAI, Google (Gemini/Imagen), Grok, OpenRouter
_video.py         -- Video backends: Grok, Google Veo, OpenAI Sora
_audio.py         -- Audio backends: ElevenLabs, OpenAI TTS
generate_media.py -- Entry point: routing, validation, batch mode, image-to-image

新しいバックエンドを追加するための完全なチェックリスト

1. 登録（_base.py）

• BACKEND_API_KEYS に追加：バックエンド名を環境変数にマッピングします
• DEFAULT_MODELS に追加：バックエンド名を、サポートする各タイプの {MediaType: model_name} にマッピングします
• BACKEND_PRIORITY に追加：メディアタイプごとの適切な位置に挿入します

2. 実装（_image.py / _video.py / _audio.py）

• モジュールの先頭で SDK の import を追加します
• _generate_{media}_{backend}(config) -> GenerationResult を実装します
• 最初に API キーを確認し、キーがない場合はエラー結果を返します
• API キーを使って SDK クライアントを作成します
• config.* のフィールドを SDK のパラメーターにマッピングします
• 継続処理（該当する場合）を処理します —「継続ストアのパターン」を参照してください
• 出力バイト列を config.output_path に書き込みます
• メタデータを含む GenerationResult を返します
• try/except で囲み、エラーをログに記録します

3. ディスパッチャーの更新

• メディアタイプの generate_{media}() 関数に elif backend == "new_backend": を追加します

4. 画像から画像への生成のサポート（generate_media.py）

• _generate_single_with_input_images の selected_backend not in (...) チェックにバックエンド名を追加します
• 自動選択チェーンにフォールバックとして elif has_api_key("new_backend"): を追加します
• エラーメッセージを更新し、新しいバックエンドと環境変数に言及します

5. ドキュメント

• TOOL.md：フロントマターに環境変数を、表にバックエンドを、キーワードに関連語を追加します
• generate_media.py の docstring：backend_type のリストと Supported Backends を更新します

6. テスト

• バックエンド登録テスト（API キー、デフォルトモデル、優先順位）
• 自動選択テスト（このバックエンドのキーのみの場合、複数のキーがある場合）
• SDK 呼び出しの検証（正しいパラメーターが渡されること）
• 出力ファイルが正しく書き込まれること
• 継続処理のフロー（該当する場合）
• エラー処理（キーの欠落、API エラー）
• パラメーターのマッピング（aspect_ratio、size、duration）
• 優先順位リストの長さや内容を検証する既存のテストを更新します

継続ストアのパターン

反復編集をサポートする各バックエンドには、継続処理の仕組みが必要です。

バックエンド	ストアの種類	キーの形式	保存する内容	継続処理の方法
OpenAI	ステートレス（サーバー側）	response.id	ローカルには何も保存しません	次の呼び出しに previous_response_id を渡します
Gemini	_GeminiChatStore（インメモリー）	gemini_chat_{uuid12}	（クライアント、チャット）のタプル	send_message() にチャットオブジェクトを再利用します。HTTP 接続の GC を防ぐため、クライアントは保持します
Grok	_GrokImageStore（インメモリー）	grok_img_{uuid12}	Base64 文字列	保存した Base64 を image_url データ URI として渡します

ストアパターンのテンプレート

class _NewBackendStore:
    def __init__(self, max_items: int = 50):
        self._store: OrderedDict[str, Any] = OrderedDict()
        self._max = max_items

    def save(self, data: Any) -> str:
        store_id = f"prefix_{uuid.uuid4().hex[:12]}"
        if len(self._store) >= self._max:
            self._store.popitem(last=False)  # LRU eviction
        self._store[store_id] = data
        return store_id

    def get(self, store_id: str) -> Any | None:
        return self._store.get(store_id)

_store = _NewBackendStore()

よくある落とし穴

1. 優先順位リストへの追加漏れ — バックエンドを明示的に指定すれば動作しますが、自動選択されません
2. 同期処理と非同期処理 — SDK によっては同期処理のみです。必要に応じて asyncio.to_thread() でラップします
3. 一時的な URL — 一時的な URL を返す API があります。常に Base64 を優先するか、すぐにダウンロードしてください
4. 偽と評価される duration — duration or default では 0 が偽と評価されます。if duration is not None を使用してください
5. 既存テストへの影響 — 優先順位リストへの追加によって自動選択が変わります。環境変数をクリアする既存テストを更新してください
6. 画像から画像への生成の制限 — _generate_single_with_input_images 関数には、許可するバックエンドのリストがあります

参照ファイル

ファイル	目的
massgen/tool/_multimodal_tools/generation/_base.py	API キー、デフォルトモデル、優先順位
massgen/tool/_multimodal_tools/generation/_selector.py	バックエンドの自動選択ロジック
massgen/tool/_multimodal_tools/generation/_image.py	画像生成バックエンド
massgen/tool/_multimodal_tools/generation/_video.py	動画生成バックエンド
massgen/tool/_multimodal_tools/generation/_audio.py	音声生成バックエンド
massgen/tool/_multimodal_tools/generation/generate_media.py	エントリーポイントとルーティング
massgen/tool/_multimodal_tools/TOOL.md	ユーザー向けドキュメント
massgen/tests/test_grok_multimedia_generation.py	参照：Grok バックエンドのテスト
massgen/tests/test_grok_multimedia_backend_selection.py	参照：Grok 選択テスト
massgen/tests/test_multimodal_image_backend_selection.py	参照：画像選択テスト