mediagen

mediagen — コーディングエージェント向け画像・動画生成スキル

Google Gemini、OpenAI 、Kie AIを使った画像・動画生成をエージェントに提供します。スキルもインストールも1つだけで、APIを覚える必要はありません。

作りたいものを大まかに伝えれば、あとはエージェントに任せられます。

You:   Make a hero image for the landing page, wide, something moody and industrial.

Agent: npx -y mediagen image "A disused loading dock at dusk, wet concrete…"
         --aspect-ratio 21:9 --json
       → ./output/image-20260823T094107Z.png

プロンプトを省略せずに書き出し、21:9のルールからOpenAIでは対応できないことを把握し、--jsonからパスを読み取りました。

あるいは、詳細を正確に指定すれば、エージェントが判断することはありません。

You:   Same thing with gemini-3-pro-image, 21:9, 4K, marked as AI-generated,
       saved as hero.png.

Agent: npx -y mediagen image "A disused loading dock at dusk, wet concrete…"
         --model gemini-3-pro-image --aspect-ratio 21:9 --size 4K
         --output-name hero.png --json
       → ./output/hero.jpg

       [looks at the image]

       npx -y mediagen mark ./output/hero.jpg --visible-label
         --label-position top-right --json
       → ./output/hero.labelled.jpg

対象がどこに配置されたかを確認してから、2回目の処理でマークを付けました。ラベルは搬入口の上ではなく、平らな屋根のラインに置きました。

CLIで指定できることはすべて、言葉で伝えられます。プロバイダー、モデル、アスペクト比、サイズ、出力名とディレクトリ、品質プリセット、動画の長さ、編集する入力画像、そして結果にマークを付けるかどうかです。指定した項目はそのまま使用し、省略した項目はエージェントが選択するか、設定済みの値を使用します。

インストール

npx -y skills add Cripacx/mediagen --skill mediagen

インストールはこれだけです。ほかに設定するものはありません。このスキルはnpx経由でCLIを実行し、初回の使用時に取得して、その後はキャッシュします。

次に、APIキーを設定します。

npx -y mediagen init

対話式ウィザードで、プロバイダーを選択し、各キーを画面に表示されない状態で入力し、実際のAPIで検証し、プロバイダーごとにモデルを選び、デフォルトを設定します。最初はキーが1つあれば十分です。

あとは、エージェントに画像を頼むだけです。

エージェントでできること

• 説明に基づいて画像や動画を生成したり、すでにあるメディアを編集したりできます
• タスクに適したプロバイダーを選択します。スキルはGeminiが21:9と動画に対応し、OpenAIは16:9にまったく対応しておらず、Kieが約30種類のサードパーティーモデルを集約していることを把握しています
• 指示があればそのとおりに実行します。モデル、比率、サイズ、ファイル名を指定すれば、その指定どおりに使用します。選ぶ前に利用可能な項目を確認したい場合は、mediagen modelsを実行できます
• プロンプトを適切に作成します。このスキルにはプロンプト作成のガイダンスが含まれているため、「雰囲気のある工業的なヒーロー画像」と伝えるだけで、送信前に被写体、構図、光、カメラ、素材を詳しく記述します
• 必要に応じてAI生成の出力にマークを付けます。フォトリアリスティックな画像や公開を目的とした画像では、スキルがマークを付けるよう提案します
• すべてのエラーに機械可読コードと次のアクションが含まれているため、失敗から自動で復旧します

また、チャットにAPIキーを貼り付けるよう求めることはありません。設定エラーが発生した場合は、自分のターミナルでmediagen initを実行するよう案内します。

前提条件

• APIキーが1つ以上あること：
  • Google Gemini（こちらから取得）— 画像と動画、最も幅広いアスペクト比に対応
  • OpenAI（こちらから取得）— 画像
  • Kie AI（こちらから取得）— 約30種類のサードパーティーモデル
• Node.js 20.11以降

設定

初回の設定はmediagen initで行います。あとから設定を変更するには：

npx -y mediagen config edit

各設定の現在の値と、その値の取得元をすべてメニューに表示します。プロバイダー、モデル、キー、出力ディレクトリ、品質プリセット、mediagen markのデフォルトの動作を確認できます。変更内容は、変更するたびに書き込まれます。

ターミナルがないCIやスクリプトでは、config setに同じ設定を引数として渡します。

echo "$GEMINI_API_KEY" | npx -y mediagen config set gemini --stdin
npx -y mediagen config set gemini-model gemini-3-pro-image

