scenario

シナリオ

概要

Scenario は、500 以上のモデルとカスタムトレーニングを通じて、画像、動画、3D、音声を生成します。

セットアップ

• エンドポイント：https://mcp.scenario.com/mcp（Streamable HTTP）。OAuth を推奨します。認証情報が会話を通過しません。
• クライアント設定、ヘッドレスでの API キー設定、クライアントごとの再認証については、 references/setup.md を参照してください。
• エージェントにシークレットの収集、エンコード、エコーを依頼しないでください。
• 以前は認証済みだった接続が失敗する場合は、デバッグの前に再認証してください。 diagnostics_run はレイヤー（auth、tenant-scope、api-unreachable、healthy）を示します。

ツールは 2 種類あります。

• 直接ツール：以下のループに加え、asset_get、job_get、jobs_list、models_list があります。 ?toolsets=full を指定すると、すべてのツールが利用できます。
• カタログツール：その他（コレクション、タグ付け、分析、トレーニング、メンバー、キー）です。
  • scenario_tools_search が受け取るのは query（ツール名またはキーワード）と limit のみです。スキーマとレーンを返します。
  • scenario_tool_execute_read / write / delete は、{name, parameters} でツールを実行します。
  • すべての入力は parameters の中に指定します。スコープ ID と dry_run も同様です。ほぼすべてのカタログツールでスコープ ID が宣言されています。plan_generation が受け取るのは description のみです。
  • 直接ツールでは、スコープと、model_run の dry_run をトップレベルに指定します。
  • エグゼキューターは誤った場所に指定されたキーを黙って無視します。arguments は誤ったスコープエラーとして表面化し、トップレベルの dry_run はジョブを実行して課金されます。
  • レーンは動詞ではなく、結果自身の permission です。asset_download と asset_analyze は書き込みクラスです。

最初にスコープを指定

• まずスコープを解決し、その後、すべての呼び出しで team_id と project_id を渡します。
• teams_list はチームとそのプロジェクトを返します。projects_list には team_id が必要なため、最初には呼び出せません。
• 組み合わせをユーザーに確認してください。推測すると、他人のプロジェクトに書き込むことになります。無人で実行する場合は、タスクから組み合わせを取得してください。タスクに指定がない場合は、停止して選択肢を一覧表示します。
• サーバーがスコープを補完するのは、候補が 1 つある読み取り専用ツールのみです。それ以外の場合は、誤っている側を示して失敗します。
• 2 つ目のチームまたはプロジェクトが利用可能になると、スコープの指定漏れで失敗するケースがよくあります。

クイックリファレンス

手順	ツール	備考
スコープを解決する	teams_list、続いて projects_list	セッションごとに一度だけ実行します。すべての呼び出しで ID を渡します
モデルを探す	search または recommend	無料です。機能から探す場合は recommend、名前から探す場合は search を使います
スキーマを取得する	model_schema_get	model_run の前に必ず実行します。runs_as と上限を確認します
生成する	model_run	スキーマに準拠した parameters を指定します。コストの確認には dry_run を使います
待機する	jobs_wait	model_run がアセットなしで job_id を返すたびに使います。job_get をループで呼び出さないでください
表示／保存	asset_display / asset_download	アセットの生 URL を貼り付けないでください。format は画像とメッシュを変換します
アセットを調べる	asset_get	無料です。寸法、再生時間、firstFrame / lastFrame の ID を確認できます
入力をアップロードする	upload_asset + upload_asset_complete	ローカルファイルが asset_id になります
プロンプトを改善する	prompt_spark	提案として書き換えます。model_id が必要です
クォータ／デバッグ	usage、diagnostics_run	CU の消費量、diagnose MCP プロンプト
保存済みの設定	memory_recall	OAuth のみ。プロジェクトで生成する前と、切り替えた後に再度実行します

