scenario-image

シナリオ画像の生成と編集

概要

Scenario は数百種類の画像モデルを実行します。モデルは、プロンプトから生成する txt2img と、編集、スタイル変更、インペインティング、アップスケーリングを行う img2img に分かれています。基本的な手順は、scenario スキルで説明しているループです。画像生成で問題が起きる原因は、モデルごとの仕様です。同じ処理を行う2つのモデルでも、サイズ指定フィールド、プロンプトの上限、参照画像の上限が異なるため、毎回 model_schema_get を確認してください。モデルファミリーごとの仕様（サイズ指定ファミリー、参照画像の上限、編集モード）については、scenario-seedream、scenario-gpt-image、scenario-gemini-image、scenario-ideogram、scenario-reve、scenario-luma-image、scenario-mai-image、scenario-grok-imagine-image を参照してください。アップスケーリング、グレーディング、エフェクト、拡張、リサイズ、その他のツールモデルについては、scenario-image-editing を参照してください。一連の画像で同じ見た目を保つ方法については、scenario-consistency を参照してください。それぞれに役割を持つ複数の参照画像から1枚の画像を作る方法については、scenario-multi-reference を参照してください。スプライト、アイコン、タイルセットについては、scenario-game-assets を参照してください。ここに記載された関連スキルが利用可能なスキルに見つからない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。ユーザーが不在の場合は、ツールスキーマに基づいて作業を進め、不足しているスキルがあることを明示してください。

クイックリファレンス

必要な操作	呼び出し方法
モデルを選ぶ	recommend で capability="txt2img" または "img2img" を指定するか、search（target="models"、public=true）を使用します
仕様を確認する	model_run の前に毎回 model_schema_get を呼び出します
コストを見積もる	model_run で dry_run=true を指定します。cost_impact: true は価格に影響するフィールドを示します
生成または編集する	model_run を実行してから jobs_wait を呼び出します
確認して保存する	asset_display の後に asset_download を呼び出します（既定は png、ほかに webp、jpg）
ピクセル寸法を正確に合わせる	到達可能な最も近いサイズで生成してから、model_scenario-resize-image を実行します（「正確なサイズに仕上げる」を参照）

インペインティングとアウトペインティングは img2img であり、独立した機能ではありません。

実行失敗につながる3つのフィールド

これら3つのフィールドはいずれもモデルごとに異なるため、以前の実行結果ではなくスキーマから値を取得してください。

• サイズ。 サイズ指定に共通の形式はありません。min、max、および指定可能な刻み幅を持つ数値の width と height、メガピクセルまたはK単位の解像度を指定する列挙型の aspectRatio、複数の解像度とピクセル寸法を組み合わせた size、あるいはアスペクト比のみの場合があります。アスペクト比のみでは、ピクセル寸法を正確に指定することはできません。列挙型フィールドにピクセル値を渡した場合や、指定可能な刻み幅に合わない値を指定した場合は拒否されます。スキーマで希望するサイズを指定できない場合は、黙って丸めず、指定可能な範囲を伝えてください。
• プロンプトの長さ。 プロンプトフィールドの max_length は、約2000文字から32000文字までさまざまです。あるモデルでは収まるプロンプトでも、次のモデルでは400エラーになります。
• 参照画像。 名前（referenceImages、image）、上限数、多重度はすべてスキーマで確認してください。フィールド名だけでは、どれも判別できません。モデルによっては、referenceImages という名前でも単一のファイルを受け取るスカラーフィールドです。スキーマに array: true と記載されている場合に限って配列を渡してください。また、その場合はアセットが1つだけでも配列にしてください。文字列をそのまま渡すと黙って無視されるため、参照画像が使われないまま処理が成功してしまいます。参照画像が複数ある場合は、プロンプトでそれぞれがどの画像かを説明してください。

バッチ数フィールド（numOutputs、numImages）は、同じプロンプトを繰り返すため、バリエーションが生成されます。ひとつのセットになるわけではありません。項目ごとに異なる内容が必要な場合は、項目ごとに model_run を1回実行してください。

正確なサイズに仕上げる

ゲーム内の配置では、正確なピクセル数（210x600のバナー、256x256のアイコン）が必要ですが、生成モデルが直接対応できない場合があります。数値サイズのフィールドはグリッド単位で調整されます（step は16が一般的で、min と max が範囲を制限します）。列挙型フィールドでは固定の段階が用意されており、指定した下限を下回るリクエストをエラーなしで黙って置き換えるメンバーもあります。あるメンバーでは、512x128を指定したところ、エラーもなく1408x480が返されました。指定サイズに対応していない場合は、到達可能な範囲で目標サイズ以上の最小サイズを生成し、可能な限り比率を合わせ、すべてのスキーマ制限を守ってください（1Kが下限のメンバーで256x256のアイコンを作るなら1024x1024、210x600のバナーを作るなら、そのメンバーの制限を両方の寸法が満たす場合に限り224x640）。その後、model_scenario-resize-image を使って仕上げます。これはScenarioの唯一の決定論的な正確な寸法へのリサイズツールであり、発見しても再導出するだけなので、固定IDです。アセットが1つだけでも images は配列で指定し、width と height を設定します。fit は、ボックスを埋めてはみ出した部分を中央で切り抜く cover、または歪みを許容して正確な寸法にする stretch を指定します（デフォルトの contain では、ボックスより小さい画像が返されることがあります）。より大きなソースを選ぶのは、明示的な品質要件や文書化されたモデルの指針がある場合に限り、モデルファミリーに最適なサイズだと推測して選ばないでください。asset_get で確認します。縮小すると柔らかさが目立ちにくくなることがありますが、拡大しても失われたディテールは復元できません。

