layer

Layer

概要

Layer は、モデルに依存しない単一のリクエスト形式で、画像、動画、3D メッシュ、音声を生成します。作業料金は Creative Units（CU）で算出され、ワークスペースに請求されます。このセットに含まれるほかのスキルはすべて、以下の一連の流れを前提として、その上で必要な技術を説明します。つまり、プロンプトに何を含めるか、タスクに実際に必要な機能フィルターはどれか、そして生成しただけでなく、出力を実用可能にするには何が必要かを解説します。

クライアントの接続、認証、およびこれらすべてに相当する REST の操作については、Layer が公開している layer-connect-mcp と layer-generate-assets のスキルで説明しています。サーバーは、ストリーミング可能な HTTP と OAuth に対応した https://mcp.app.layer.ai/mcp です。セッションごとに、最初の生成の前に get_instructions を一度呼び出し、最初の Forge 実行の前に get_forge_instructions を呼び出してください。

生成方法は 2 つあります。Forge は 1 つのモデルを直接実行し、すべてのパラメーターを制御できます。こちらがデフォルトです。Workflows は、スタジオがあらかじめ構築した複数ステップの Blueprint パイプラインを実行します。ユーザーがそのワークフローを指定した場合や、タスクに適した再利用可能なパイプラインがある場合に選択してください。詳細は layer-workflows を参照してください。

クイックリファレンス

ステップ	ツール	重要な点
対象指定	list_workspaces	ほとんどのツールでは workspace_id が必要です。ユーザーが複数のワークスペースを持っている場合はどれを使うか尋ねるか、最後にアクティブだったものを選びます。
選択	list_base_models	filter.use_case を渡し、最初の結果を選びます。デフォルトの sort は Layer が選定した順序です。
確認	get_base_model	モデルごとの仕様です。モデルによっては、プロンプトにトリガーワードが必要です。
アップロード	request_file_upload_url / upload_file	生成前に行います。生成後ではありません。
料金	estimate_forge_price	無料です。料金と生成後の残高をまとめて返します。
実行	execute_forge	inference_id と poll_interval_seconds を返します。
ポーリング	get_forge_run	返された間隔で実行します。通常は 10s です。

モデルの選択

base_model_id をハードコードしないでください。カタログはワークスペースごとに異なり、内容も変わるため、ここで使える ID も別の環境では MODEL_NOT_FOUND になります。毎回、一覧から探してください。

filter.use_case は主要なフィルターで、タスクの種類を指定します。text_to_image、image_editing、inpainting、reframing、multi_angle、split_into_layers、upscaling、background_removal、vectorization、text_to_video、image_to_video、video_editing、video_extend、text_to_3d、image_to_3d、remesh、retexture、rig、animate、segment、text_to_speech、sound_effects、music があります。

タスクで本当に必要な機能に限り、filter.capabilities で絞り込みます。これは名前のリストではなく、真偽値を持つオブジェクトです。例：filter.capabilities: {tileability: true}。必要なものだけを設定し、ほかは省略してください。false もフィルターであり、デフォルト値ではないためです。指定できるフィールドには、tileability、inpainting、outpainting、negative_prompt、image_editing、generate_audio、lipsync、loop、fixed_duration、music、instrumental、sound_effect、character_pose、structure、outline、square、portrait_9_16、landscape_16_9、multiple_aspect_ratios があります。filter.max_price で支出を制限できます。フィルターの結果がない場合は条件が厳しすぎます。モデルをでっち上げるのではなく、条件を緩めてください。

クリエイティブユニットの消費

実行する前に、毎回見積もりを取得してください。見積もりは無料で、料金、実行後の残高、実行に使われるモデル（auto_picked かどうかを含む）が表示されます。

20 CU を超える場合は、ユーザーに確認して明示的な承諾を待ってください。 サーバーはこのしきい値を示しており、変更できないことも明示しています。そのため、しきい値を引き上げたり、ユーザーがセッション中に引き上げることを許可したりしないでください。実行内容、支払い元のワークスペース、残高に対する料金を、短い表にして提示してください。

確認の要否は実行ごとに判断します。見積もりは実行1回分の料金を示すためです。4フレームのサイクルや6アイコンのセットなど、タスクが複数回の実行を予定している場合は、最初の実行を見積もり、開始前にシーケンス全体の合計額を提示してください。そうすれば、4回確認を求めたり、さらに悪いことに各実行がしきい値未満だったため確認を一度も求めなかったりすることなく、ユーザーはまとめて支出に同意できます。

allow_negative_balance が有効なワークスペースもあります。これは実行がブロックされないという意味です。実行が無料になるという意味ではなく、確認を省略するための余裕でもありません。

使用例

ユーザーが手描き風のアイソメトリック建物スプライトを4つ欲しがっています。