• 複数ステップのリクエスト（「ナレーション付きの商品動画」、「コンセプトから 3D へ」）：カタログの plan_generation（読み取りレーン）を使います。description に自然な言葉で記述すると、順序付きのステップが出力されます。各ステップにはツール名と任意のモデルヒントが含まれます。 実行は行いません。単一のステップの場合は recommend を使います。
• 明示された設定（「常に 9:16」）：カタログの memory_set（削除レーン）を使い、scope に project_user_memory（複数のプロジェクトにまたがる場合は user_memory）を指定します。レイヤー全体を置き換えるため、まず memory_get で取得して統合してください。

実例

スタイライズされたゲーム用小道具の画像を生成する：

1. モデルを見つけます：
   • 機能を指定する場合は、ユーザー自身の言葉をpromptとしてrecommendを使います。
   • 既知のモデル名を指定する場合は、target="models"、query="<model name>"、public=trueを指定してsearchを使います。キーワードで順位付けされ、filtersには機能を示すキーが含まれないため、機能を示す語句で検索すると、異なる出力タイプが最上位に表示されることがあります。
   • ユーザーが独自にトレーニングしたモデルの場合は、searchでpublicを省略します（非公開フラグはありません）。recommendにはinclude_private_models: trueを指定します。
   • チームごとに利用可能なモデルが異なるため、使用のたびにIDを再検索します。
2. 選んだモデルに対してmodel_schema_getを実行します。正確なフィールド名、型、必須フラグ、デフォルト値、上限を確認します。
   • プロンプトのmax_lengthなどの上限を超えると、切り詰められず400エラーになります。
   • ...Urlという名前でも、ファイルフィールドにはアセットIDを指定します。
   • cost_impact: trueは料金に影響するフィールドを示します。
3. スキーマにruns_as（"lora"または"composition"）が含まれる場合、そのモデルのIDをmodel_runに渡してはいけません。実際の呼び出し方法はrun_with.required_argumentsに記載されています。ここでのmodel_idはベースモデルであり、そのparameters（lorasまたはmodelIdの紐付け）は、同じスキーマに基づく入力とマージされます。required_argumentsだけを使うと、プロンプトが反映されません。
4. 任意：prompt_sparkを使うと、簡素なプロンプトをモデルに適した内容に書き換えられます。検出したID（ベースモデルではなく、LoRA自身のID）と下書きのpromptを渡します。意図的に作成したプロンプトは書き換えないでください。
5. model_idと、スキーマに準拠したparametersを指定してmodel_runを実行します。
   • ユーザーが料金を気にしないと言っている場合を除き、まずmodel_idと同じ階層にdry_run: trueを指定して料金を確認します。ジョブは作成されず、creativeUnitsCostにこのペイロードの正確な料金が示されます。
   • recommendの見積もりはデフォルト値を前提とします。実際の料金はcost_impactフィールドによって変わります。
   • 実行時：インラインアセット（status: success）は待機不要です。それ以外の場合はjob_idをjobs_waitに渡します。
   • 未完了のステータス：待機がタイムアウトした場合はin_progressです。wait=falseの場合はqueued、in-progress、またはwarming-upです。いずれもjobs_waitが必要です。
6. job_ids=[...]（最大32件）を指定してjobs_waitを実行します。
   • 完了した各行にはassetIdsとcuCostが含まれるため、後続のjob_getは不要です。
   • タイムアウト（in_progress）した場合は、pending_job_idsをjob_idsとして指定して再度呼び出します。再実行やキャンセルはしないでください。タイムアウト引数はありません。
   • xAIの生成がモデレーションによって停止された場合を除き、失敗したジョブの料金は返金されます。
7. asset_displayを使うと、アセットがインラインで表示されます。formatで表示形式を選択します。
   • display（デフォルト）：インライン画像、リンク、ビューアーデータを表示します。ホストのウィジェットは無効になりません。
   • viewer：インタラクティブウィジェットを表示するホスト向けの軽量なペイロードです。
   • json、markdown：メタデータとリンクを表示します。