使用するプロバイダー

優先順位を設定します。最も優先するものを先頭にしてください。

npx -y mediagen config set provider-priority gemini,kie,openai

これは優先設定であり、許可リストではありません。--provider を指定しないリクエストは、優先順位の先頭から、キーが設定されていてかつその処理を実行できるプロバイダーに送られます。そのため、OpenAI のキーがなくても Gemini で実行できる処理は止まりません。また、動画を要求すると、動画を生成できないプロバイダーは飛ばされます。--provider を指定すると、これらすべての設定より優先されます。

mediagen models では、設定された優先順位、使用可能なプロバイダー、リクエストの送信先を確認できます。

1. Google Gemini (gemini)  [preferred, key from config file]
  Would use: gemini-3.1-flash-image  (provider default)
2. Kie AI (kie)  [key from config file]
3. OpenAI (openai)  [preferred, no key]
  No key configured, so requests to it fail. Fix: mediagen config set openai

A request with no --provider uses gemini/gemini-3.1-flash-image.

--json を指定すると、wouldUse、usableProviders、providerPriority も追加されます。スキルは生成前にエージェントにこの情報を読み取らせるため、キーが設定されていないプロバイダーのモデルを選ぶことはありません。

設定内容とキーが引き続き有効かどうかを確認するには、次を実行します。

npx -y mediagen doctor

doctor はプロバイダーごとに、キーが設定されているか、どのレイヤーから読み込まれたか、プロバイダーがキーを受け付けるかを報告します。また、未設定、拒否、到達不能、_安価に確認する方法がない_を区別します。それぞれ必要な対処が異なるためです。

警告

API キーを引数として受け取るフラグは、意図的に用意していません。引数はシェルの履歴やプロセス一覧に残り、使用したコマンドの終了後も消えないためです。

設定は、まず環境変数、次に作業ディレクトリ内の .env、最後に設定ファイルの順に読み込まれます。

ヒント

この種のツールで最も大きな問題になるのは、古い環境変数が新たに設定したキーを上書きすることです。mediagen config list では、上書きされている値がすべて表示されるため、推測ではなく実際に確認できます。

プロバイダー

メモ

OpenAI はアスペクト比ではなくピクセル寸法を受け取り、実際に 16:9 の画像を生成できません。最も横長の画像は 1536×1024、つまり 3:2 です。16:9 を要求した場合、別の比率で黙って提供するのではなく、指定された比率に対応できないことが明示されます。この制約をスキルは把握しており、横長の比率は Gemini に振り分けます。

一覧にないモデルもプロバイダーに送信されるため、mediagen が把握する前にリリースされたモデルでも使用できます。Kie のカタログは手作業で管理するのではなく、Kie の公式ドキュメントから生成されます。

コンテンツのマーキング

EU AI Act では開示義務が2つに分かれているため、mediagen mark には互いに独立した2つのスイッチがあります。

生成時にマーキングは行われません。 マーキングは常に、ファイルに対して後から実行する2つ目のコマンドです。

npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K --json
npx -y mediagen mark ./output/image-….jpg --visible-label --label-position top-left

これは単なる形式ではありません。視覚ラベルは被写体がない場所に配置する必要があり、その場所を判断できるのは完成した画像だけです。機械可読マーカーも無料ではありません。JPEGやWebPにメタデータを追加するにはデコードと再エンコードが必要なため、マーキングには2回目の非可逆処理が伴います。画像を求めた副作用としてではなく、意図して行う価値があります。mediagen は高品質で再エンコードしてこの影響を小さくしますが、ゼロにはできません。

毎回指定しなくても、mediagen mark が視覚ラベルを描画するようにするには、次のようにします。

npx -y mediagen config edit      # "AI marking by default"

デフォルトを設定しても、実行ごとに --no-mark または --no-visible-label で上書きできます。

視覚ラベルには、欧州委員会独自のアイコンが使われます。これは AI 生成コンテンツの透明性に関する実施規範とともに公開されたもので、クレジット表記なしで無料で使用できます。3種類のうち2種類を使用します。デフォルトでは AI GENERATED、--modified を指定すると AI MODIFIED です。後者は、人が作成したメディアをモデルが変更した場合に使います。ラベルを読めなければ開示にならないため、配置先の隅の実際の背景に応じて、明るい版または暗い版が選ばれます。

