Scenario Image Generation and Editing

Overview

Scenario runs hundreds of image models, split across txt2img (generate from a prompt) and img2img (edit, restyle, inpaint, upscale). The loop is the one the scenario skill teaches. What breaks image runs is the per-model contract: sizing fields, prompt limits, and reference caps differ between two models that do the same job, so read model_schema_get every time. Per-family contracts (sizing families, reference caps, edit modes): scenario-seedream, scenario-gpt-image, scenario-gemini-image, scenario-ideogram, scenario-reve, scenario-luma-image, scenario-mai-image, scenario-grok-imagine-image. Upscaling, grading, effects, expand, resize and the other tool models: see scenario-image-editing. Holding one look across a set: see scenario-consistency. One image from several references, each with one job: scenario-multi-reference. Sprites, icons, and tilesets: see scenario-game-assets. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Quick reference

Need	Call
Pick a model	recommend with capability="txt2img" or "img2img", or search (target="models", public=true)
Read the contract	model_schema_get, before every model_run
Estimate cost	model_run with dry_run=true; cost_impact: true marks the fields that move price
Generate or edit	model_run, then jobs_wait
Review and save	asset_display, then asset_download (png default, webp, jpg)
Land exact pixels	Generate at the nearest reachable size, then model_scenario-resize-image (see Landing an exact size)

Inpainting and outpainting are img2img, not capabilities of their own.

The three fields that fail runs

All three are per-model, so take them from the schema rather than from a previous run:

• Size. Sizing has no common shape: numeric width and height with min, max, and a step to land on; an enum (aspectRatio, a resolution in megapixels or K tiers, a size mixing tiers with pixel pairs); or an aspect ratio alone, which puts an exact pixel target out of reach entirely. Pixels sent to an enum field, or an off-step value, are rejected. When the schema cannot express the size asked for, report what it can reach rather than rounding silently.
• Prompt length. The prompt field's max_length ranges from roughly 2000 characters to 32000. A prompt that fits one model is a 400 on the next.
• References. Name (referenceImages, image), cap, and cardinality all come from the schema, and the name settles none of them: a field called referenceImages is a single scalar file on some models. Pass an array only where the schema says array: true, and there pass one even for a lone asset, since a bare string is dropped silently and the run then succeeds while ignoring the reference. With several references, say in the prompt which is which.

A batch-count field (numOutputs, numImages) repeats one prompt, so it yields variations, not a set. Anything with a per-item difference needs one model_run per item.

Landing an exact size

In-game placements need exact pixels (a 210x600 banner, a 256x256 icon), which a generative model may not support directly. Numeric sizing fields snap to a grid (a step of 16 is common, with min and max bounding the range), enum fields offer fixed tiers, and some members silently replace a request below their floor: 512x128 came back as 1408x480 on one member, with no error. When the target is unsupported, generate at the nearest reachable size at or above it, matching the ratio where possible and respecting every schema limit (1024x1024 for a 256x256 icon on a member with a 1K floor; 224x640 for a 210x600 banner only if both dimensions meet that member's limits), then finish with model_scenario-resize-image, a fixed id since it is Scenario's single deterministic exact-dimension resize tool and discovery would only re-derive it: images as an array even for one asset, width and height, and fit cover to fill the box and center-crop the overflow or stretch for exact dimensions at the cost of distortion (contain, the default, can return a smaller image than the box). Choose a larger source only for an explicit quality requirement or documented model guidance, not an assumed family sweet spot. Confirm with asset_get. Downscaling can make softness less visible; resizing upward cannot recover missing detail.

Blur has the same discipline: several members default to a 1K tier with a higher one in the schema, so set the resolution or quality tier explicitly for a new generation. To preserve an approved frame, upscale the exact keeper (scenario-image-editing); re-running its recipe can change the image. On a custom-trained member, check guidance and step count against its schema and model guidance before increasing them. When outputs feel literal, split the prompt into what is fixed and what the model may invent and say so. Invented details must obey the fixed constraints too (no decorative runes in a text-free brief); prompt_spark expands a thin brief into an on-model one before the run.

Prompt wording

In-image text: quote each string exactly and say where it sits ("the label reads 'NORTH', top center"), keep to a few short strings, and spell a word that keeps mangling letter by letter (NORTH: N, O, R, T, H); unquoted copy gets reworded. Copy that must be letter-perfect (prices, legal lines) is composited with scenario-text-overlay, never prompted. A film-still or cinematic prompt, or a ratio written in prose (2.39:1), can bake letterbox bars into the pixels, and an asset_get dimension check reads them as picture: ask for full frame edge to edge, no letterboxing, no black bars, and carry the ratio in the sizing field alone. Where skin shows, name its texture (visible pores, fine hairs, a faint highlight) or it tends to come back retouched smooth.

An instruction edit names the change and pins the rest: "put the chair on a sunlit terrace; keep its shape, fabric and shadow exactly", or for text, "change only the headline to 'NORTH', same typeface, size and position". Anything unnamed is open to change.

Worked example: replacing a label on a product shot

1. recommend with capability="img2img" and the user's own words as prompt. Handle next_step as the scenario skill directs, and never run a requires_plan_upgrade entry.
2. upload_asset the product photo, then upload_asset_complete, which returns the asset_id. Only the inline path under ~100KB skips the second call.
3. model_schema_get on the pick: the reference field's name and cap, which sizing family it uses, the prompt max_length, and whether a mask field exists.
4. For a masked edit, read the mask field's own description before building anything. Masks are not interchangeable: one model wants an alpha channel at the source's exact dimensions, another wants a black and white image it resizes itself, and which pixels get painted differs too. With no mask in hand, recommend with capability="img2img" and the masking need in the user's own words finds segmentation models that take a short noun phrase or a box and return one mask per object; most segmentation models in the catalog segment 3D meshes instead, so check capabilities on the pick. Where no convention fits, an instruction editor scopes the edit in prose instead.
5. model_run with the schema's own field names: the prompt, the reference (wrapped in an array only where the schema says array: true), plus the mask and sizing fields it named. Use dry_run=true first when cost matters.
6. jobs_wait; its ~180s timeout is not an error, so re-call it with the returned pending_job_ids as job_ids. Then asset_display to review and asset_download to save.

Common mistakes

• Passing a bare string where the schema marks the reference field array: true: it is dropped without an error, and the output quietly ignores it.
• Reusing one model's parameter block on another: aspectRatio and width/height rarely coexist, and unknown fields are rejected.
• Retrying a 403 ModelAccessRestrictedError: it names modelId and requiredPlan, so surface the upgrade or pick another model.
• Prompting "transparent background": diffusion outputs are opaque. Use a background field when the schema has one, otherwise run a background-removal model afterwards.
• Re-running an approved frame at a higher size tier and expecting it back sharper: many models expose no seed, and where one exists it reproduces a run only with every other field unchanged, so the re-run is a new image; draft at the cheapest tier, then upscale the exact keeper (scenario-image-editing).
• Assuming a model can hit a requested pixel size: some expose an aspect ratio and nothing else, and others silently substitute a size for one below their floor. Generate near, then resize (Landing an exact size), and confirm what landed with asset_get, which reports properties.width and properties.height; jobs_wait returns asset ids only.