8. asset_downloadはファイルURLを返します。アセットごとに1回呼び出し、curl -Lで保存します（リダイレクトされる場合があります）。
   • formatを指定すると、画像（png、webp、jpg）とメッシュ（glb、fbx、obj）を変換できます。GIFアニメーションはgifならアニメーションのままですが、デフォルトのpngでは1フレームに変換されます。動画と音声ではformatを省略してください。指定すると400 Invalid target formatエラーになります。
   • MCP呼び出しは成功するのに、curlでhost_not_allowedまたはCONNECT tunnel failed, response 403が発生する場合は、ホストの送信ネットワークポリシーが原因と考えられます。CDNの403だけでは判断できません。まず新しいURLを取得してください。
   • Sandbox network accessに設定名が記載されています。一部のホストでは、ユーザーが変更できない組織の許可リストになっています。
   • その間は、asset_displayのapp_urlをユーザーに渡してください。ユーザーはそこでダウンロードでき、メッシュの場合はasset_downloadで提供されていないエクスポート形式を選択できます。
   • 署名付きURLには有効期限があります。これは最後の手段であり、納品物として使わないでください。

ローカルの入力ファイルは、upload_assetでアップロードします。

• file_name、content_type、kind（image、audio、video、3d）は常に指定し、さらに file_size または data のどちらか一方だけを指定します。どちらも指定しないと、Either 'file_size' … or 'data' is required というエラーになります。
• file_size を優先してください。これはディスクから読み取った正確なバイト数で、data は省略します。応答には署名付きパート URL と instructions が含まれます。
• 各パートの生バイト列を、追加ヘッダーを付けずに URL へ PUT します。チェックサムヘッダーを付けると、ストアから 403 が返されます。すべての PUT が 200 を返したことを確認してから、upload_id を指定して upload_asset_complete を呼び出します。
• インラインの base64 data は 100KB 未満の場合に限り、シェルからパートを PUT できないときだけ使用します。この方法ではアセットが直接返され、完了処理は不要です。サイズが上限を超えるファイルは、上限を示すエラーとともに拒否されます。
• どちらの呼び出しでも指定するのはスコープのみで、それ以外は不要です。パート一覧や etag は指定しません。
• インラインの data は upload_asset 内部でデコードされます。そこでデコードエラー（libpng read error、Corrupt JPEG data、unable to read pixels）が発生した場合、ファイルではなく base64 文字列が破損しています。
  • エージェントが data の文字を一つずつ入力し直したところ、57K 文字の文字列がその方法で破損しました。
  • 再送しても同じエラーが繰り返されます。シェルを使える場合は、ユーザーがインラインを希望していても file_size の方法に切り替え、その理由を伝えてください。
• file_size の方法では、サーバーが完了時にデコードします。Upload upl_… failed: に続いて Corrupt JPEG data、premature end of data segment、bad Huffman code、libpng read error のいずれかが表示された場合、デコードできていません。
  • ソースの破損、本文の切り詰めや再エンコード、パートの欠落、file_size の誤りがないか確認してください。
  • ローカルファイルが指定したコンテンツタイプで開けることを確認してから、新しい upload_asset を開始し、生バイト列を PUT してください。同じ upload_id で完了処理を再試行しないでください。
• スマートフォンの HEIC 写真はそのままアップロードします（content_type: "image/heic"）。変換しないでください。Unhandled image format には kind: "image" で受け付けられる形式が列挙されます。それ以外の形式はローカルで変換してください。
• シェルを使えないホストからはパートを PUT できません。ユーザーが app.scenario.com でアップロードし、エージェントはアセット ID を使って処理を続けます。

ファイリングは後片付けではなく、納品の一部です。

• collection_create で指定できるのは名前とスコープのペアのみです。そこで送信した asset_ids は黙って無視されるため、アセットの追加には必ず別の呼び出しが必要です。collection_id と asset_ids を指定して collection_add_assets を呼び出してください。
• ID は任意の数を受け付け、49 件ずつに分割して処理し、重複はスキップします。結果では already_present_asset_ids と added_asset_ids が分けて返されます。
• 失敗した後は、一覧全体を安全に再送できます。エラーには追加済みの件数が含まれ、再試行で残りが追加されます。
• その応答をもとに確認してください。新規書き込み直後は、search の filters={"collection_ids": [...]} にはまだ反映されません。
• asset_add_tags はタグを追加するもので、1 回につき asset_id は 1 件です。アセットにすでに付いているタグを送ると 400 Duplicated tag が返されるため、先に assets_get_bulk で tags を読み取り、不足しているものだけを送信してください。

