Smart routing

Set "model": "auto" and let the gateway pick. Quality-band routing based on authoritative benchmarks — cost-aware within the band, never cheap for cheap's sake.

What it is

Smart routing is live in production. Instead of pinning a model ID, send your request to the routing endpoint with "model": "auto". The gateway classifies the task, consults current benchmark scores and live upstream health, and dispatches the request to the model that best fits your preference. The candidate pool spans all five providers — including the Moonshot Kimi family — so "auto" may select a Kimi model (for example kimi-k2.7-code on code tasks) whenever it leads the quality band. Explicit model IDs still work exactly as before on the standard /v1/chat/completions endpoint — routing is opt-in, and you can mix both styles in one application.

Routing endpoint

POST https://api.houjiayan.com/v1/auto/chat/completions

Quickstart

One curl is enough. The request below uses quality routing (the default) with a code task hint:

curl https://api.houjiayan.com/v1/auto/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "preference": "quality",
    "task_hint": "code",
    "messages": [
      {"role": "user", "content": "Write a Python function that validates an email address."}
    ]
  }'

Two optional fields steer the router: preference (quality / balanced / cost — defaults to quality) and task_hint (one of the task types listed below). Omit both and the gateway classifies the task from your prompt and routes with quality.

The three preferences

The quality band is drawn first, and it is the same for all three preferences. What changes is how the router picks inside the band:

Preference	Behaviour	When to use
`quality (default)`	Picks the highest-scoring in-band model for the detected task. Price is not considered.	Default and recommended when you want the best result — hard reasoning, production code, anything where a wrong answer costs more than tokens.
`balanced`	Picks the best value inside the band — near-top quality at the lower end of the band's price range.	Workloads where you want a middle ground between quality and cost.
`cost`	Picks the cheapest model that still sits inside the quality band.	High-volume or latency-tolerant workloads where band-level quality is enough.

Note that cost does not mean "the cheapest model overall". The band itself is fixed by quality — even preference: cost is cost-aware within the band, never below it.

The quality-band rule, in plain language

We rank candidate models by scores from authoritative public benchmarks — primarily Artificial Analysis. For each task type we draw a quality band: every model scoring within 0.05 of the top score is treated as "good enough to be the right answer". Price is only ever compared inside that band. The router will never send your request to a cheaper model that scores below the band, whatever your preference says. Quality is decided first; cost second.

Supported task types

The router classifies the task automatically from your prompt. You can set task_hint to steer it explicitly:

task_hint	Task type	How it's routed
`code`	Code	Generation, completion, debugging. Routed to the strongest in-band code model.
`chat`	Chat	General conversation and Q&A. Routed to fast, cost-efficient in-band models.
`summary`	Summarisation	Condensing text. Routed to in-band models with strong compression fidelity.
`long-doc`	Long documents	Large inputs, codebases, RAG. Routed to in-band models with the largest context windows.
`translate`	Translation	Cross-language work. Routed to in-band models with the strongest multilingual scores.
`writing`	Writing	Prose, marketing, editorial. Routed to in-band models tuned for fluent long-form output.
`vision`	Vision	Image inputs, OCR, multimodal. Routed to in-band multimodal models only.

Reading the routing decision

Non-streaming responses include a routing_decision object. Streaming responses carry the same data in the X-Routing-Decision response header. Either way, every routed call can be audited:

Field	Meaning
`selected`	The model that actually served the request.
`candidates`	The shortlist of in-band models that were considered for this request.
`reason`	A human-readable explanation: the detected task type, your preference, and why the winner won.
`source annotation`	The benchmark source behind the quality scores (primarily Artificial Analysis), so you can verify the ranking independently.

{
  "routing_decision": {
    "selected": "kimi-k2.7-code",
    "candidates": ["deepseek-v4-pro", "qwen3.7-max"],
    "reason": "code task, preference=quality, highest in-band code score",
    "source": "Artificial Analysis"
  }
}

Fallback behaviour

If the router itself is unavailable, routed requests do not fail. The gateway degrades to its standard multi-upstream selection — a healthy upstream serving a default general-purpose model — and marks the decision source as fallback in routing_decision (or the X-Routing-Decision header). You still get a response; what you lose is the task-aware optimisation, not availability. Explicit model IDs on /v1/chat/completions are unaffected by router availability at all.

You can still pin models yourself: "model": "deepseek-v4-pro" (or any listed model ID) on the standard endpoint bypasses routing entirely. Mix freely — pin critical endpoints, use "auto" for the long tail.

Questions?

Email support@houjiayan.com. We respond within 24 hours on business days.