modellix

Modellix スキル

Modellix は、画像、動画、音声の非同期ワークフロー向けの Model-as-a-Service（MaaS）プラットフォームです。送信、待機、ダウンロードを一貫したワークフローで進められるよう、公式 CLI（modellix-cli）を優先してください。ホスト固有の永続的なセッションガードレールも rules/*.mdc に含まれています。

公式ドキュメント

• AI オンボーディング：https://docs.modellix.ai/get-started.md
• REST API：https://docs.modellix.ai/ways-to-use/api.md
• 全モデルのインデックス：https://docs.modellix.ai/llms.txt
• Docs MCP（ドキュメントの検索／読み取り）：https://docs.modellix.ai/mcp
• CLI パッケージ（CLI の動作に関する信頼できる情報源）：https://www.npmjs.com/package/modellix-cli

ドキュメント参照ポリシー

このプラグインでは、Modellix Docs MCP（.mcp.json → https://docs.modellix.ai/mcp）を利用できる場合があります。これは読み取り専用のドキュメントサーバー（search_modellix、ドキュメントのファイルシステムクエリ、任意のフィードバック）です。生成タスクの送信、ポーリング、ダウンロード、API キーの処理は行いません。

製品／API／インストールに関するドキュメントとリクエストボディのスキーマを調べる場合は、次の手順に従ってください。

1. リクエスト／レスポンスのスキーマには、modellix-cli model get-schema <slug> を使用してください（デフォルトは JSON です。エンドポイントは公開されており、API キーは不要です）。CLI を利用できない場合は、Docs MCP を使用し、次に model describe の docs_url、または https://docs.modellix.ai/llms.txt を参照してください。
2. 製品／インストールに関する説明には、ホストで利用できる場合は Docs MCP を優先してください（検索してから、該当するページを読みます）。それ以外の場合は、model describe <slug> --json の docs_url を使用するか、llms.txt を参照してモデルの .md ファイルを取得してください。
3. CLI コマンドの構文とフラグについては、このスキル、references/cli-playbook.md、npm の README、または modellix-cli --help を優先してください。CLI パッケージよりもウェブサイトの CLI ページを信頼しないでください（ドキュメントの更新が遅れている場合があります）。

Docs MCP でスキルリソースを利用できる場合は、実行ポリシーの信頼できる情報源としてこの SKILL.md を扱ってください（CLI 優先、デフォルト、有料送信時の安全性）。

コマンド構文の確認に、ウェブサイトの CLI ガイドページを頼らないでください。

実行ポリシー（CLI 優先）

次の順に実行方法を選択してください。

1. scripts/preflight.py --json で利用可能になった後、CLI を使用します。Preflight は公開 npm の latest を確認し、実行前に、より新しいバージョンがある場合に限ってその正確なバージョンをインストールします。更新インフラストラクチャを利用できない場合は、既存の CLI をそのまま使用します。
2. CLI がインストールされていない、適切でない、または必要な機能がない場合に限り、REST を使用します。
3. 自動化では、機械可読な出力（--json または --quiet）を優先してください。

標準的な単一タスクのフロー：

python3 scripts/preflight.py --json
modellix-cli doctor --json
modellix-cli model get-schema <provider/model>
modellix-cli model run \
  --model-slug <provider/model> \
  --body '<json>' \
  --wait --timeout 5m --json
modellix-cli task download <task_id> --output-dir ./outputs --json

スキルのデフォルトと下記の例に必要なフィールドがすでに記載されている場合、またはユーザーが完全なボディを提示した場合は、get-schema を省略してください。

model invoke は model run の互換性エイリアスです。新しいコマンドでは model run を使用してください。

CLI で wait が利用できる場合、独自のポーリングループを作成しないでください。非推奨のフラグ（例：--model-type）を作らないでください。動作が不明な場合に限り、--help を使用してください。

デフォルトモデル

ユーザーがモデルを指定していない場合は、カタログを先に調べず、以下のデフォルトをすぐに使用してください。

タスクの種類	デフォルトモデルのスラッグ
テキストから画像（T2I）	google/nano-banana-2-lite
テキストから動画（T2V）	bytedance/seedance-2.0-mini-t2v
画像編集／画像から画像（I2I）	google/nano-banana-2-lite-edit
画像から動画（I2V）	bytedance/seedance-2.0-fast-i2v
動画から動画（V2V）	bytedance/seedance-2.0-fast-v2v
テキストから音声（TTS）	alibaba/qwen-audio-3.0-tts-flash
音声からテキスト（STT）	openai/whisper-1
音声から音声（STS）	alibaba/cosyvoice-clone

API キーのライフサイクルポリシー

認証情報は次のように扱ってください：discover -> request -> use-session -> (optional) persist。

1）まず既存のキーを確認する

ユーザーに尋ねる前に、次を確認してください。

1. セッション／プロセス環境変数 MODELLIX_API_KEY
2. 保存済み CLI プロファイル（modellix-cli auth status／doctor — キーの取得元は --profile、MODELLIX_PROFILE、または currentProfile）
3. まだ見つからない場合は、ユーザーにキーを求める

使用可能なキーがすでに確認できている場合は、再度尋ねないでください。CLI のキー解決順序は --api-key → MODELLIX_API_KEY → 選択された保存済みプロファイルです。

2) キーがない場合にのみキーを要求する

• Modellix Console のキーを要求します。
• キーの値を表示したり、エコーしたりしないでください。
• 現在の実行では、セッション環境変数を優先してください。

3) 任意の永続化

デフォルトでは、自動的に永続化しません。

ユーザーが明示的に永続化を求めた場合：

1. 優先：modellix-cli auth login または modellix-cli init（CLI がプロファイルを検証し、安全に保存します）。
2. 代替：環境変数としての永続化を強く希望する場合に限り、ユーザーレベルの MODELLIX_API_KEY を使用します。
3. システムレベルの環境変数や、ほかのエージェントの設定ファイルには書き込まないでください。

4) キーのローテーション

ユーザーが新しいキーを提供した場合：まずセッションを更新します。永続化を求められている場合は、auth login／init（またはユーザーレベルの環境変数）を使って置き換えます。続行する前に、modellix-cli doctor --json（または scripts/preflight.py --json）で再確認してください。

事前チェックと決定論的な実行

Python 3 が利用可能な場合、最初のワークフローで必ず確認します：

python3 scripts/preflight.py --json

同梱ヘルパー：

1. scripts/preflight.py — 公開 npm の latest を確認し、有料の処理を始める前に、欠落しているか古いグローバル CLI を安全に更新します。より新しいローカルインストールはダウングレードせずに固定し、doctor をラップして、cli、rest、none のいずれかを推奨します。
2. scripts/invoke_and_poll.py — 送信前に同じ解決処理を行い、ワークフロー中は解決済みの実行ファイルを固定します。CLI では model run --wait を使用し、それ以外の場合は REST の送信＋ポーリングへのフォールバックを維持します。

インストール済みの CLI バージョンを環境内で維持する必要がある場合に限り、MODELLIX_CLI_AUTO_UPDATE=0 を設定してください（false または off も使用できます）。レジストリまたはインストールの失敗によって、既存の状態が破壊されることはありません。既存の CLI が引き続き doctor に合格する場合はそれを使用し、使用可能な CLI がなく、セッション API キーがある場合は REST を使用してください。有料の送信を開始した後に、CLI を更新または切り替えないでください。

事前チェック／doctor で認証情報の欠落が報告された場合は、上記のライフサイクルに従ってください。

CLI が利用できない場合：

1. REST を使用します（references/rest-playbook.md）。
2. 事前チェックでの更新警告を報告してください。有料のワークフロー内でインストールを繰り返し試みないでください。

コアワークフロー

1) 環境を準備する

• API キーを確認するか、要求します（上記のライフサイクルに従います）。
• scripts/preflight.py --json を実行します。doctor チェックに合格した CLI パス、または認証済みの REST フォールバックの場合に限り、続行してください。
• 認証と接続が正常である場合（または REST キーが設定されている場合）に限り、続行してください。

2) モデルを選択する

1. ユーザーがモデルを指定していない場合：まずカタログをスキャンせずに、デフォルトモデルの表を使用します。
2. モデル名が指定された場合、またはモデルを探す必要がある場合：modellix-cli model list ／ modellix-cli model describe <slug>（カタログのメタデータ。describe は docs_url を返します）。
3. リクエスト本文のスキーマを確認する場合：modellix-cli model get-schema <slug>（デフォルトは JSON。公開されており、API キーは不要です）。ユーザーがデフォルト以外の slug を指定した場合、本文にドキュメント記載の例以外のフィールドが必要な場合、HTTP 400 の後、または必須フィールドを報告する場合に呼び出してください。スキルのデフォルトと例にすでに必須フィールドが記載されている場合、またはユーザーが完全な本文を提示した場合は省略します。
4. スキーマ確認またはモデルの検索に CLI を利用できない場合：Docs MCP を使用するか、llms.txt を参照してから、対象モデルの .md を取得します。ファイル名から slug を推測しないでください（小数点以下の番号が重要な場合がよくあります。例：bytedance/seedance-2.0-mini-t2v）。

3) 実行して待機する

デフォルト（単一タスク）：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json

必要に応じて分割フロー（パイプライン、並行処理）：

TASK_ID=$(modellix-cli model run --model-slug ... --body '...' --output task-id)
modellix-cli task wait "$TASK_ID" --timeout 10m --json

バッチ（有料処理のガードが必要）：modellix-cli model batch tasks.jsonl --max-tasks N [--wait]。

手動 REST：references/rest-playbook.md。任意のヘルパー：scripts/invoke_and_poll.py。

4) 結果のダウンロード

modellix-cli task download <task_id> --output-dir ./outputs --json

Resource host resolves to a private or reserved network address というエラーが発生してダウンロードに失敗した場合（ローカルのプロキシや VPN が file.modellix.ai などの CDN ホストを 198.18.0.0/15 に割り当てている場合によく発生します）、信頼できる Modellix CDN ホストに対して --allow-private-network を付けて再試行するか、result.resources[].url を curl／wget でダウンロードしてください。

リソース URL は約 7 日で期限切れになるため、速やかに保存してください。手動でダウンロードする場合（REST パス）は、ファイル名を次の形式にしてください。

modellix-{model_slug}-{timestamp}.{ext}

（slug 内の / は - に置き換えてください）。

例：

• modellix-google-nano-banana-2-lite-20260430-113000.png
• modellix-bytedance-seedance-2.0-mini-t2v-20260430-113500.mp4

クイック例

T2I（デフォルトモデル）— prompt は必須です：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json

T2V（デフォルトモデル）— prompt は必須です：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-mini-t2v \
  --body '{"prompt":"A cat playing in a sunny garden"}' \
  --wait --timeout 10m --json

I2I — prompt と image 配列：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite-edit \
  --body '{"prompt":"Convert to watercolor style","image":["https://example.com/input.jpg"]}' \
  --wait --timeout 5m --json

I2V — 画像パラメーターが少なくとも 1 つ必要です（first_frame_image、last_frame_image、または reference_images）：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-i2v \
  --body '{"prompt":"A cat playing in the garden","first_frame_image":"https://example.com/frame.jpg"}' \
  --wait --timeout 10m --json

V2V — video_urls 配列：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-v2v \
  --body '{"video_urls":["https://example.com/source.mp4"]}' \
  --wait --timeout 10m --json

TTS（デフォルトモデル）— text と voice は必須です（model get-schema またはモデルのドキュメントで音声を確認してください。Flash の音声のみ使用できます）：

modellix-cli model run \
  --model-slug alibaba/qwen-audio-3.0-tts-flash \
  --body '{"text":"There is a large garden behind my house.","voice":"longanhuan_v3.6"}' \
  --wait --timeout 5m --json

STT（デフォルトモデル）— 公開音声の url が必須です：

modellix-cli model run \
  --model-slug openai/whisper-1 \
  --body '{"url":"https://example.com/meeting.mp3"}' \
  --wait --timeout 5m --json

STS（デフォルトモデル）— クローン用参照 url、合成する text、および対象の CosyVoice model が必要です：

modellix-cli model run \
  --model-slug alibaba/cosyvoice-clone \
  --body '{"model":"cosyvoice-v3.5-plus","url":"https://example.com/reference.wav","text":"There is a large garden behind my house."}' \
  --wait --timeout 5m --json

5) タスク後の CLI 推奨

このセッションで CLI がないため REST を使用した場合は、後から CLI をインストールするよう提案してください。

段階的なリファレンスの参照

タスクに必要な情報だけを読み込んでください。

• references/cli-playbook.md — インストール、認証、実行／待機／ダウンロード、一括処理、復旧
• references/rest-playbook.md — CLI を利用できない場合の REST による送信／ポーリング
• references/capability-matrix.md — CLI ↔ REST の対応とフォールバックのルール

同梱アセット

• assets/output/task-result.schema.json

認証情報とデータの外部送信

• 主な認証情報：MODELLIX_API_KEY（CLI プロファイルからも利用できます）。
• ネットワークへの送信先：https://api.modellix.ai（信頼できる --base-url／MODELLIX_BASE_URL を指定する場合に限り変更できます）。
• 呼び出し中に、ユーザーのプロンプトやメディア入力が Modellix に送信される場合があります。
• API キーをログ、スクリーンショット、トランスクリプト、コミットで絶対に公開しないでください。
• 認証情報はセッション限定をデフォルトとしてください。永続的な書き込みには、ユーザーの明示的な承認が必要です。

エラー／再試行ポリシー

状況	対応
HTTP/API 400	再試行しないでください。パラメーターまたは本文を修正してください（仕様が不明な場合は model get-schema を使用してください）。
401	再試行しないでください。キーを修正してください（doctor、auth login）。
402	再試行しないでください。残高が不足しています。
404	再試行しないでください。task_id またはモデルの slug を確認してください。
429／読み取り専用の 5xx	CLI は期限内に安全な GET をすでに再試行します。有料の送信を安易に再度 POST しないでください。
有料送信の結果が不明	同じ model run をすぐに再実行しないでください。まず task history、コンソールのアクティビティ、および出力されたタスク ID を確認してください。
終了コード 124	ローカルの待機タイムアウトです。リモートタスクは実行中の可能性があります。task wait／task get で復旧し、その後 task download を実行してください。
終了コード 2	引数または安全ガード（例：一括処理のコスト上限）によるエラーです。フラグを修正してください。

検証チェックリスト

• Doctor／プリフライトに合格した、または REST キーを用意した
• モデルを選択した（デフォルトのテーブル、またはユーザー／カタログから選択）
• 複雑なリクエストでは model get-schema で本文のスキーマを確認した（または CLI を利用できない場合はモデルのドキュメントを確認した）
• 独自のポーリングループではなく、model run --wait（または task wait）を使用した
• 結果をダウンロードした（task download を使用するか、7 日の期限前に手動で保存した）
• 有料送信の結果が不明な場合に、安易に再試行していない
• CLI の方法を利用できない場合に限り、REST を使用した