Singular request extensions

Fallback model list

Singular accepts a models array with two or more string IDs. The first valid entry becomes the primary model and the remainder become an ordered fallback list:

{
  "models": [
    "provider/primary-model",
    "provider/first-fallback",
    "provider/second-fallback"
  ],
  "messages": [{"role": "user", "content": "Hello"}]
}

This is a Singular extension, not an OpenAI field. A one-item models array is ignored; use the standard model field when there is no fallback list.

Accountless x402 and MPP calls do not support this extension. A paid request must contain exactly one explicit live-catalog model, omit models, and avoid Singular routing suffixes so the quoted model and executed model cannot diverge.

Routing profiles

Set routing_profile (or routingProfile) to one of:

• eco: bias policy toward economical eligible candidates.
• auto: use the balanced default policy.
• premium: bias toward higher-tier eligible candidates.
• agentic: bias scoring toward the agentic routing profile. It does not hard-filter eligibility or tool capability.

Profiles are policy inputs, not guarantees that a particular provider or model will be selected.

Provider preference object

Advanced callers can place routing preferences in a provider object. Supported controls include ordered/only/ignored provider sets, fallback permission, required-parameter checks, zero-data-retention and data-collection constraints, region and quantization filters, price ceilings, and throughput/latency preferences.

{
  "model": "auto",
  "provider": {
    "allowFallbacks": true,
    "sort": "price",
    "zdr": true,
    "maxPrice": {"prompt": 2, "completion": 8}
  },
  "messages": [{"role": "user", "content": "Hello"}]
}

A constraint can reduce the candidate pool to zero. Applications must handle a no-eligible-model error instead of silently dropping security or price constraints.

Supported model suffixes

Singular recognizes exactly three final suffixes:

Only the last colon-delimited token is inspected. Unknown suffixes remain part of the model ID because some provider models legitimately contain colons. Suffixes such as :online, :thinking, and :memory are not Singular controls in the current product runtime.

Precedence

Organization, team, key, and server-side guardrails can narrow or override caller preferences. Body extensions never grant access to a disallowed provider, model, region, data policy, or spend tier.