docs: document Infron service tiers

Tiers beyond a model's default are reachable as `<model>:<tier>` ids, so
the chat docs gain a Service tiers section covering what the suffixes
mean, that the tier named is the tier billed, and that a tier can carry
a smaller context window than its siblings.

The listModels return value described a `cost` object with `input` and
`output` keys. No such field is returned — pricing comes back as `costs`
alongside `costs_currency`, keyed per vendor and named by the model's
own `input_cost_key` / `output_cost_key`. Correct the prose and replace
the example with a real entry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/docs/src/AI/chat.md

@@ -27,7 +27,7 @@ A string containing the prompt you want to complete.
 
 An object containing the following properties:
 
-- `model` (String) - The model you want to use for the completion. If not specified, defaults to `gpt-5-nano`. More than 500 models are available from vendors including OpenAI, Anthropic, Google, Alibaba Cloud, xAI, Mistral, OpenRouter, Infron, and others. For a full list, see the [AI models list](https://developer.puter.com/ai/models/) page.
+- `model` (String) - The model you want to use for the completion. If not specified, defaults to `gpt-5-nano`. More than 500 models are available from vendors including OpenAI, Anthropic, Google, Alibaba Cloud, xAI, Mistral, OpenRouter, Infron, and others. For a full list, see the [AI models list](https://developer.puter.com/ai/models/) page. Models sold at more than one service tier accept a tier suffix on the id — see [Service tiers](#service-tiers).
 - `provider` (String) (Optional) - Pin the request to a specific vendor, for example `openrouter` or `infron`. Without it, Puter selects a vendor for the requested model. Call [`puter.ai.listModelProviders()`](/AI/listModelProviders) for the available values, and [`puter.ai.listModels(provider)`](/AI/listModels) for the models a given vendor serves.
 - `stream` (Boolean) - A boolean indicating whether you want to stream the completion. Defaults to `false`.
 - `max_tokens` (Number) - The maximum number of tokens to generate in the completion. By default, the specific model's maximum is used.
@@ -115,6 +115,34 @@ In case of an error, the `Promise` will reject with an error message.
 
 We use different vendors for different models and try to use the best vendor available at the time of the request. Vendors currently include Alibaba Cloud, Anthropic, Azure OpenAI, DeepSeek, Google, Infron, Meta, MiniMax, Mistral, Moonshot AI, OpenAI, OpenRouter, Together AI, xAI, and Z.AI. Call [`puter.ai.listModelProviders()`](/AI/listModelProviders) for the current list, or pass `provider` in the options object to pin a request to one of them.
 
+## Service tiers
+
+Some vendors sell the same model at more than one service tier, trading latency against price. Where they do, Puter exposes each tier as its own model id: append `:flex` or `:priority` to the model name.
+
+```js
+// Default tier
+const a = await puter.ai.chat("Hello", { model: "infron:openai/gpt-6-astra" });
+
+// Same model, flex tier — cheaper, with higher and less predictable latency
+const b = await puter.ai.chat("Hello", { model: "infron:openai/gpt-6-astra:flex" });
+```
+
+A plain model id always means the model's default tier, which is the balanced one. `flex` is the cheapest and is meant for work that tolerates waiting — batch jobs, overnight runs — because requests may be held until capacity frees up. `priority` is the fastest and the most expensive.
+
+The tier named in the id is the tier the request is billed at, and the price [`puter.ai.listModels()`](/AI/listModels) reports for that id is the price you pay for it.
+
+Not every model sells every tier, and a tier can differ from its siblings in more than price — some carry a smaller context window. Each tier is listed as a separate entry, so compare them before picking one:
+
+```js
+const models = await puter.ai.listModels("infron");
+for (const m of models.filter(m => m.id.startsWith("infron:openai/gpt-6-astra"))) {
+    // Cost keys differ by vendor, so read them through input_cost_key / output_cost_key.
+    console.log(m.id, m.costs[m.input_cost_key], m.costs[m.output_cost_key], m.context);
+}
+```
+
+If a model has no tier-suffixed ids in that list, it is sold at a single tier and the plain id is the only way to call it.
+
 ## Response Normalization
 
 Most vendors respond in the OpenAI chat format, where `message.content` is a string and tool calls appear as `message.tool_calls`. Anthropic models historically respond in Anthropic's native format instead, where `message.content` is an array of content blocks such as `[{ type: "text", text: "..." }]`.

src/docs/src/AI/listModels.md

@@ -20,24 +20,31 @@ A string containing the provider you want to list the models for.
 
 ## Return value
 
-Resolves to an array of model objects. Each object always contains `id` and `provider`, and may include fields such as `name`, `aliases`, `context`, `max_tokens`, and a `cost` object (`currency`, `tokens`, `input` and `output` costs in cents). Additional provider-specific capability fields may also be present.
+Resolves to an array of model objects. Each object always contains `id` and `provider`, and may include fields such as `name`, `aliases`, `context` and `max_tokens`.
+
+Pricing is reported as a `costs` object alongside `costs_currency`. The keys of `costs` differ by vendor, so each model names its own with `input_cost_key` and `output_cost_key`; read prices through those rather than hard-coding a key. `costs.tokens` is the number of tokens the prices are quoted per — 1,000,000 throughout — and the remaining keys cover vendor-specific extras such as cache reads. Additional provider-specific capability fields may also be present.
+
+A model sold at several service tiers appears once per tier, under ids suffixed with the tier name (`…:flex`, `…:priority`), each carrying its own `costs` and `context`. See [Service tiers](/AI/chat#service-tiers) for how to pick one.
 
 Example model entry:
 
 ```json
 [
   {
-    "id": "claude-opus-4-8",
+    "id": "claude-opus-4-5-20251101",
     "provider": "claude",
-    "name": "Claude Opus 4.8",
-    "aliases": ["claude-opus-4-8-latest"],
+    "name": "Claude Opus 4.5",
+    "aliases": ["claude-opus-4-5-latest", "claude-opus-4-5"],
     "context": 200000,
     "max_tokens": 64000,
-    "cost": {
-      "currency": "usd-cents",
+    "costs_currency": "usd-cents",
+    "input_cost_key": "input_tokens",
+    "output_cost_key": "output_tokens",
+    "costs": {
       "tokens": 1000000,
-      "input": 500,
-      "output": 2500
+      "input_tokens": 500,
+      "cache_read_input_tokens": 50,
+      "output_tokens": 2500
     }
   }
 ]