ぼやけについても同じ注意が必要です。複数のメンバーでは、スキーマ上でより高い段階が用意されているにもかかわらず、デフォルトで1Kの段階が使われます。そのため、新規生成では解像度または quality の段階を明示的に設定してください。承認済みのフレームを維持するには、確定した画像をそのままアップスケールします（scenario-image-editing）。レシピを再実行すると、画像が変わることがあります。カスタム学習済みのメンバーでは、ステップ数を増やす前に、スキーマとモデルの指針を確認してください。出力が指示どおりすぎると感じる場合は、固定する要素とモデルに考案させる要素を分けて、その旨を伝えてください。考案されるディテールも固定制約を守る必要があります（テキストなしの指示に装飾的なルーンを加えてはいけません）。実行前に prompt_spark を使えば、簡潔な指示をモデルに適したプロンプトに拡張できます。

プロンプトの表現

画像内のテキストについては、文字列を一つずつ正確に引用し、配置も指定します（「ラベルには『NORTH』と表示し、上部中央に配置」）。短い文字列を数個にとどめ、綴りが崩れ続ける単語は一文字ずつ指定します（NORTH：N、O、R、T、H）。引用符で囲んでいない文言は言い換えられます。一字一句正確でなければならない文言（価格や法的表記）はプロンプトで指示せず、scenario-text-overlay で合成してください。フィルムスチルやシネマティックなプロンプト、または文章で比率を指定した表現（2.39:1）は、ピクセルにレターボックスの黒帯が焼き込まれることがあります。asset_get で寸法を確認すると、黒帯も画像として判定されます。端から端まで画面全体を使い、レターボックスや黒帯を入れないよう指示し、比率はサイズ指定フィールドだけに記載してください。肌が見える場合は、見える毛穴や産毛、ほのかなハイライトなど、肌の質感を指定してください。そうしないと、肌が滑らかにレタッチされた状態で返されがちです。

編集の指示では、変更内容を指定し、それ以外を維持するよう明記します。「椅子を日当たりのよいテラスに置き、形、布地、影はそのまま正確に保つ」や、テキストの場合は「見出しだけを『NORTH』に変更し、書体、サイズ、位置は同じにする」といった具合です。明記していない要素は変更される可能性があります。

実践例：商品画像のラベルを差し替える

1. recommendをcapability="img2img"と、ユーザー自身の言葉を使ったpromptで呼び出します。next_stepはscenarioスキルの指示に従って処理し、requires_plan_upgradeの項目は決して実行しないでください。
2. 商品写真をupload_assetでアップロードし、続けてupload_asset_completeを呼び出します。これによりasset_idが返されます。約100KB未満のインラインパスでは、2つ目の呼び出しを省略できます。
3. 選んだモデルに対してmodel_schema_getを呼び出し、参照フィールドの名前と上限、使用するサイズ設定の系統、プロンプトのmax_length、およびmaskフィールドの有無を確認します。
4. マスクを使って編集する場合は、作成に取りかかる前にmaskフィールド自体の説明を読みます。マスクは互換性がありません。ソース画像と正確に同じ寸法のアルファチャンネルを必要とするモデルもあれば、モデル側でリサイズする白黒画像を必要とするモデルもあり、どのピクセルが塗りつぶされるかも異なります。マスクを用意していない場合は、ユーザー自身の言葉でマスキングの要望を伝えて、capability="img2img"でrecommendを呼び出すと、短い名詞句やボックスを受け取り、オブジェクトごとに1つのマスクを返すセグメンテーションモデルを見つけられます。カタログ内のセグメンテーションモデルの大半は、代わりに3Dメッシュをセグメント化するため、選んだモデルのcapabilitiesを確認してください。どの方式も適合しない場合は、指示エディターで編集範囲を文章で指定します。
5. スキーマに記載されたフィールド名を使ってmodel_runを呼び出します。プロンプト、参照（スキーマにarray: trueとある場合に限り配列でラップします）、および指定されたマスクとサイズ設定のフィールドを渡します。コストが気になる場合は、最初にdry_run=trueを使ってください。
6. jobs_waitを呼び出します。約180秒のタイムアウトはエラーではないため、返されたpending_job_idsをjob_idsとして指定し、再度呼び出してください。その後、asset_displayで確認し、asset_downloadで保存します。

よくある間違い

• スキーマで参照フィールドにarray: trueと指定されているのに、単なる文字列を渡すこと：エラーなしで破棄され、出力では参照が静かに無視されます。
• あるモデルのパラメータブロックを別のモデルで再利用すること：aspectRatioとwidth／heightが共存することはほとんどなく、未知のフィールドは拒否されます。
• 403のModelAccessRestrictedErrorを再試行すること：modelIdとrequiredPlanが示されるので、アップグレードを案内するか、別のモデルを選んでください。
• 「背景を透明に」とプロンプトで指定すること：拡散モデルの出力は不透明です。スキーマにbackgroundフィールドがあればそれを使い、なければ後から背景削除モデルを実行してください。
• 承認済みの画像をより高いサイズ階層で再実行すれば、より鮮明になると思い込むこと：多くのモデルにはseedがなく、存在する場合でも、ほかのすべてのフィールドを変更せずに実行した場合に限り同じ結果を再現するため、再実行では新しい画像になります。最も安価な階層で下書きを作成し、気に入った画像そのものをアップスケールしてください（scenario-image-editing）。
• モデルが指定したピクセルサイズで出力できると思い込むこと：アスペクト比しか指定できないモデルもあれば、下限を下回るサイズを黙って別のサイズに置き換えるモデルもあります。近いサイズで生成してからリサイズし（正確なサイズに仕上げる）、実際の出力をasset_getで確認してください。asset_getはproperties.widthとproperties.heightを報告します。jobs_waitが返すのはアセットIDのみです。