Provider routing

Sunra routes a canonical model ID to an available provider automatically. In most requests, omit provider and let Sunra select the route.

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Use the optional provider object when you need a specific provider or want to control the eligible provider set. Provider routing is supported by Chat Completions, Messages, Responses, and Embeddings.

Discover available providers

Provider availability varies by model and API format. Query the discovery endpoint before presenting provider choices in an application:

curl "https://api-llm.sunra.ai/v1/models/google/gemini-2.5-flash/providers?format=chat%2Fcompletions" \
  -H "Authorization: Bearer <SUNRA_KEY>"

{
  "object": "list",
  "data": [
    {
      "id": "google-vertexai",
      "name": "Google Vertex AI",
      "supported_formats": ["chat/completions", "messages", "responses"]
    },
    {
      "id": "openrouter",
      "name": "OpenRouter",
      "supported_formats": ["chat/completions", "messages", "responses"]
    }
  ]
}

The discovery endpoint uses the same API key authentication as the LLM inference endpoints. Supported format values are chat/completions, messages, responses, and embeddings.

Select one provider

Set provider.only to restrict the request to one provider:

curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "provider": {
      "only": ["google-vertexai"]
    },
    "messages": [
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'

The request returns an error when none of the requested providers can serve the model and API format.

Set a preference order

Use order to prefer providers in sequence. Providers not listed in order remain eligible unless allow_fallbacks is false.

{
  "provider": {
    "order": ["google-vertexai", "openrouter"],
    "allow_fallbacks": false
  }
}

allow_fallbacks controls the initial eligible provider set. It does not retry a request through another provider after an upstream response or failure has started.

Exclude providers

Use ignore to remove providers from automatic routing:

{
  "provider": {
    "ignore": ["openrouter"]
  }
}

Prefer the lowest price

Use sort: "price" to prefer the lowest-priced eligible route. Price sorting applies when order is omitted.

{
  "provider": {
    "sort": "price"
  }
}

latency and throughput sorting are not currently supported.

Provider fields

provider

object

Optional routing preferences. Omit this object for automatic routing.

Show properties

only

string[]

Restrict routing to these provider IDs.

order

string[]

Prefer providers in this order.

ignore

string[]

Exclude these providers from routing.

allow_fallbacks

boolean

When order is present, allow providers not listed in order to remain eligible. Defaults to true.

sort

string

Sort eligible providers. Currently supported value: price.

Overview

Platform

Multimodal

LLM

Client Libraries

Discover available providers

Select one provider

Set a preference order

Exclude providers

Prefer the lowest price

Provider fields

​Discover available providers

​Select one provider

​Set a preference order

​Exclude providers

​Prefer the lowest price

​Provider fields

Discover available providers

Select one provider

Set a preference order

Exclude providers

Prefer the lowest price

Provider fields