再利用可能なテンプレートと参照コンテンツでは、共通アセットのライフサイクルに従ってください。既存アセットを解決し、新しいバージョンをステージングし、サポートされている操作でのみ公開してから、公開 ID を記録する前にパブリックアクセスを確認します。アップロードとファイリングだけでは公開されません。

エラーと復旧

• context_missing：何も解決されませんでした。必要に応じて teams_list、projects_list を実行します。
• context_ambiguous：複数の候補が該当します。選択肢を提示し、ユーザーに選んでもらいます（無人実行の場合：タスクでペアが指定されていればそのペアを使用し、指定されていなければ停止して一覧を提示します）。
• 403 Forbidden：通常はスコープが間違っており、見つからないわけではありません。ID のペアを再確認します。プライベートアセットの入力は、それ自身のプロジェクトからのみ読み取れます。
  • どのプロジェクトにあるか尋ねます（無人実行の場合：タスクで指定されていれば使用し、指定されていなければ停止します）。
  • カタログの asset_copy（書き込みレーン）を、そのプロジェクトを project_id として、さらに asset_id と target_project_id を指定して実行します。
  • 返された ID を使用します。asset_copy でコピーできるのは、同じチーム内のプロジェクト間のみです。
• プラン名を示す 403：アップグレードまたはモデルの切り替えを案内します。再試行しても解消されません。recommend は、応答でプランによる制限が _degraded と示されている場合を除き、これらを requires_plan_upgrade として事前に警告します（この場合は実行しません）。その場合は、この項目が代替の対応策となります。
• details.actionName が parallel-custom-jobs の 429：チームごとの生成並列数の上限です。同時実行するジョブは actionLimit 件以下に保ちます。wait=false で起動し、次のジョブを起動する前に jobs_wait でジョブを完了させます。すぐに再試行すると、同じエラーが繰り返されます。
• custom-generation の 429、またはクォータ、残高、シート数の上限を示す 429：
  • actionLimit は期間内の CU 上限（Free：1 日あたり 50）、actionValue はすでに消費した量です。必要な料金が残量を超える実行は拒否されるため、actionValue が少ない場合はクレジット切れではなく、このペイロードのコストが高すぎることを意味します。
  • バッチを停止し、ペイロードを dry_run して、より安価なメンバーまたは出力数を減らす案を提示するか、リセットまたはアップグレードについて報告します（無人実行の場合：報告して停止します）。
  • usage には、同じ project_id（または scope: "team"）を指定します。
  • ユーザーごとの上限についてはチーム管理者に連絡してください。シート数の上限エラーによって、アップロードもブロックされることがあります。請求情報やメンバーシップは自分で変更しないでください。
• 429 Too Many Requests. Please, wait N seconds（remainingSeconds）：リラックスモードです。プランの CU を使い切っているため、ジョブを実行するたびに待機が発生します。
  • 待機時間はペイロードのコストに応じて変わります。高負荷のジョブ（高いエフォートティア、長い動画など）は、より安価なジョブが実行できる状態でもロックされたままになることがあります。remainingSeconds の間は、同じペイロードを再送信しないでください。
  • チームメンバーの誰かがジョブを実行すると、チームの待機時間がリセットされます。また、チームが生成を続けると待機時間が長くなるため、バッチの処理は遅くなります。拒否された試行に料金はかかりません。
  • この拒否からリラックスモードを検出します。usage が報告するのは消費量であり、残りの CU ではありません。待機時間の確認方法がどのツールにも記載されていない場合は、不明であると伝えます。
  • バッチを停止します。CU の追加購入（リラックスモードを即座に終了します）またはアップグレードを提案します。それ以外の場合は、より安価なペイロード（先に dry_run します）、出力数を減らす案、または後で再実行する案を提示します（無人実行の場合：報告して停止し、再起動はしません）。
  • ルールとプランの上限： リラックスモード。
