Skip to main content

​
What a wrapper is

A model is a raw capability: it takes whatever inputs the provider exposes and returns a result. A wrapper is the product you build on top of one (or more) of those models. It gives the model:
  • a custom input schema — the small set of fields your users actually fill in,
  • a prompt template — a fixed recipe that turns those fields into the prompt the base model sees,
  • and field mappings — rules that reshape your inputs into each base model’s native schema.
The result is callable at the exact same kind of endpoint as a model — ownerName/alias — so anything that can call a ModelRunner model can call a wrapper with no extra work.
Think of a model as an engine and a wrapper as the car you ship around it. Wrappers are ModelRunner’s product-composition layer: the same handful of base models can back dozens of distinct, opinionated products.

​
Why build one

Make it foolproof

Expose two friendly fields (subject, mood) instead of the base model’s fifteen raw parameters. Bake the good defaults in so every call looks professional.

Ship a house style

Enforce a look — “cinematic portrait”, “isometric game asset”, “corporate headshot” — through the prompt template. Callers pick the subject; your recipe does the rest.

Combine inputs

Collect several inputs into the shape a model wants — e.g. a person photo plus two garment images merged into one image_urls array for a virtual try-on.

Stay model-agnostic

Put one stable interface in front of several base models. Swap or A/B the underlying model — or offer speed/quality tiers — without your callers changing a line. See switching base models.

Curate a catalog

Group base models into named, described, thumbnailed products with example outputs — a catalog your users browse instead of raw model parameters.

​
Anatomy of a wrapper

A wrapper is four things layered over a base model. At request time, the caller’s input flows through them in order: the prompt template builds the prompt, then the field mappings reshape everything into the exact input the base model expects.
PartWhat it doesWhere to read more
Input schemaThe user-facing fields your wrapper accepts (OpenAPI-style JSON Schema).Build a wrapper
Prompt templateHandlebars recipe that builds the base model’s prompt from those fields.Prompt templates
Base model(s)One or more existing models the wrapper runs on.Switching base models
Field mappingsPer-model rules (collectFields, staticValues, presets, renames, omit) that adapt your input to each model’s schema.Build a wrapper

​
Calling a wrapper

A wrapper is called exactly like a model — same endpoint format, same request lifecycle, same status URLs. The body is just your wrapper’s input fields: 
POST /{ownerName}/{alias}
Authorization: Key $MODELRUNNER_KEY
Content-Type: application/json

{ "subject": "a fox in a trench coat", "mood": "noir" }
Everything in request lifecycle applies unchanged — polling, the SSE stream, cancellation, and automatic finalization all work the same way for wrapper requests.
Callers don’t write the base model’s prompt or its raw parameters — they only fill in the fields your schema defines. The wrapper turns those into the full base-model payload server-side.

​
Discovering wrappers

Wrappers live in the same catalog as models. From an AI assistant connected to the MCP server, list_wrappers, recommended_wrappers, and get_wrapper browse and inspect them; search spans both models and wrappers in one call.

​
Next steps

Build a wrapper

A full worked example, end to end, from your AI assistant.

Prompt templates

Handlebars helpers, lookup maps, and the rules to follow.

Switching base models

One wrapper, many models — and letting callers choose.