1. list_workspaces を実行し、ワークスペース ID を取得します。
2. filter.use_case: "text_to_image" を指定して list_base_models を実行します。最初の結果を使います。
3. そのモデルに対して get_base_model を実行し、トリガーワードが必要か、どのアスペクト比に対応しているかを確認します。
4. base_model_id、プロンプト、batch_size: 4 を指定して estimate_forge_price を実行します。残高 900 CUs に対して 7 CUs と返されるため、しきい値未満であり、確認は不要です。
5. 同じ引数に session_name を加えて execute_forge を実行します。これにより、4つのスプライトが Layer アプリ内でまとめられます。
6. 返された inference_id を使って、COMPLETE になるまで poll_interval_seconds ごとに get_forge_run を実行し、その後アセットの URL を提示します。

batch_size は 1～16 で、デフォルトは 4 です。1つのプロンプトのバリエーションが生成されます。異なるスプライトを4つ生成するには、4つのプロンプトが必要です。つまり、4回の実行であり、バッチサイズ 4 の実行1回ではありません。

ファイル

ローカルのバイトデータには request_file_upload_url を使います。2段階の再開可能なアップロード用の署名付き URL と file_id が返されます。upload_file は、ファイルがすでに公開 HTTP(S) URL 上にある場合にのみ使います。正しいタイプを指定して、guidance_files に file_id の値を渡してください。タイプは init_image、reference_image、pose、depth、canny、lineart、scribble、face、first_frame、last_frame、init_video、reference_video、init_audio、reference_audio、init_mesh、texture_image です。

完了した実行の出力アセットには、すでに file_id が付いています。それをそのまま次の実行に渡してください。生成済みアセットを再アップロードするのは、必ず誤りです。

トレーニング済みスタイル

list_reference_sets は、ワークスペースのトレーニング済みスタイルを返します。reference_sets: [{set_id, weight}] として渡してください。最大10個まで指定でき、重みの範囲は0～2、デフォルトは1.0です。リファレンスセットを指定し、base_model_id を指定しない場合、サーバーはそれらを適用できるモデルを選びます。通常はこれが望ましい動作です。キュレーション済みのランキングはリファレンスセットへの適合度ではなく、タスクへの適合度に基づいています。layer-reference-sets を参照してください。

劣化は通知なく発生します。reference_sets_degraded と reference_sets_warning は、見積もり、実行、ポーリングの各応答に含まれます。劣化した実行も成功し、CUs も消費します。セットが適用されなかった場合は、そのセットと理由を伝えてください。劣化したセットを適用済みとして報告してはいけません。

ルーティング

ユーザーの要望	スキル
静止画、または意図どおりにならないプロンプト	layer-image
手持ちの画像を変更したい	layer-image-editing
動画、または特定の動きをさせる必要があるショット	layer-video
メッシュ、リグ、またはアニメーション	layer-3d
音楽、効果音、または音声	layer-audio
キャラクター、環境、アイコン、またはゲーム UI	layer-game-assets
ピクセルアート、スプライトシート、または歩行サイクル	layer-pixel-art
継ぎ目なく繰り返せるテクスチャ	layer-textures
一連の素材全体で統一した見た目、または学習済みのスタイル	layer-reference-sets
保存済みの複数ステップのパイプライン	layer-workflows
1 本の完成動画につなぎ合わせたクリップ	layer-video-timeline
制作に着手する前の方向性、ムードボード、またはストーリーボード	layer-art-direction
納品前に一連の生成物を評価したい	layer-quality

ここに記載されている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add layerai/skills --skill <name>）。無人で処理を続ける場合は、ツールスキーマに基づいて進め、不足していることを明示してください。

よくある間違い

• base_model_id を確認せず、記憶に頼って断定する。
• 見積もりなしで実行する、または明示的な承認を得ずに 20 CU を超えて使用する。
• poll_interval_seconds の代わりに固定時間のスリープを使う。
• batch_size を、1 回の実行で N 個の異なる素材を生成する方法として扱う。
• 劣化したリファレンスセットを適用済みとして報告する。
• すでに file_id がある素材を再アップロードする。
• allow_negative_balance を、支出ゲートを省略してよいという意味に解釈する。

エラー

UNAUTHENTICATED は OAuth フローが完了していないことを意味するため、ユーザーに MCP クライアントの設定を開くよう案内してください。MODEL_NOT_FOUND は、再び推測するのではなく list_base_models で再検出する必要があることを意味します。INSUFFICIENT_BALANCE は、クレジットを購入するために Layer アプリを案内してください。RATE_LIMITED は同時実行数が多すぎることを意味するため、待機するか、cancel_inference で実行を 1 つキャンセルしてください。FEATURE_DISABLED はワークスペースでその機能が利用できないことを意味するため、有効化方法を推測せず、アプリ内サポートを案内してください。