• その他の 429（不明な actionName を含む）：名前から動作を推測してはいけません。エラーを報告し、復旧方法を選ぶ前に同じスコープで diagnostics_run を実行します。
• model_run でのトランスポートエラー（HTTP ステータスなし）：リクエストが受け付けられている可能性があります。再実行する前に jobs_list を実行してください。応答が失われると二重請求になります。dry_run はジョブを作成せず、常に安全に再試行できます。
• 400 Cannot cancel this type of job：起動済みのジョブには料金が発生します。job_cancel はほとんどの生成ジョブを拒否するため、中断手段がない前提でバッチを計画してください。
• asset_get の 404：その ID は存在せず、再試行しても表示されることはありません。jobs_wait または job_get の行から assetIds を再読み込みしてください。推測した ID や入力ミスが通常の原因です。
• 400 At least one of query, filter, image, or images must be provided：search は条件なしでは一覧を表示しません。新しい順にアセットを一覧表示するには、target="assets"、filter="createdAt EXISTS"、sort_by=["createdAt:desc"] を指定します。
• recommend のクライアント側タイムアウト：ライブデータを使って順位付けするため、通常は 30 秒、場合によっては 1 分以上かかります。待つか再度呼び出してください。機能の代替として search を使ってはいけません。

よくある間違い

• プレースホルダー ID（asset_placeholder）で後続ステップの料金を見積もる：料金見積もりの前にファイル ID が解決されるため、dry_run は 404 を返し、料金を見積もりません。recommend で見積もり、実際のアセットが存在してから dry_run を実行してください。
• スキーマで array: true と指定されているのに、値を単独で渡す：黙って破棄されるため、実行時に参照画像や LoRA が無視されます。出力に対する asset_get には、実行で使用された内容（metadata.referenceImages、parentId）が表示されます。これが最も手軽な確認方法です。
• recommend の ranked[0] を何も考えずに選ぶ。まず next_step.type を確認してください。
  • no_match：ranked に部分的な候補があっても、生成を中止してください。unmet_requirements と suggested_action を説明し、要件を黙って緩和しないでください。スキーマチェックや dry_run の成功によって no_match が覆ることはありません。
  • ask_user：選択肢を提示してください。ユーザーの選択を優先します（無人実行の場合はタスクを優先し、それ以外は proceed を選びます）。
  • proceed：specialty.model_id を優先し、それがなければ caveats、tradeoff、または explanation に非推奨と記載されていない最初の ranked エントリーを選んでください。ランキングが示すのは性能であり、ライフサイクルではありません。
• 手がかりなしにデバッグする：diagnose MCP プロンプトはトレース ID を返します。また、失敗した呼び出しのスコープペアと、確認された mcpt_ ID を observed_trace_ids として指定した diagnostics_run もトレース ID を返します。
• ファイルフィールドの名前を推測する：400 Input image is required（または referenceImages、startImage、frontImage、video。各モデルで名前が異なります）は、ペイロードにスキーマの required フィールドがないことを示します。フィールド名をそのままコピーしてください。ここに URL を指定すると、値がないものとして扱われます。ファイルフィールドにはアセット ID のみを指定してください。
• 画像フィールドに動画、音声、または 3D アセットを渡す：400 Unhandled image format には、受け付けられるタイプが表示されます。asset_get でアセットの mimeType を確認し、モデルが画像を要求する場合は、クリップの firstFrame を使って静止画を取得してください。
• target="models" を指定した search で filters.kind を使う：kind はアセットを説明するフィールドであるため、400 "kind" is not a filterable field が返されます。filters.type（アーキテクチャ）または tags でモデルを絞り込むか、recommend で機能を指定してください。
• privacy: "public" を指定せずに models_list を type で絞り込む：その旨を示す 400 が返されます。プライベートな一覧では status または modality で絞り込むか、search を使用してください（デフォルトはプライベートです）。