Scenario Model Training
Overview
Train a custom model when one look must hold across many assets: an icon set, a recurring character,
a product line. Prompts, references, and control maps are cheaper first steps: see
scenario-consistency. Before quoting a training run, run the reference test scenario-consistency
teaches for the subject at hand: the approved art as style references (with the prompt saying they
set the style only) for a look, the hero as a subject reference for a character or product. At
authoring time a style test matched the look of a custom LoRA on the same brief at a comparable
per-image price, for the cost of one generation. Train when that test drifts across the set, not
before; the worked example below starts after it.
The judgment calls live in two references:
references/base-model-selection.md (the user interview that
feeds recommend_training) and references/dataset-curation.md
(dataset size, image rules, captions, and review per training type).
Connection and the core generation loop: see the scenario skill. If a sibling skill named here is
missing from your available skills, load it with skill_get (Scenario MCP) or ask the user to
install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas
and flag the gap.
Training tools are not in the default toolset: get schemas with scenario_tools_search, run reads
(recommend_training, model_get) via scenario_tool_execute_read and writes (model_create,
train, model_update) via scenario_tool_execute_write, or reconnect with ?toolsets=full.
Quick reference
| Step |
Tool |
| Pick a base architecture |
recommend_training (LLM-powered, cost-bearing) |
| Create the model shell |
model_create (data.type from the recommendation) |
| Upload the dataset |
upload_asset + upload_asset_complete |
| Attach training images |
train action upload_images, 10 asset ids per call |
| Estimate cost |
train action configure with dry_run: true (a quote, no job) |
| Preview every epoch |
config.sample_prompts, at least one on any multi-epoch run |
| Launch |
train action start, with the same config or bare for defaults |
| Wait |
jobs_wait with the returned job id |
| Generate |
model_schema_get on YOUR model id, then model_run |
| Manage |
models_list, model_get, model_update |
Worked example: a style LoRA for game props
recommend_training with prompt: "hand-painted prop icons for a mobile RPG",
modality: "image", dataset_shape: "single_images", plus subject, style, and priority
from the interview. Returns a recommended variant, alternatives, and dataset_requirements
(shape and size bounds). Cost-bearing: call it once with clear intent.
model_create with data: {"name": "rpg-prop-icons", "type": "<type from step 1>"}. Note the
returned model id.
- Curate the set first (dataset reference), matching
dataset_requirements from step 1, then
upload each file with upload_asset plus upload_asset_complete (see the scenario skill) and
collect the asset ids. For image_pairs datasets, map pairs with train action set_pairs.
train with action: "upload_images", model_id, images: [<asset ids>], at most 10 per call
(see Dataset limits); it changes data, so pass team_id and project_id (scope: the scenario
skill).
train with action: "configure",
config: {"epochs": 12, "sample_prompts": ["a rusty lantern icon, centered, plain field", "a blue mana potion icon, three-quarter view, plain field"]},
dry_run: true returns the quote and starts nothing. epochs is the main cost lever (scales
linearly); size the other levers by dataset size (dataset reference). sample_prompts is not
optional on a multi-epoch run: the trainer publishes a per-epoch checkpoint only for a run that
has them, so a run without them finishes with its final weights alone, one epoch to choose from
whatever epochs said, and a model that ends up overfit has nothing earlier to fall back to (a
12-epoch run that came back with a single selectable epoch was this). Caps are per family, 8 on
the Flux LoRA family and 4 on Flux.2, Qwen and ZImage LoRAs at authoring time, so read them off
the train schema. Write prompts that test the concept off-dataset, following the caption rules
of the training type (a style set names new subjects and never the style; a character set leads
with the trigger word and a new pose or setting): they are the previews you pick the epoch from,
and generic prompts return generic scenes at every epoch, which is how one run spent its whole
quote on twenty previews of four unrelated landscapes. Edit families take sample_source_images,
one asset id per prompt in the same order; every other family rejects the field. Show the user
the quote and get a go-ahead, then launch with action: "start" and the same config
(unattended, launch only when the task already authorized training or a budget covering it;
otherwise stop and report the quote). configure always quotes and never launches;
dry_run: false there is rejected. Only start launches training; start with dry_run: true
quotes instead. Treat start as spending the whole quote: do not count on stop returning any
of it.
- The launch response includes a job:
jobs_wait with its id in job_ids. No job id means nothing
launched: report it instead of retrying. Training outlasts the server wait budget, so re-call
with the returned pending_job_ids until completed; never poll job_get.
- Pick the epoch from the previews before generating: they sit on the model page in the web app,
and the strongest is rarely the last. The pick is the user's; unattended, generate with the model
as trained, say that the epoch choice was left open, and continue. Then
model_schema_get on
your new model id and model_run; custom models carry their own parameter contract. A LoRA runs
on the base that the schema's runs_as and run_with.required_arguments name (see scenario)
and on no other variant of its family, with one documented exception, the Z-Image LoRAs that
carry across the Z-Image variants (base reference). A size mismatch or weight dimension error
at generation means another variant was sent as the base, not that the training failed: do not
retrain, re-read run_with and run the pair it names.
- Manage:
models_list with filters: {"privacy": "private", "status": "trained"} lists ready
models. model_get with include_description: true fetches the full docs; model_update edits
name, descriptions, privacy.
Dataset limits that stop a run
Nearly every train failure is dataset handling, not hyper-parameters.
- Ten ids per call.
upload_images takes at most 10 asset ids; more returns 400
Too many assetIds provided in a single request. Call once per 10-id chunk: the model accumulates
the whole set.
- Chunks must not overlap. Re-sending an id already attached returns 400
The provided assetId is already a training image of this model. After a partial failure, re-send
only the chunks that did not land.
- Two separate plan ceilings. Dataset size is capped per team: past it,
upload_images returns
429 naming add-training-image with the ceiling in actionLimit. Chunking cannot bypass it: trim
to the strongest images or surface the upgrade. Concurrent trainings are capped separately as
parallel-training, and some plans set it to zero.
- Images before configuration.
configure or start on an empty dataset fails validation on
the training-image count. Pair datasets need whole pairs, with a family minimum above one.
- One launch at a time. Once a run is live, launching again returns 400
Model is already training: wait with jobs_wait or train action: "stop". Repeated launches
also hit a cooldown whose 429 names remainingSeconds.
Common mistakes
- Training for a one-off. One on-style image is a prompt plus reference job; the public catalog
holds many trained LoRAs,
search first.
- Reading the same wrong face on every output as ordinary drift. A model that reproduces one
consistent stranger learned the captions, not the pictures: the images carried too little identity
signal, usually because they were all derived from one source image and only look varied, so the
dataset reads as near-duplicates of one composition. Fix the dataset (genuinely different shots,
captions naming only the variables, a trigger word), not the epochs (dataset reference).
- Using
recommend_training to pick a generation model: it only picks training bases; use
recommend or search.
- Passing local paths or URLs to
train: upload with upload_asset first and pass asset ids;
anything else surfaces as a body-shape error naming assetId.
- Reading 400
Custom models only are supported for this endpoint as a parameter problem: the route
accepts your own trained models only; re-read the id from models_list.
- Launching several epochs with no
sample_prompts: the run completes, but with one epoch and no
previews, so the quote bought no comparison.
- Treating a quote as a launch.
configure returns training_started: false and no job; launch
through start only after approval and require a job id before waiting.
- Filtering
models_list with status: "ready": free-form values are silently ignored, returning
everything including deleted models. Use "trained".
model_update data.tags replaces the whole tag set; use model_add_tags / model_remove_tags
for diffs.
- Expecting an older base from
recommend_training: the default excludes legacy families; set
legacy_ok: true only when a project must stay on one.
Voice cloning
Voice cloning starts from the same recommend_training call with modality: "voice" and
dataset_shape: "short_audio" or "long_audio"; the returned type feeds model_create the same
way.
1---2name: scenario-model-training3description: "Use when generated assets must keep a consistent style, character, or product look and references stop scaling, or when a user asks to train a custom model through the Scenario MCP, fine-tune a LoRA, clone a voice, curate a training dataset, choose a base model, set epochs and sample prompts, estimate training cost, diagnose a trained model that lost its identity or has one epoch, or generate with a trained model. Keywords: custom model, LoRA, dataset curation, epoch previews."4license: MIT5metadata:6 source: https://skillmd.com/skills/scenario-labs/scenario-model-training7---89# Scenario Model Training1011## Overview1213Train a custom model when one look must hold across many assets: an icon set, a recurring character,14a product line. Prompts, references, and control maps are cheaper first steps: see15`scenario-consistency`. Before quoting a training run, run the reference test `scenario-consistency`16teaches for the subject at hand: the approved art as style references (with the prompt saying they17set the style only) for a look, the hero as a subject reference for a character or product. At18authoring time a style test matched the look of a custom LoRA on the same brief at a comparable19per-image price, for the cost of one generation. Train when that test drifts across the set, not20before; the worked example below starts after it.2122The judgment calls live in two references:23[references/base-model-selection.md](references/base-model-selection.md) (the user interview that24feeds `recommend_training`) and [references/dataset-curation.md](references/dataset-curation.md)25(dataset size, image rules, captions, and review per training type).2627Connection and the core generation loop: see the `scenario` skill. If a sibling skill named here is28missing from your available skills, load it with `skill_get` (Scenario MCP) or ask the user to29install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas30and flag the gap.3132Training tools are not in the default toolset: get schemas with `scenario_tools_search`, run reads33(`recommend_training`, `model_get`) via `scenario_tool_execute_read` and writes (`model_create`,34`train`, `model_update`) via `scenario_tool_execute_write`, or reconnect with `?toolsets=full`.3536## Quick reference3738| Step | Tool |39| ------------------------ | ------------------------------------------------------------------- |40| Pick a base architecture | `recommend_training` (LLM-powered, cost-bearing) |41| Create the model shell | `model_create` (`data.type` from the recommendation) |42| Upload the dataset | `upload_asset` + `upload_asset_complete` |43| Attach training images | `train` action `upload_images`, 10 asset ids per call |44| Estimate cost | `train` action `configure` with `dry_run: true` (a quote, no job) |45| Preview every epoch | `config.sample_prompts`, at least one on any multi-epoch run |46| Launch | `train` action `start`, with the same `config` or bare for defaults |47| Wait | `jobs_wait` with the returned job id |48| Generate | `model_schema_get` on YOUR model id, then `model_run` |49| Manage | `models_list`, `model_get`, `model_update` |5051## Worked example: a style LoRA for game props52531. `recommend_training` with `prompt: "hand-painted prop icons for a mobile RPG"`,54 `modality: "image"`, `dataset_shape: "single_images"`, plus `subject`, `style`, and `priority`55 from the interview. Returns a recommended variant, alternatives, and `dataset_requirements`56 (shape and size bounds). Cost-bearing: call it once with clear intent.572. `model_create` with `data: {"name": "rpg-prop-icons", "type": "<type from step 1>"}`. Note the58 returned model id.593. Curate the set first (dataset reference), matching `dataset_requirements` from step 1, then60 upload each file with `upload_asset` plus `upload_asset_complete` (see the `scenario` skill) and61 collect the asset ids. For `image_pairs` datasets, map pairs with `train` action `set_pairs`.624. `train` with `action: "upload_images"`, `model_id`, `images: [<asset ids>]`, at most 10 per call63 (see Dataset limits); it changes data, so pass `team_id` and `project_id` (scope: the `scenario`64 skill).655. `train` with `action: "configure"`,66 `config: {"epochs": 12, "sample_prompts": ["a rusty lantern icon, centered, plain field", "a blue mana potion icon, three-quarter view, plain field"]}`,67 `dry_run: true` returns the quote and starts nothing. `epochs` is the main cost lever (scales68 linearly); size the other levers by dataset size (dataset reference). `sample_prompts` is not69 optional on a multi-epoch run: the trainer publishes a per-epoch checkpoint only for a run that70 has them, so a run without them finishes with its final weights alone, one epoch to choose from71 whatever `epochs` said, and a model that ends up overfit has nothing earlier to fall back to (a72 12-epoch run that came back with a single selectable epoch was this). Caps are per family, 8 on73 the Flux LoRA family and 4 on Flux.2, Qwen and ZImage LoRAs at authoring time, so read them off74 the `train` schema. Write prompts that test the concept off-dataset, following the caption rules75 of the training type (a style set names new subjects and never the style; a character set leads76 with the trigger word and a new pose or setting): they are the previews you pick the epoch from,77 and generic prompts return generic scenes at every epoch, which is how one run spent its whole78 quote on twenty previews of four unrelated landscapes. Edit families take `sample_source_images`,79 one asset id per prompt in the same order; every other family rejects the field. Show the user80 the quote and get a go-ahead, then launch with `action: "start"` and the same `config`81 (unattended, launch only when the task already authorized training or a budget covering it;82 otherwise stop and report the quote). `configure` always quotes and never launches;83 `dry_run: false` there is rejected. Only `start` launches training; `start` with `dry_run: true`84 quotes instead. Treat `start` as spending the whole quote: do not count on `stop` returning any85 of it.866. The launch response includes a job: `jobs_wait` with its id in `job_ids`. No job id means nothing87 launched: report it instead of retrying. Training outlasts the server wait budget, so re-call88 with the returned `pending_job_ids` until completed; never poll `job_get`.897. Pick the epoch from the previews before generating: they sit on the model page in the web app,90 and the strongest is rarely the last. The pick is the user's; unattended, generate with the model91 as trained, say that the epoch choice was left open, and continue. Then `model_schema_get` on92 your new model id and `model_run`; custom models carry their own parameter contract. A LoRA runs93 on the base that the schema's `runs_as` and `run_with.required_arguments` name (see `scenario`)94 and on no other variant of its family, with one documented exception, the Z-Image LoRAs that95 carry across the Z-Image variants (base reference). A `size mismatch` or `weight dimension` error96 at generation means another variant was sent as the base, not that the training failed: do not97 retrain, re-read `run_with` and run the pair it names.988. Manage: `models_list` with `filters: {"privacy": "private", "status": "trained"}` lists ready99 models. `model_get` with `include_description: true` fetches the full docs; `model_update` edits100 name, descriptions, privacy.101102## Dataset limits that stop a run103104Nearly every `train` failure is dataset handling, not hyper-parameters.105106- **Ten ids per call.** `upload_images` takes at most 10 asset ids; more returns 400107 `Too many assetIds provided in a single request`. Call once per 10-id chunk: the model accumulates108 the whole set.109- **Chunks must not overlap.** Re-sending an id already attached returns 400110 `The provided assetId is already a training image of this model`. After a partial failure, re-send111 only the chunks that did not land.112- **Two separate plan ceilings.** Dataset size is capped per team: past it, `upload_images` returns113 429 naming `add-training-image` with the ceiling in `actionLimit`. Chunking cannot bypass it: trim114 to the strongest images or surface the upgrade. Concurrent trainings are capped separately as115 `parallel-training`, and some plans set it to zero.116- **Images before configuration.** `configure` or `start` on an empty dataset fails validation on117 the training-image count. Pair datasets need whole pairs, with a family minimum above one.118- **One launch at a time.** Once a run is live, launching again returns 400119 `Model is already training`: wait with `jobs_wait` or `train` `action: "stop"`. Repeated launches120 also hit a cooldown whose 429 names `remainingSeconds`.121122## Common mistakes123124- Training for a one-off. One on-style image is a prompt plus reference job; the public catalog125 holds many trained LoRAs, `search` first.126- Reading the same wrong face on every output as ordinary drift. A model that reproduces one127 consistent stranger learned the captions, not the pictures: the images carried too little identity128 signal, usually because they were all derived from one source image and only look varied, so the129 dataset reads as near-duplicates of one composition. Fix the dataset (genuinely different shots,130 captions naming only the variables, a trigger word), not the epochs (dataset reference).131- Using `recommend_training` to pick a generation model: it only picks training bases; use132 `recommend` or `search`.133- Passing local paths or URLs to `train`: upload with `upload_asset` first and pass asset ids;134 anything else surfaces as a body-shape error naming `assetId`.135- Reading 400 `Custom models only are supported for this endpoint` as a parameter problem: the route136 accepts your own trained models only; re-read the id from `models_list`.137- Launching several epochs with no `sample_prompts`: the run completes, but with one epoch and no138 previews, so the quote bought no comparison.139- Treating a quote as a launch. `configure` returns `training_started: false` and no job; launch140 through `start` only after approval and require a job id before waiting.141- Filtering `models_list` with `status: "ready"`: free-form values are silently ignored, returning142 everything including deleted models. Use `"trained"`.143- `model_update` `data.tags` replaces the whole tag set; use `model_add_tags` / `model_remove_tags`144 for diffs.145- Expecting an older base from `recommend_training`: the default excludes legacy families; set146 `legacy_ok: true` only when a project must stay on one.147148## Voice cloning149150Voice cloning starts from the same `recommend_training` call with `modality: "voice"` and151`dataset_shape: "short_audio"` or `"long_audio"`; the returned `type` feeds `model_create` the same152way.