Runware Model Router: set the rules, and let the API choose the model

If you build on image or video models, you've probably noticed how often the lineup changes. New models land every few days, and prices for the same kind of output can be far apart. On Runware today, an image of about one megapixel costs $0.0006 on TwinFlow Z-Image-Turbo at 4 steps and $0.138 on Nano Banana Pro. Ten seconds of 1080p video costs $0.70 on KlingAI 2.5 Turbo Pro and $2.35 on Kling VIDEO 4.0, which arrived on Oct 23.

The usual way to cope is to hardcode a model ID and track prices in a spreadsheet. The spreadsheet is out of date almost as soon as you finish it, and the hardcoded model ends up handling every kind of job in your app, so a product thumbnail and a landing-page hero image go to the same model even when they'd be better served by different ones.

The Runware Model Router takes that choice off your plate. Each request describes what it needs, and the router picks the model for it.

What changes in your request

Your request looks almost exactly like it does today. Put "model": "auto" where the model ID would go and leave the rest as it is. The router keeps every value you set, fills in only what you've left out, and never rewrites your prompt. If a model can't take one of your values, say a five-second duration, the router passes over it.

The response works the way you're used to. The task runs as soon as a model has been chosen, so routing doesn't add a second call or a step of its own to wait on. You get the result the same way as any other request for that task type, including polling when a long task is still processing, along with the name of the model that served it. Add includeCost and you'll also see what the run cost. Routing itself is free; you pay the price of whichever model it picks.

It works across the task types you're likely already using: image, video, and audio generation, text and 3D generation, upscaling, background removal, captioning, vectorizing, prompt enhancement, and more.

How the Runware Model Router chooses a model

The router narrows the catalog down in three passes. Pick an example below to watch a request go through them.

{  "taskType": "imageInference",  "taskUUID": "ef485de7-4ba6-4aeb-aa66-ac427bc974d8",  "model": "auto",  "positivePrompt": "a ceramic coffee mug on a marble counter, morning light",  "width": 1024,  "height": 1024,  "includeCost": true,  "routing": {    "preferences": {      "quality": 2,      "speed": 4,      "cost": 5    },    "maxPrice": 0.01  }}

The first pass is the straightforward one. The router compares each model's published schema and listed prices against your request, and removes any model that can't run the task, can't accept one of your values, or would cost more than your maxPrice at its listed rates.

The second pass covers what a schema can't express. Something like "with audio, 1080p or better", "in a watercolor style", or "with a transparent background" takes judgment, so the router uses a mix of decision models and LLMs to check your requirements against each remaining model, and drops the ones that fall short.

Then it ranks whatever is left. It looks at measured signals, including public benchmark scores for quality, measured run times for speed, and each model's price for your request, weights them by your preferences, and runs the top model. Quality here means how good a model's outputs are in general, so if you care about a particular style or subject, such as photorealism or illustration, put that in your requirements instead. Newer or rarely used models may not have enough data for a quality score yet.

Setting preferences, a price ceiling, and requirements

All of this is controlled by the routing object, which takes three settings.

preferences weight quality, speed, and cost on a scale from 0 to 5. They only affect the order of the models that have already passed the checks. Setting one to 0 takes it out of the decision entirely, and if you skip preferences altogether, all three count equally.

maxPrice is your price ceiling for the request, in USD. It's measured against what you're actually asking for, so a per-second model is priced over your requested duration and a per-image model over the number of results. When a model has several rates, the router checks the most expensive one, because the tier isn't set until the task runs. The ceiling is best effort for realistic settings, since some models bill by compute time and extreme parameters, like a very high step count, can push the cost past their listed rates. Models whose cost can't be known up front are left out whenever maxPrice is set. If you want them in the mix, drop the ceiling and weight cost instead.

requirements describe what the result must have, in up to 3,000 characters of plain language. They're meant for things no parameter can hold, like "video with audio" or "an open-source model". You can write settings in there too, such as "a 1024x1024 image in 20 steps", and the router will take them into account, but they're more reliable as real parameters like width, height, and steps, so use those whenever one exists. Your prompt still describes the subject, and if you don't send a prompt at all, the router writes one from your requirements.

Here's a video request that puts all three to work:

{
  "taskType": "videoInference",
  "taskUUID": "<uuid-v4>",
  "model": "auto",
  "positivePrompt": "a drone shot over a harbor at sunrise",
  "duration": 5,
  "includeCost": true,
  "routing": {
    "preferences": {
      "quality": 5,
      "speed": 2,
      "cost": 1
    },
    "maxPrice": 1,
    "requirements": "with audio, 1080p or better"
  }
}

In our test run on Oct 19, the router sent this request to PixVerse V6, which came back with a five-second 1080p clip with audio for $0.575, comfortably under the $1.00 ceiling.

The response names the model the router picked and what the run cost:

{
  "data": [
    {
      "taskType": "videoInference",
      "videoUUID": "e1bc0800-55dc-45bd-bd60-468349199666",
      "taskUUID": "0dcd3f98-2882-4522-879d-045ab21b4ffb",
      "model": "pixverse:1@8",
      "cost": 0.575,
      "seed": 2015850649,
      "videoURL": "https://vm.runware.ai/video/os/a01d21/ws/5/vi/e1bc0800-55dc-45bd-bd60-468349199666.mp4"
    }
  ]
}

When nothing fits

Now lower the ceiling on that same request to $0.05. No model can deliver five seconds of 1080p video with audio at that price, so the router doesn't run anything. It returns noEligibleModel with a reason that tells you why, instead of quietly downgrading your request to make it fit.

Each failure has its own error code, which makes them easy to handle separately:

Where the Runware Model Router fits

The router suits work where the output and the budget matter more than which model made it. You also stop tracking launches yourself: when a newly added model suits your request better than the current pick, "model": "auto" starts sending work its way, and there's nothing to redeploy. For batch jobs, set maxPrice once and every request is checked against it at listed prices before anything runs, while a higher cost weight leans the picks toward cheaper models that still meet your requirements.

If your users write the prompts, you can't tell whether the next one needs readable text, a transparent background, or a photoreal face. Send their prompt as usual and put any must-haves from your UI, such as a "transparent background" checkbox, in requirements, and the router picks a model that can deliver them. The same call can serve every plan you sell, too: free-plan requests get a low maxPrice and a high cost weight, paid-plan requests get a high quality weight, and only the routing object changes.

It also works through the Runware MCP server. An agent can send "model": "auto" and put its needs in requirements rather than keeping its own notes on which model does what. And for a prototype, you can write down the result you're after and start building before you've chosen a model.

What it routes, and when to pin a model

The router picks only from Runware's official model catalog. Community models and your organization's private models stay outside it, and you reach them by model ID like any other request.

Routing isn't deterministic, so two identical calls can reach different models. Pin a model yourself when you need the same one every time: when your product depends on one model's exact look, like a consistent style across thousands of images, when your prompts are tuned to a particular model, or when an agent has to stay on one model for a whole conversation. Once a prototype settles on a model you like, pin that one too.

Try it

Take a request you already send and swap the model ID for "auto". The Model Router page shows a request going through each step, along with the routing controls and use cases, and the Model Router docs cover every parameter, with examples in TypeScript, Python, cURL, and the CLI.

Frequently asked questions