GMI Router Overview

The GMI Router turns a plain-language request into the right model for the job. You send an intent or a full chat, and the API ranks the eligible models by task-category fit, quality, and cost, then either hands back a ranked list or routes the request straight to the best model and returns the completion. Access the playground here: https://console.gmicloud.ai/user-console/ie/gmi-router/test-routing

How routing works

Autoroute treats model selection as a process, not a single guess. Every Autoroute request moves through the same sequence:

Understand. The router reads your latest message and classifies the task and its requirements.
Compare. It scores the allowed model pool across quality, cost, and latency.
Validate. The top candidate is checked before it is committed. A high score alone does not win the request.
Select. The router locks in the winning model.
Respond. The selected model generates the completion, returned inline or streamed token by token.

The flow, at a glance: Prompt -> Understand -> Compare -> Validate -> Select -> Respond. Two ways to use it:

/autoroute picks the model and returns the completion in one call. Streaming is the default.

Authentication

Base URL: https://console.gmicloud.ai/api/v1/ie/recommendation Send a bearer token in the Authorization header: Authorization: Bearer YOUR_TOKEN Most routed responses include an X-Recommendation-ID header. It is absent on auth and early validation errors. Keep this value if you plan to submit feedback later.

Quick start: Autoroute

Send an OpenAI-style messages[] array. The router reads the latest user message, ranks the model pool, and generates with the top candidate.

curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/autoroute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Summarize this contract in three bullet points." }
    ],
    "mode": "balanced",
    "stream": false
  }'

Non-streaming response:

{
  "model": "provider/model-name",
  "message": { "role": "assistant", "content": "..." },
  "routing_metadata": {
    "selected_model": "provider/model-name",
    "task_type": "summarization",
    "selected_mode": "balanced",
    "fallback_models": ["provider/backup-a"],
    "recommendation_id": "bab0a8bb-195f-49c5-8f9c-016da0d89cc8"
  }
}

Request fields

Field	Type	Required	Description
`messages`	array	Yes	OpenAI-style conversation. The full conversation influences routing, not only the latest message
`mode`	string	No	Accepted values are cost, balanced, or quality. Unknown request fields are ignored.
`stream`	boolean	No	Streaming is the default. Set false for one-shot JSON.

Streaming vs non-streaming

Streaming (default). Returns text/event-stream. Chunks are proxied as they arrive, followed by a routing_metadata event, then [DONE]. One backup model may be tried before the first token on a 5xx, provider error, 429, or a 10-second first-token timeout. Once tokens start flowing, no further fallback happens; a mid-stream failure keeps the partial output, sends an error event, and closes the stream.
Non-streaming (stream: false). Returns one JSON object with up to two ordered backups on a transient failure (5xx, provider error, 429, or a 30-second timeout).

The router is stateless. Resend the full conversation on every request.

Quick start: Recommendations

Get a ranked list of models without generating anything.

curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/recommendations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "cheap text generation for summarization",
    "mode": "balanced"
  }'

Response:

{
  "recommendation_id": "bab0a8bb-195f-49c5-8f9c-016da0d89cc8",
  "parsed": { "category": "llm", "use_case": "summarization", "confidence": 0.95 },
  "recommendations": [
    {
      "model_id": "provider/model-name",
      "name": "Model Name",
      "provider": "provider",
      "is_top": true,
      "reason_badge": "best value",
      "estimated_cost_savings": { "amount": 0.0042, "currency": "USD" }
    }
  ]
}

Notes on the response:

estimated_cost_savings appears only on the top recommendation, and only when the estimate is positive.
V1 recommends LLMs only, so category is always llm.

Request fields

Field	Type	Required	Description
`intent`	string	Yes	Plain-language description of the task.
`mode`	string	No	cost, balanced, or quality. Unknown keys are ignored.

Submitting feedback

Feedback is write-once per recommendation. Use the recommendation_id from a recommendation or from autoroute routing metadata.

curl -X POST https://console.gmicloud.ai/api/v1/ie/recommendation/recommendations/{id}/feedback \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "signal": "down", "reasons": ["wrong_task_type", "too_slow"] }'

Rules:

signal is up or down.
For down, include one or more reasons with no duplicates.
For up, omit reasons entirely.
A second submission for the same recommendation returns 409.

Allowed reasons:

not_the_model_i_want, wrong_task_type, model_quality_poor, too_slow, cost_not_meaningfully_lower, model_unavailable, not_allowed_by_policy, prefer_another_model, other.

Routing settings

Routing settings define which models are eligible and how they are ranked. Org owners set the hard bounds; each user sets a preference within those bounds.

Endpoint	Method	Purpose
`/routing-settings`	GET	Read the org bounds, your preference, and the resolved merge. is_org_owner shows whether org settings are editable.
`/routing-settings/org`	PUT	Replace org-level bounds: model scope, allowed model pool, and workspace defaults. Org owners only. For PUT /routing-settings/org, allowed_model_pool cannot be omitted or empty. To allow all models, list every supported model ID. However, orgs with no saved settings, or legacy empty pools, resolve to the full catalog on GET.
`/routing-settings/user`	PUT	Set your own mode and Auto Mode preference within the org bounds.

Defaults when fields are omitted on the org update: model scope all, mode balanced, and Auto Mode on.

Health checks

Both are unauthenticated.

Endpoint	Method	Purpose
`/health`	GET	Service health.
`/ready`	GET	Service readiness.

Status codes

Code	Meaning
`200`	Success.
`401`	Missing or invalid credentials.
`403`	Caller is not an org owner (org settings only).
`404`	No eligible models survived the filters.
`409`	Feedback already submitted for this recommendation.
`422`	Invalid body, or no user message.
`500`	Ranking weights unavailable.
`502`	Every candidate model failed to generate.
`504`	Upstream pricing or signal source timed out.

Getting Started

API Reference

GMI Router

Marketplace

Console

Resources

Billing

Console Release Notes

How routing works

Authentication

Quick start: Autoroute

Request fields

Streaming vs non-streaming

Quick start: Recommendations

Request fields

Submitting feedback

Routing settings

Health checks

Status codes

​How routing works

​Authentication

​Quick start: Autoroute

​Request fields

​Streaming vs non-streaming

​Quick start: Recommendations

​Request fields

​Submitting feedback

​Routing settings

​Health checks

​Status codes

How routing works

Authentication

Quick start: Autoroute

Request fields

Streaming vs non-streaming

Quick start: Recommendations

Request fields

Submitting feedback

Routing settings

Health checks

Status codes