デフォルトでは右下に配置されます。--label-position で別の隅に移動するか、auto を指定すると画像内で最も細部の少ない場所に配置されます。

重要

視覚ラベルが元のファイルに上書きされることはありません。mediagen mark photo.png --visible-label は photo.labelled.png を生成し、photo.png のピクセルはそのまま保持しつつ、そこに機械可読マーカーを書き込みます。そのため、どちらを公開しても開示情報が含まれます。ラベルの配置に問題があれば、変更されていない元ファイルからやり直せます。それ以外のファイルからはやり直せません。上書きしてよい場合は --in-place を指定してください。

エージェントなしで使う

スキルは CLI をラップしたもので、CLI 単独でも使用できます。

npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K
npx -y mediagen image "make the sky stormy" --input ./photo.jpg
npx -y mediagen mark ./output/image-….jpg --visible-label
npx -y mediagen video "a marble rolling down a wooden track" --duration 6
npx -y mediagen models

短いコマンドを使いたいほど頻繁に利用する場合は、グローバルにインストールします。

npm install -g mediagen

オプション

ヒント

スキルを使わない場合、プロンプトの作成は自分で行う必要があります。mediagen はプロンプトを記述どおりに送信し、展開も書き換えもしません。被写体、構図、光、カメラまたは画材、素材、雰囲気を決め、望まないものではなく、望むものを伝えてください。

スクリプトでの利用

--json を指定すると、標準出力には JSON オブジェクトが 1 つだけ出力され、それ以外は何も出力されません。 指定しない場合、保存先のパスは最後の行に出力されます。また、失敗時には標準出力に何も出力されないため、最後の行を読み取っても、パスの代わりにエラーメッセージを受け取ることはありません。

{
  "success": true,
  "filePath": "./output/image-20260823T094107Z.png",
  "kind": "image",
  "provider": "gemini",
  "model": "gemini-3.1-flash-image",
  "mimeType": "image/png"
}

失敗時には errorCode が付与されます。値は VALIDATION_ERROR、CONFIG_ERROR、 API_ERROR、NETWORK_ERROR、FILE_ERROR、CONTENT_BLOCKED、TIMEOUT のいずれかです。 また、具体的な次の操作を示す hint も付与されます。

MCP サーバーとして使用する

スキルを実行する代わりに MCP を使用するホスト向けです。同じパッケージを mediagen mcp で起動し、 generate_media、list_models、check_configuration を公開します。

claude mcp add mediagen --env GEMINI_API_KEY=your-api-key-here -- npx -y mediagen mcp

{
  "mcpServers": {
    "mediagen": {
      "command": "npx",
      "args": ["-y", "mediagen", "mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

code --add-mcp "{\"name\":\"mediagen\",\"command\":\"npx\",\"args\":[\"-y\",\"mediagen\",\"mcp\"]}"

{
  "servers": {
    "mediagen": {
      "command": "npx",
      "args": ["-y", "mediagen", "mcp"]
    }
  }
}

mediagen init の実行後は、いずれの設定でも env を省略できます。サーバーは CLI と同じ設定を読み込みます。

仕組み

1 つのパイプラインに 3 つのフロントエンドがあります。スキルは CLI を操作し、MCP サーバーは 同じコアを利用する 2 つ目のアダプターです。どちらにも独自の動作は含まれないため、 一方にある機能が他方にはない、ということはありません。

      agent skill  ·  CLI  ·  MCP server
                     ↓
 request → model resolution → capability check → provider client
                     ↓
                save to disk → result

              mediagen mark → AI content marking

各プロバイダーは、対応する機能を宣言する自己完結型のディレクトリです。 プロバイダーを追加する際、自身のフォルダーの外で変更するのは 1 行だけです。 プロバイダーのマニフェストはベンダー SDK をインポートしないため、doctor と config の実行時に SDK の読み込みによる負荷は発生しません。

src/
├── types/          leaf types everything shares
├── core/           pipeline, errors, capability checks, file handling
├── config/         the three configuration layers, key verification
├── providers/      one directory per provider, plus the registry
│   ├── gemini/
│   ├── openai/
│   ├── kie/
│   └── shared/     polling for asynchronous providers
├── cli/            the command tree; output.ts owns stdout
├── mcp/            the MCP server
└── marking/        AI content marking
skills/mediagen/    the agent skill
scripts/            catalogue generation, version syncing

コントリビューション

開発環境のセットアップ、プロバイダーの追加方法、リリースの作成方法については CONTRIBUTING.md を参照してください。