Model selection
Model slugs and their accepted spellings, catalog filters, and per-request control of retries, fallback and route.
Slugs and spellings
A model is a slug from GET /v1/models (models your key can call). These spellings authorize as the same slug and are recorded under it:
| You send | Means |
|---|---|
gpt-6-luna | The slug |
openai/gpt-6-luna | Vendor prefix: valid only when the vendor is the maker or one of its OpenRouter listings |
<slug>:free | Free only: served while a free tier funds it, then 429 free_limit_reached, never billed. No free tier: 403 model_not_granted (Free models) |
<slug>:online | Adds web search |
claude-fable-5-1 | Anthropic dashed ids map to the dot form; dated ids are 403 |
GET /api/v1/models lists the OpenRouter-shaped ids with canonical_slug on each.
/v1/modelsGET/api/v1/modelscurl https://api.experientiallabs.ai/v1/models \
-H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data[].id'Browse the catalog
GET /api/models is keyless (your key adds your org's own models). Filters: modality, category, provider, min_context, max_input_nano_usd_per_million, supports, retention, sort (preferred, price, age, context, throughput), limit, offset. One model's detail has max_input_tokens, max_output_tokens, supported_params and pricing. Catalog concepts: Models and catalog.
/api/modelsGET/api/models/{slug}curl "https://api.experientiallabs.ai/api/models?sort=price&min_context=200000&limit=10"Retries and fallback per request
Each slug resolves through an ordered list of provider routes (How routing works). Override retry and fallback for one call with a gateway object in the body of Chat, Responses or Messages (Python: extra_body). It is never sent upstream and is rejected on token counting and batch lines. Default without it: 2 attempts per route, 8 total.
| Field | Values |
|---|---|
retry.max_attempts_per_route | 1 to 4, first attempt included |
retry.max_total_attempts | 1 to 8 across routes, including internal repair and tool-search turns |
retry.backoff | {"type": "none"} or {"type": "exponential", "base_delay_ms": 500, "max_delay_ms": 8000, "multiplier": 2} (1 to 10,000; up to 60,000; 1 to 4) |
routing.allow_fallbacks | false keeps the request on the selected route |
routing.route_id | Pin an eligible route by its opaque handle |
SDK retries multiply with gateway retries: set max_retries=0 if your app owns retries.
client.chat.completions.create(
model="gpt-6-luna",
messages=[{"role": "user", "content": "Hello"}],
extra_body={"gateway": {
"retry": {"max_attempts_per_route": 3, "max_total_attempts": 6,
"backoff": {"type": "exponential", "base_delay_ms": 250}},
"routing": {"allow_fallbacks": True},
}},
)Pin a route
Read route_id values from GET /api/models/{slug}/providers with your key (null for inactive or unrouted rows; BYOK rows return the handle of your account's lane). With allow_fallbacks: false the pinned route is the only one; with true it is tried first. A foreign, retired or policy-excluded handle fails explicitly. Pins never bypass credit, rate, location or data-control rules. OpenRouter's provider object also works: only, ignore, order (behind a pinned route) and allow_fallbacks, matched against provider names; a preference no route satisfies is a 400. provider.zdr is on Data controls.
/api/models/{slug}/providerscurl https://api.experientiallabs.ai/api/models/gpt-6-luna/providers \
-H "Authorization: Bearer YOUR_API_KEY" | jq '.providers[] | {provider, route_id}'
curl https://api.experientiallabs.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-6-luna", "messages": [{"role": "user", "content": "Hi"}],
"gateway": {"routing": {"route_id": "ROUTE_ID", "allow_fallbacks": false}}}'Save an order for your org
PUT /api/models/{slug}/waterfall replaces your org's saved chain (model_provider_ids, ordered: deployment ids or byok:{connection_id}); an empty list resets to the default. On a shared model the chain must include one of your own BYOK connections; a platform-only reorder is refused with 422. Send expected_revision (the override_revision you read) to get 409 instead of overwriting a concurrent change. See BYOK.
/api/models/{slug}/waterfallPUT/api/models/{slug}/waterfallcurl https://api.experientiallabs.ai/api/models/claude-opus-5/waterfall \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X PUT https://api.experientiallabs.ai/api/models/claude-opus-5/waterfall \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model_provider_ids": ["byok:CONNECTION_ID", "DEPLOYMENT_ID"], "expected_revision": 0}'