@molecule/api-resource-ai-models 1.16.0 → 1.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-10-14T02:53:39.781Z
6
+ Generated: 2026-10-16T23:31:16.001Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-ai-models
10
10
 
11
- > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
12
- > It is written to be read by coding agents as much as by people, and is generated from this
13
- > package's source — edit `src/index.ts` JSDoc, not this file.
14
-
15
11
  AI model catalog resource.
16
12
 
17
13
  Server-side source of truth for available AI models plus an
@@ -22,6 +18,10 @@ directly; authenticated clients fetch the filtered projection over HTTP. The
22
18
  so the configured-model catalog is never disclosed to an unauthenticated
23
19
  caller even if the route's `'authenticate'` middleware is stripped by codegen.
24
20
 
21
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
22
+ > It is written to be read by coding agents as much as by people, and is generated from this
23
+ > package's source — edit `src/index.ts` JSDoc, not this file.
24
+
25
25
  ## Quick Start
26
26
 
27
27
  ```typescript
@@ -48,19 +48,20 @@ npm install @molecule/api-resource-ai-models @molecule/api-bond @molecule/api-i1
48
48
 
49
49
  ### Interfaces
50
50
 
51
- #### `ListModelsResponse`
51
+ #### `ModelTokenRates`
52
52
 
53
- Response shape returned by `GET /ai/models`.
53
+ The four per-MTok token rates a turn bills at (USD).
54
54
 
55
55
  ```typescript
56
- interface ListModelsResponse {
57
- models: ModelDefinition[]
58
- /**
59
- * Per-mode server default model ids for the requester's tier. Optional —
60
- * servers that don't compute tier-aware defaults omit it, and clients fall
61
- * back to generic "default" labeling.
62
- */
63
- defaults?: ModeModelDefaults
56
+ interface ModelTokenRates {
57
+ /** Input price per million uncached tokens in USD. */
58
+ inputPricePerMTok: number
59
+ /** Output price per million tokens in USD. */
60
+ outputPricePerMTok: number
61
+ /** Prompt-cache read price per million tokens in USD. */
62
+ cacheReadPricePerMTok: number
63
+ /** Prompt-cache write price per million tokens in USD. */
64
+ cacheWritePricePerMTok: number
64
65
  }
65
66
  ```
66
67
 
@@ -221,289 +222,7 @@ interface ModelDefinition {
221
222
  * Processing regions this model can run in, as arbitrary region codes; the
222
223
  * FIRST entry is the model's default region. Omit for `['us']` (the platform
223
224
  * default — a single-region US model). A single-entry list pins the model to
224
- * that region regardless of the user's per-model choice (e.g. `['cn']` for a
225
- * model with no US re-host). Dispatch resolves a region to the
226
- * `<provider>-<region>` named bond (`'us'` → the bare `<provider>` bond).
227
- */
228
- regions?: string[]
229
- /**
230
- * Per-region price overrides in USD per MTok, keyed by region code, for
231
- * regions whose host bills differently from the base rates (e.g. a US
232
- * re-host of a Chinese-origin model). The BASE `*PricePerMTok` fields always
233
- * carry the native provider's list prices (what models.dev / the freshness
234
- * gate verify); a region with no entry here bills at the base rates. Omitted
235
- * cache fields fall back to the region's `inputPricePerMTok` (hosts with no
236
- * cache discount / no write premium).
237
- */
238
- regionPricing?: Record<
239
- string,
240
- {
241
- /** Region input price per million uncached tokens in USD. */
242
- inputPricePerMTok: number
243
- /** Region output price per million tokens in USD. */
244
- outputPricePerMTok: number
245
- /** Region prompt-cache read price per million tokens in USD. */
246
- cacheReadPricePerMTok?: number
247
- /** Region prompt-cache write price per million tokens in USD. */
248
- cacheWritePricePerMTok?: number
249
- }
250
- >
251
- /** Input price per million *uncached* (fresh) input tokens in USD. */
252
- inputPricePerMTok: number
253
- /** Output price per million tokens in USD. */
254
- outputPricePerMTok: number
255
- /**
256
- * Price per million prompt-cache *read* (cache-hit) input tokens in USD.
257
- *
258
- * REQUIRED — never omit. Prompt caching is enabled for the agentic loop, so
259
- * for a long conversation the cache-read tokens are the DOMINANT input
260
- * category. Pricing them at `0` (the bug this field fixes) systematically
261
- * under-measures real upstream spend and lets cost-gated budgets be blown
262
- * past their caps. Conventionally a steep discount on `inputPricePerMTok`
263
- * (e.g. Anthropic / OpenAI / DeepSeek bill cache reads at ~0.1×). MUST be
264
- * `<= inputPricePerMTok` — a cache hit is never more expensive than fresh
265
- * input.
266
- */
267
- cacheReadPricePerMTok: number
268
- /**
269
- * Price per million prompt-cache *write* (cache-creation) input tokens in USD.
270
- *
271
- * REQUIRED — never omit. The first time a prefix is cached the provider may
272
- * charge a premium (Anthropic's 5-minute cache write is ~1.25× input);
273
- * providers that auto-cache at no extra charge (OpenAI, DeepSeek) set this
274
- * equal to `inputPricePerMTok`. MUST be `>= inputPricePerMTok` — a cache
275
- * write is never cheaper than fresh input. Only the Anthropic bond currently
276
- * emits `cacheCreationInputTokens`, but every model declares this so a new
277
- * cache-emitting bond can never silently bill cache writes at `0`.
278
- */
279
- cacheWritePricePerMTok: number
280
- /**
281
- * Optional provider peak-hour pricing: during the listed UTC windows, ALL of
282
- * this model's token prices (input, output, cache read/write) bill at
283
- * `multiplier × ` the listed rates. Metering MUST price each request by its
284
- * own timestamp via `priceMultiplierAt()` — never assume the flat rate — or
285
- * peak-hour usage is under-metered and the platform eats the difference
286
- * (e.g. DeepSeek's announced 2× Beijing-business-hours pricing).
287
- *
288
- * Windows are minutes-since-midnight UTC, half-open `[start, end)`; a window
289
- * may wrap midnight (`start > end`).
290
- *
291
- * `daysOfWeekUtc` restricts a window to certain UTC weekdays (`0` = Sunday …
292
- * `6` = Saturday); omitted means every day. A provider that prices its peak
293
- * by BUSINESS hours qualifies them by day, and a day-less window over-bills
294
- * every weekend hour inside it at the full multiplier — DeepSeek's card
295
- * carried no day qualifier when these windows landed on 2026-08-16 and added
296
- * "Monday through Friday" by 2026-08-31, which is exactly the 2× weekend
297
- * over-bill this field exists to prevent. A wrapping window belongs to the
298
- * day it STARTS on, so its post-midnight tail is still matched against the
299
- * previous day.
300
- *
301
- * `excludedDatesUtc` lists `YYYY-MM-DD` dates on which no window applies —
302
- * a provider's public holidays. DeepSeek's peak excludes Chinese public
303
- * holidays (its pricing page, 2026-09-23); without the list those days bill
304
- * at 2× while the provider charges off-peak. A date is matched against the
305
- * day a window STARTS on (UTC), like `daysOfWeekUtc`. The list is DATA that
306
- * runs out: check-model-freshness warns when the coming year has no dates.
307
- *
308
- * `rule` is the provider's own sentence defining these windows, verbatim,
309
- * and the page that publishes it. check-model-freshness re-reads the page on
310
- * every run and warns the moment the sentence changes — the windows are only
311
- * as right as the last reading, and DeepSeek has amended its rule twice
312
- * (a weekday qualifier by 2026-08-31, a holiday exclusion by 2026-09-23)
313
- * without anything here noticing.
314
- */
315
- peakPricing?: {
316
- windows: { startMinuteUtc: number; endMinuteUtc: number; daysOfWeekUtc?: number[] }[]
317
- multiplier: number
318
- excludedDatesUtc?: string[]
319
- rule?: { url: string; text: string }
320
- }
321
- /**
322
- * A price change the provider has ANNOUNCED with a dated effective instant,
323
- * staged ahead of time. Until `effectiveFrom` the model bills at the base
324
- * rates above; from that instant on, these rates replace them.
325
- *
326
- * This exists because the freshness gate can only ever see prices that are
327
- * ALREADY live: it diffs the catalog against models.dev's *current* rates, so
328
- * a change announced today and effective in three days is invisible to it
329
- * until after it lands — and the cron runs every 8h, so the catalog would
330
- * under-meter for up to a third of a day at whatever the new rate is. Landing
331
- * the new numbers early is not an option either: that over-bills every turn
332
- * until the switch (the exact mistake the removed DeepSeek peak windows made
333
- * for weeks against the free-tier default model). Staging with a timestamp is
334
- * the only form that is correct on BOTH sides of the instant, and it needs no
335
- * one awake at the switch.
336
- *
337
- * Applies to the BASE rates only — a `regionPricing` entry is a different
338
- * host's rate card (a US re-host does not reprice because the native provider
339
- * did) and is never touched by a scheduled change.
340
- *
341
- * `peakPricing` here, when declared, replaces the model's peak windows from
342
- * the same instant; when omitted, the model's existing windows carry through
343
- * unchanged. To schedule the END of peak pricing, declare an explicit
344
- * `{ windows: [], multiplier: 1 }`.
345
- *
346
- * `longContextPricing` here, when declared, replaces the model's long-context
347
- * band from the same instant; when omitted, the existing band carries through
348
- * unchanged. The band that bills AFTER the instant (declared here, or the
349
- * carried-through one) must stay strictly dearer than the scheduled base
350
- * rates — the catalog invariant test enforces that at staging time, so a
351
- * banded model's price change can never land with a stale band silently
352
- * under-metering its most expensive prompts.
353
- *
354
- * Resolution is `effectiveBaseRates()` / `effectivePeakPricing()` /
355
- * `effectiveLongContextPricing()`, and every
356
- * consumer reaches it through `modelRegionRates()` / `priceMultiplierAt()` /
357
- * the `withEffectivePricing()` projection the list handler serves — so a
358
- * scheduled change lands everywhere at once with no follow-up edit. Once the
359
- * instant has passed, fold the rates into the base fields and delete this
360
- * (the freshness gate now verifies them against models.dev normally).
361
- */
362
- scheduledPricing?: {
363
- /** ISO-8601 UTC instant the new rates take effect. */
364
- effectiveFrom: string
365
- /** Input price per million *uncached* tokens in USD, from `effectiveFrom`. */
366
- inputPricePerMTok: number
367
- /** Output price per million tokens in USD, from `effectiveFrom`. */
368
- outputPricePerMTok: number
369
- /** Prompt-cache *read* price per million tokens in USD, from `effectiveFrom`. */
370
- cacheReadPricePerMTok: number
371
- /** Prompt-cache *write* price per million tokens in USD, from `effectiveFrom`. */
372
- cacheWritePricePerMTok: number
373
- /** Peak-hour pricing from `effectiveFrom` (omitted → existing windows carry through). */
374
- peakPricing?: {
375
- windows: { startMinuteUtc: number; endMinuteUtc: number; daysOfWeekUtc?: number[] }[]
376
- multiplier: number
377
- excludedDatesUtc?: string[]
378
- rule?: { url: string; text: string }
379
- }
380
- /**
381
- * Long-context band from `effectiveFrom` (omitted → the model's existing
382
- * band carries through unchanged). Indexed off the model-level field so
383
- * the two shapes can never drift apart.
384
- */
385
- longContextPricing?: ModelDefinition['longContextPricing']
386
- /** Where the change was announced, for the re-verify pass after it lands. */
387
- source?: string
388
- }
389
- /**
390
- * Fast-mode ("priority speed") pricing — the per-MTok rates billed when a
391
- * request runs with the provider's fast/priority tier (e.g. Anthropic's
392
- * `speed: "fast"` research preview: same model, up to ~2.5× output speed, at
393
- * premium pricing). PRESENCE of this field is the capability flag: a model
394
- * without it does not support fast mode, and metering/UI/dispatch all key off
395
- * that. All four fields are required for the same never-under-meter reasons
396
- * as the base rates. Metering MUST price a turn by the speed the provider
397
- * REPORTS it ran at (`TokenUsage.speed`), not the speed requested — a
398
- * fast-mode 429 that falls back to standard must not bill 2×.
399
- */
400
- fastPricing?: {
401
- /** Fast-mode input price per million uncached tokens in USD. */
402
- inputPricePerMTok: number
403
- /** Fast-mode output price per million tokens in USD. */
404
- outputPricePerMTok: number
405
- /** Fast-mode prompt-cache read price per million tokens in USD. */
406
- cacheReadPricePerMTok: number
407
- /** Fast-mode prompt-cache write price per million tokens in USD. */
408
- cacheWritePricePerMTok: number
409
- }
410
- /**
411
- * Long-context pricing — models priced BY PROMPT LENGTH (Claude Haiku 5.5: 5× above 100K prompt tokens). A request
412
- * whose prompt (fresh input + cache read + cache write tokens) EXCEEDS `aboveInputTokens` bills ALL of its tokens at
413
- * these rates, not just the excess. Resolved by `modelRegionRates(model, region, at, promptTokens)`; callers must pass
414
- * ONE provider call's prompt size, never a multi-call sum. All four rates are required for the same never-under-meter
415
- * reasons as the base rates. A staged `scheduledPricing` change can carry its own replacement band from the same
416
- * instant (omitted → this band carries through) — resolved by `effectiveLongContextPricing()`. A `regionPricing`
417
- * override is a different host's complete rate card, so the band never applies on top of an override.
418
- */
419
- longContextPricing?: {
420
- /** A prompt larger than this many tokens bills at the long-context rates. */
421
- aboveInputTokens: number
422
- /** Long-context input price per million uncached tokens in USD. */
423
- inputPricePerMTok: number
424
- /** Long-context output price per million tokens in USD. */
425
- outputPricePerMTok: number
426
- /** Long-context prompt-cache read price per million tokens in USD. */
427
- cacheReadPricePerMTok: number
428
- /** Long-context prompt-cache write price per million tokens in USD. */
429
- cacheWritePricePerMTok: number
430
- }
431
- /** Reliable knowledge cutoff date (YYYY-MM-DD). */
432
- knowledgeCutoff: string
433
- /**
434
- * When the model was (or will be) deprecated (YYYY-MM-DD).
435
- *
436
- * Past dates: still selectable, but the picker tucks them into an "Older
437
- * models" section so newcomers default to current entries. Saved selections
438
- * (a user previously picked this) keep working. Future dates: still treated
439
- * as current — useful for scheduling a deprecation in advance.
440
- *
441
- * Omit entirely for current models.
442
- */
443
- deprecatedAt?: string
444
- /**
445
- * Whether this model is fully disabled — removed from selection and the
446
- * public listing while remaining priceable for historical usage.
447
- *
448
- * Stronger than {@link deprecatedAt}: a deprecated model is still selectable
449
- * (the picker just tucks it into an "Older models" section), whereas a
450
- * disabled model vanishes from every *exposure* surface — it is excluded from
451
- * `MODEL_IDS`, `getAvailableModels()`, the `GET /ai/models` listing, and the
452
- * client-side free-tier / deprecation-partition helpers. Use it for a model
453
- * the provider has retired or deprecated (e.g. `grok-code-fast-1`).
454
- *
455
- * `getModel(id)` STILL returns a disabled entry so a saved selection or a
456
- * historical usage row can always be priced — NEVER delete a disabled model,
457
- * or its past usage silently meters as free. Omit entirely for active models.
458
- */
459
- disabled?: boolean
460
- /**
461
- * The id of the NEWER-generation model that replaces this one, set on the
462
- * OLDER entry and naming its successor (e.g. `qwen3.7-max` carries
463
- * `supersededBy: 'qwen3.8-max'`).
464
- *
465
- * A superseded model is NOT selectable — like {@link disabled} it is excluded
466
- * from `MODEL_IDS`, `getAvailableModels()`, the `GET /ai/models` listing and
467
- * the client-side picker partitions, so a user is only ever offered the
468
- * newest generation of a family. It differs from `disabled` in *why* and in
469
- * what it points at: a disabled model is one the provider retired (it can no
470
- * longer answer), whereas a superseded model is usually still served upstream
471
- * and simply has nothing to offer over its successor — and the successor id
472
- * is a real migration target, so a saved selection can resolve forward
473
- * (`resolveSelectableModelId`) instead of silently falling back to the
474
- * platform default.
475
- *
476
- * `getModel(id)` STILL returns a superseded entry — historical usage must stay
477
- * priceable, so NEVER delete one.
478
- *
479
- * Set this ONLY when the successor covers the same TIER. A cheaper or
480
- * specialist tier with no newer equivalent is NOT superseded merely because
481
- * its version number is lower (Google's sole pro tier `gemini-3.1-pro-preview`
482
- * alongside the newer flash flagship; `qwen3-coder-plus`; `kimi-k2.7-code`) —
483
- * hiding those would leave a provider with no cheap option. Mark those
484
- * {@link deprecatedAt} at most. The invariant is enforced by
485
- * `__tests__/lookup.test.ts`: two selectable models of the same family at
486
- * different versions fail unless listed there as a documented exception.
487
- */
488
- supersededBy?: string
489
- }
490
- ```
491
-
492
- #### `ModelTokenRates`
493
-
494
- The four per-MTok token rates a turn bills at (USD).
495
-
496
- ```typescript
497
- interface ModelTokenRates {
498
- /** Input price per million uncached tokens in USD. */
499
- inputPricePerMTok: number
500
- /** Output price per million tokens in USD. */
501
- outputPricePerMTok: number
502
- /** Prompt-cache read price per million tokens in USD. */
503
- cacheReadPricePerMTok: number
504
- /** Prompt-cache write price per million tokens in USD. */
505
- cacheWritePricePerMTok: number
506
- }
225
+ // … truncated — the full declaration is in node_modules/@molecule/api-resource-ai-models/dist/types.d.ts
507
226
  ```
508
227
 
509
228
  #### `ModeModelDefaults`
@@ -527,6 +246,22 @@ interface ModeModelDefaults {
527
246
  }
528
247
  ```
529
248
 
249
+ #### `ListModelsResponse`
250
+
251
+ Response shape returned by `GET /ai/models`.
252
+
253
+ ```typescript
254
+ interface ListModelsResponse {
255
+ models: ModelDefinition[]
256
+ /**
257
+ * Per-mode server default model ids for the requester's tier. Optional —
258
+ * servers that don't compute tier-aware defaults omit it, and clients fall
259
+ * back to generic "default" labeling.
260
+ */
261
+ defaults?: ModeModelDefaults
262
+ }
263
+ ```
264
+
530
265
  ### Types
531
266
 
532
267
  #### `AIProviderID`
@@ -578,101 +313,82 @@ type EffortLevel = string
578
313
 
579
314
  ### Functions
580
315
 
581
- #### `effectiveBaseRates(modelDef, at)`
316
+ #### `list(_req, res)`
582
317
 
583
- A model's BASE token rates in effect at a given instant — the staged
584
- {@link ModelDefinition.scheduledPricing} rates once their `effectiveFrom` has
585
- passed, else the base fields.
318
+ Returns models whose `provider` has a bond registered under the `'ai'`
319
+ category. When no AI providers are bonded the response is `{ models: [] }`,
320
+ which signals a misconfigured server rather than masking the issue.
586
321
 
587
- These are the native provider's rates. A `regionPricing` override is a
588
- different host's rate card and is resolved separately by
589
- {@link modelRegionRates}.
322
+ Fails closed with `401` when there is no authenticated session, so the model
323
+ catalog is never disclosed to an unauthenticated caller even if the route's
324
+ `'authenticate'` middleware is dropped by codegen.
590
325
 
591
326
  ```typescript
592
- function effectiveBaseRates(modelDef: ModelDefinition, at?: Date): ModelTokenRates
327
+ function list(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>
593
328
  ```
594
329
 
595
- - `modelDef` — The model definition.
596
- - `at` — The instant to price at (defaults to now).
330
+ - `_req` — The request object (unused).
331
+ - `res` — The response object.
597
332
 
598
- **Returns:** The base rates in effect at that instant.
333
+ #### `isSelectableModel(model)`
599
334
 
600
- #### `effectiveLongContextPricing(modelDef, at)`
335
+ Whether a model may be offered for selection: not `disabled` (retired
336
+ upstream) and not `supersededBy` a newer generation of its own family. Both
337
+ kinds stay in the catalog for pricing — this predicate is the single place
338
+ that decides _exposure_, so every listing/validation surface agrees.
601
339
 
602
- A model's long-context band in effect at a given instant: the staged
603
- {@link ModelDefinition.scheduledPricing} `longContextPricing` once its
604
- `effectiveFrom` has passed (when that entry declares one — an omitted one
605
- leaves the model's existing band in force), else the model's own
606
- {@link ModelDefinition.longContextPricing}.
340
+ ```typescript
341
+ function isSelectableModel(model: Pick<ModelDefinition, 'disabled' | 'supersededBy'>): boolean
342
+ ```
607
343
 
608
- This is what lets a banded model's price change move BOTH cards at once:
609
- resolving the static band against landed scheduled base rates would leave
344
+ - `model` — The model definition (or the two flags from one).
610
345
 
611
- > threshold prompts on a stale card (possibly cheaper than the new base —
612
- > silently under-metering the most expensive traffic).
346
+ **Returns:** True when the model may be listed and chosen.
347
+
348
+ #### `resolveSelectableModelId(id)`
349
+
350
+ Resolve a model id FORWARD to the selectable model that replaces it, following
351
+ the {@link ModelDefinition.supersededBy} chain (a saved `qwen3.7-max` →
352
+ `qwen3.8-max`). Lets a persisted selection keep the user's intent — the same
353
+ tier from the same provider — instead of falling back to the platform default
354
+ once the older generation stops being offered.
613
355
 
614
356
  ```typescript
615
- function effectiveLongContextPricing(
616
- modelDef: ModelDefinition,
617
- at?: Date,
618
- ):
619
- | {
620
- aboveInputTokens: number
621
- inputPricePerMTok: number
622
- outputPricePerMTok: number
623
- cacheReadPricePerMTok: number
624
- cacheWritePricePerMTok: number
625
- }
626
- | undefined
357
+ function resolveSelectableModelId(id: string): string | undefined
627
358
  ```
628
359
 
629
- - `modelDef` — The model definition.
630
- - `at` — The instant to evaluate (defaults to now).
360
+ - `id` — The persisted model id.
631
361
 
632
- **Returns:** The long-context band in effect, or `undefined` when none is.
362
+ **Returns:** The selectable successor's id, the id itself when it is already selectable, or `undefined` for an unknown or `disabled` model (nothing to forward to).
633
363
 
634
- #### `effectiveModelRegion(modelDef, requested)`
364
+ #### `getModel(id)`
635
365
 
636
- Resolve a model's effective processing region: the requested region when the
637
- model's {@link ModelDefinition.regions} list offers it, else the model's
638
- DEFAULT region (the first listed; `'us'` when the catalog omits regions,
639
- which also covers unknown model ids). A single-entry `regions` list pins the
640
- model regardless of the request (e.g. a model with no US re-host).
366
+ Look up a model definition by ID.
367
+
368
+ Returns `disabled` and `supersededBy` models too: a saved selection or a
369
+ historical usage row may reference a since-retired or since-superseded model,
370
+ and it must stay priceable. Use {@link MODEL_IDS} / {@link getAvailableModels}
371
+ (or {@link isSelectableModel}) to decide what is _selectable_.
641
372
 
642
373
  ```typescript
643
- function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?: string): string
374
+ function getModel(id: string): ModelDefinition | undefined
644
375
  ```
645
376
 
646
- - `modelDef` — The model definition (or undefined for unknown ids).
647
- - `requested` — The user's per-model region choice, if any.
377
+ - `id` — The API model ID.
648
378
 
649
- **Returns:** The effective region code.
379
+ **Returns:** The model definition, or `undefined` if not found.
650
380
 
651
- #### `effectivePeakPricing(modelDef, at)`
381
+ #### `getModelsByProvider(provider)`
652
382
 
653
- A model's peak-hour pricing in effect at a given instant: the staged
654
- {@link ModelDefinition.scheduledPricing} `peakPricing` once its
655
- `effectiveFrom` has passed (when that entry declares one — an omitted one
656
- leaves the existing windows in force), else the model's own `peakPricing`.
383
+ Get all models for a specific provider.
657
384
 
658
385
  ```typescript
659
- function effectivePeakPricing(
660
- modelDef: ModelDefinition,
661
- at?: Date,
662
- ):
663
- | {
664
- windows: { startMinuteUtc: number; endMinuteUtc: number; daysOfWeekUtc?: number[] }[]
665
- multiplier: number
666
- excludedDatesUtc?: string[]
667
- rule?: { url: string; text: string }
668
- }
669
- | undefined
386
+ function getModelsByProvider(provider: AIProviderID): readonly ModelDefinition[]
670
387
  ```
671
388
 
672
- - `modelDef` — The model definition.
673
- - `at` — The instant to evaluate (defaults to now).
389
+ - `provider` — The provider ID.
674
390
 
675
- **Returns:** The peak-pricing config in effect, or `undefined` when none is.
391
+ **Returns:** Array of model definitions for that provider.
676
392
 
677
393
  #### `getAvailableModels(availableProviders)`
678
394
 
@@ -692,105 +408,105 @@ function getAvailableModels(
692
408
 
693
409
  **Returns:** Selectable models whose provider is in the available set.
694
410
 
695
- #### `getModel(id)`
411
+ #### `effectiveBaseRates(modelDef, at)`
696
412
 
697
- Look up a model definition by ID.
413
+ A model's BASE token rates in effect at a given instant — the staged
414
+ {@link ModelDefinition.scheduledPricing} rates once their `effectiveFrom` has
415
+ passed, else the base fields.
698
416
 
699
- Returns `disabled` and `supersededBy` models too: a saved selection or a
700
- historical usage row may reference a since-retired or since-superseded model,
701
- and it must stay priceable. Use {@link MODEL_IDS} / {@link getAvailableModels}
702
- (or {@link isSelectableModel}) to decide what is _selectable_.
417
+ These are the native provider's rates. A `regionPricing` override is a
418
+ different host's rate card and is resolved separately by
419
+ {@link modelRegionRates}.
703
420
 
704
421
  ```typescript
705
- function getModel(id: string): ModelDefinition | undefined
422
+ function effectiveBaseRates(modelDef: ModelDefinition, at?: Date): ModelTokenRates
706
423
  ```
707
424
 
708
- - `id` — The API model ID.
425
+ - `modelDef` — The model definition.
426
+ - `at` — The instant to price at (defaults to now).
709
427
 
710
- **Returns:** The model definition, or `undefined` if not found.
428
+ **Returns:** The base rates in effect at that instant.
711
429
 
712
- #### `getModelsByProvider(provider)`
430
+ #### `effectivePeakPricing(modelDef, at)`
713
431
 
714
- Get all models for a specific provider.
432
+ A model's peak-hour pricing in effect at a given instant: the staged
433
+ {@link ModelDefinition.scheduledPricing} `peakPricing` once its
434
+ `effectiveFrom` has passed (when that entry declares one — an omitted one
435
+ leaves the existing windows in force), else the model's own `peakPricing`.
715
436
 
716
437
  ```typescript
717
- function getModelsByProvider(provider: AIProviderID): readonly ModelDefinition[]
438
+ function effectivePeakPricing(
439
+ modelDef: ModelDefinition,
440
+ at?: Date,
441
+ ):
442
+ | {
443
+ windows: { startMinuteUtc: number; endMinuteUtc: number; daysOfWeekUtc?: number[] }[]
444
+ multiplier: number
445
+ excludedDatesUtc?: string[]
446
+ rule?: { url: string; text: string }
447
+ }
448
+ | undefined
718
449
  ```
719
450
 
720
- - `provider` — The provider ID.
721
-
722
- **Returns:** Array of model definitions for that provider.
723
-
724
- #### `isSelectableModel(model)`
725
-
726
- Whether a model may be offered for selection: not `disabled` (retired
727
- upstream) and not `supersededBy` a newer generation of its own family. Both
728
- kinds stay in the catalog for pricing — this predicate is the single place
729
- that decides _exposure_, so every listing/validation surface agrees.
730
-
731
- ```typescript
732
- function isSelectableModel(model: Pick<ModelDefinition, 'disabled' | 'supersededBy'>): boolean
733
- ```
451
+ - `modelDef` — The model definition.
452
+ - `at` — The instant to evaluate (defaults to now).
734
453
 
735
- - `model` — The model definition (or the two flags from one).
454
+ **Returns:** The peak-pricing config in effect, or `undefined` when none is.
736
455
 
737
- **Returns:** True when the model may be listed and chosen.
456
+ #### `effectiveLongContextPricing(modelDef, at)`
738
457
 
739
- #### `list(_req, res)`
458
+ A model's long-context band in effect at a given instant: the staged
459
+ {@link ModelDefinition.scheduledPricing} `longContextPricing` once its
460
+ `effectiveFrom` has passed (when that entry declares one — an omitted one
461
+ leaves the model's existing band in force), else the model's own
462
+ {@link ModelDefinition.longContextPricing}.
740
463
 
741
- Returns models whose `provider` has a bond registered under the `'ai'`
742
- category. When no AI providers are bonded the response is `{ models: [] }`,
743
- which signals a misconfigured server rather than masking the issue.
464
+ This is what lets a banded model's price change move BOTH cards at once:
465
+ resolving the static band against landed scheduled base rates would leave
744
466
 
745
- Fails closed with `401` when there is no authenticated session, so the model
746
- catalog is never disclosed to an unauthenticated caller even if the route's
747
- `'authenticate'` middleware is dropped by codegen.
467
+ > threshold prompts on a stale card (possibly cheaper than the new base —
468
+ > silently under-metering the most expensive traffic).
748
469
 
749
470
  ```typescript
750
- function list(_req: MoleculeRequest, res: MoleculeResponse): Promise<void>
471
+ function effectiveLongContextPricing(
472
+ modelDef: ModelDefinition,
473
+ at?: Date,
474
+ ):
475
+ | {
476
+ aboveInputTokens: number
477
+ inputPricePerMTok: number
478
+ outputPricePerMTok: number
479
+ cacheReadPricePerMTok: number
480
+ cacheWritePricePerMTok: number
481
+ }
482
+ | undefined
751
483
  ```
752
484
 
753
- - `_req` — The request object (unused).
754
- - `res` — The response object.
485
+ - `modelDef` — The model definition.
486
+ - `at` — The instant to evaluate (defaults to now).
755
487
 
756
- #### `modelRegionRates(modelDef, requested, at, promptTokens)`
488
+ **Returns:** The long-context band in effect, or `undefined` when none is.
757
489
 
758
- The token rates for a model in a given processing region: the model's
759
- {@link ModelDefinition.regionPricing} override for the region when one
760
- exists, else the base rates in effect at `at` (the native provider's list
761
- prices, including any staged {@link ModelDefinition.scheduledPricing} change
762
- that has landed). Omitted cache fields in an override fall back to the
763
- override's input price (hosts with no cache discount / no write premium). The
764
- region is resolved via {@link effectiveModelRegion}, so callers may pass the
765
- raw user choice.
490
+ #### `withEffectivePricing(modelDef, at)`
766
491
 
767
- `at` defaults to NOW rather than being required, so an existing caller cannot
768
- keep billing a superseded rate by omitting it — metering should still pass
769
- each request's own timestamp, the same way it must for
770
- {@link priceMultiplierAt}.
492
+ A model projected onto the pricing in effect at a given instant: the staged
493
+ {@link ModelDefinition.scheduledPricing} rates folded into the base fields
494
+ (and its peak windows into `peakPricing`) once effective, with the staged
495
+ entry stripped.
771
496
 
772
- A model priced by prompt length ({@link ModelDefinition.longContextPricing}) bills a request whose
773
- `promptTokens` EXCEED the threshold at the long-context rates (all of its tokens, not the excess). Pass ONE
774
- provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply. The
775
- band itself is resolved at `at` via {@link effectiveLongContextPricing} — a landed
776
- {@link ModelDefinition.scheduledPricing} change that declares its own band replaces the static one from
777
- the same instant (an omitted one carries the static band through).
497
+ This is what the `GET /ai/models` handler serves, so a client renders the
498
+ rates that are actually billing right now without needing to resolve a
499
+ schedule against its own clock — the server's clock is the only one that
500
+ decides when a price change lands.
778
501
 
779
502
  ```typescript
780
- function modelRegionRates(
781
- modelDef: ModelDefinition,
782
- requested?: string,
783
- at?: Date,
784
- promptTokens?: number,
785
- ): ModelTokenRates
503
+ function withEffectivePricing(modelDef: ModelDefinition, at?: Date): ModelDefinition
786
504
  ```
787
505
 
788
506
  - `modelDef` — The model definition.
789
- - `requested` — The user's per-model region choice, if any.
790
- - `at` — The instant to price at (defaults to now).
791
- - `promptTokens` — The request's prompt size in tokens, when the caller knows it.
507
+ - `at` — The instant to project at (defaults to now).
792
508
 
793
- **Returns:** The region-effective rates.
509
+ **Returns:** The model with effective pricing and no `scheduledPricing`.
794
510
 
795
511
  #### `priceMultiplierAt(modelDef, at, region)`
796
512
 
@@ -820,42 +536,61 @@ function priceMultiplierAt(modelDef: ModelDefinition | undefined, at: Date, regi
820
536
 
821
537
  **Returns:** The multiplier (`1` outside peak windows, when none are declared, or in a region that prices off its own override).
822
538
 
823
- #### `resolveSelectableModelId(id)`
539
+ #### `effectiveModelRegion(modelDef, requested)`
824
540
 
825
- Resolve a model id FORWARD to the selectable model that replaces it, following
826
- the {@link ModelDefinition.supersededBy} chain (a saved `qwen3.7-max` →
827
- `qwen3.8-max`). Lets a persisted selection keep the user's intent — the same
828
- tier from the same provider — instead of falling back to the platform default
829
- once the older generation stops being offered.
541
+ Resolve a model's effective processing region: the requested region when the
542
+ model's {@link ModelDefinition.regions} list offers it, else the model's
543
+ DEFAULT region (the first listed; `'us'` when the catalog omits regions,
544
+ which also covers unknown model ids). A single-entry `regions` list pins the
545
+ model regardless of the request (e.g. a model with no US re-host).
830
546
 
831
547
  ```typescript
832
- function resolveSelectableModelId(id: string): string | undefined
548
+ function effectiveModelRegion(modelDef: ModelDefinition | undefined, requested?: string): string
833
549
  ```
834
550
 
835
- - `id` — The persisted model id.
551
+ - `modelDef` — The model definition (or undefined for unknown ids).
552
+ - `requested` — The user's per-model region choice, if any.
836
553
 
837
- **Returns:** The selectable successor's id, the id itself when it is already selectable, or `undefined` for an unknown or `disabled` model (nothing to forward to).
554
+ **Returns:** The effective region code.
838
555
 
839
- #### `withEffectivePricing(modelDef, at)`
556
+ #### `modelRegionRates(modelDef, requested, at, promptTokens)`
840
557
 
841
- A model projected onto the pricing in effect at a given instant: the staged
842
- {@link ModelDefinition.scheduledPricing} rates folded into the base fields
843
- (and its peak windows into `peakPricing`) once effective, with the staged
844
- entry stripped.
558
+ The token rates for a model in a given processing region: the model's
559
+ {@link ModelDefinition.regionPricing} override for the region when one
560
+ exists, else the base rates in effect at `at` (the native provider's list
561
+ prices, including any staged {@link ModelDefinition.scheduledPricing} change
562
+ that has landed). Omitted cache fields in an override fall back to the
563
+ override's input price (hosts with no cache discount / no write premium). The
564
+ region is resolved via {@link effectiveModelRegion}, so callers may pass the
565
+ raw user choice.
845
566
 
846
- This is what the `GET /ai/models` handler serves, so a client renders the
847
- rates that are actually billing right now without needing to resolve a
848
- schedule against its own clock — the server's clock is the only one that
849
- decides when a price change lands.
567
+ `at` defaults to NOW rather than being required, so an existing caller cannot
568
+ keep billing a superseded rate by omitting it — metering should still pass
569
+ each request's own timestamp, the same way it must for
570
+ {@link priceMultiplierAt}.
571
+
572
+ A model priced by prompt length ({@link ModelDefinition.longContextPricing}) bills a request whose
573
+ `promptTokens` EXCEED the threshold at the long-context rates (all of its tokens, not the excess). Pass ONE
574
+ provider call's prompt size (fresh input + cache read + cache write); omit it and the base rates apply. The
575
+ band itself is resolved at `at` via {@link effectiveLongContextPricing} — a landed
576
+ {@link ModelDefinition.scheduledPricing} change that declares its own band replaces the static one from
577
+ the same instant (an omitted one carries the static band through).
850
578
 
851
579
  ```typescript
852
- function withEffectivePricing(modelDef: ModelDefinition, at?: Date): ModelDefinition
580
+ function modelRegionRates(
581
+ modelDef: ModelDefinition,
582
+ requested?: string,
583
+ at?: Date,
584
+ promptTokens?: number,
585
+ ): ModelTokenRates
853
586
  ```
854
587
 
855
588
  - `modelDef` — The model definition.
856
- - `at` — The instant to project at (defaults to now).
589
+ - `requested` — The user's per-model region choice, if any.
590
+ - `at` — The instant to price at (defaults to now).
591
+ - `promptTokens` — The request's prompt size in tokens, when the caller knows it.
857
592
 
858
- **Returns:** The model with effective pricing and no `scheduledPricing`.
593
+ **Returns:** The region-effective rates.
859
594
 
860
595
  ### Constants
861
596
 
@@ -899,330 +634,8 @@ Effort is each model's OWN native value — there is no abstract scale (see
899
634
  - A model with a controllable token budget but no native level names (e.g.
900
635
  Claude Haiku 4.5's `budget_tokens`, Qwen's `thinking_budget`) lists
901
636
  scaled-budget labels (`['4K', '8K', '16K', '32K']`) with `effortBudgetTokens`
902
- mapping each label to the token budget it sends.
903
- - A model whose reasoning is fixed (always-on or on/off only, no depth
904
- control) carries `thinkingConfigurable: false` and OMITS both fields —
905
- there is nothing to tune.
906
-
907
- ONE GENERATION PER FAMILY. When a provider ships a newer generation of a
908
- model line, the older entry gets `supersededBy: '<newer id>'` and stops being
909
- offered — the picker never shows both `qwen3.7-max` and `qwen3.8-max`. The
910
- entry is NEVER deleted: `getModel()` still resolves it so saved selections and
911
- historical usage stay priceable, and a persisted id resolves forward to the
912
- successor. Supersede only within the same TIER: a cheaper or specialist model
913
- with no newer equivalent (`gemini-3.1-pro-preview`, `qwen3-coder-plus`,
914
- `kimi-k2.7-code`, `grok-build-0.1`) keeps at most `deprecatedAt`, so every
915
- provider keeps a real choice. `__tests__/lookup.test.ts` fails on any two
916
- selectable models of one family at different versions that aren't a
917
- documented exception.
918
-
919
- Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
920
- 2026-07-30 GPT-5.6 repricing — cross-check prices against models.dev with
921
- `npm run check:model-freshness` from the workspace root):
922
-
923
- - Web search (`webSearchPricePer1k`, billed per search on top of tokens;
924
- verified 2026-09-25 on each provider's pricing page): Anthropic $10 per
925
- 1,000 searches (failed searches are not billed); OpenAI $10 per 1,000
926
- web_search_call items on reasoning models; Google $14 per 1,000 search
927
- queries after 5,000/month free, shared across the account, so not
928
- modeled; Z.ai $0.01 per use, but its search never runs on a Synthase-shaped
929
- request, so GLM entries carry no webSearchToolType.
930
- - Anthropic: https://platform.claude.com/docs/en/about-claude/models/overview
931
- - /docs/en/build-with-claude/effort (fable-5-1 / opus-5-5 / sonnet-5-5
932
- current as of 2026-09-29 — see the dated notes below; historically fable-5 / opus-5 / sonnet-5 current;
933
- opus-4-8 superseded by opus-5 at identical pricing but still served — it is
934
- the recommended refusal-fallback model; effort ladder on all three current
935
- models is low|medium|high|xhigh|max; budget_tokens 400s on 4.7+)
936
- (re-verified 2026-08-06: added opus-4-7 — legacy but Active, $5/$25,
937
- cache $0.50/$6.25, 1M ctx / 128K out per the overview + pricing pages;
938
- models.dev first listed it 2026-08-06)
939
- (re-verified 2026-09-01 on /docs/en/about-claude/pricing: sonnet-5's
940
- $2/$10 launch pricing is now the STANDARD price — that page's own note
941
- reads "The previously scheduled increase to $3/$15 per million input/output
942
- tokens on September 1, 2026 will not occur." Catalog moved off the
943
- never-under-charge $3/$15 to $2/$10, cache $0.20/$2.50, and the
944
- KNOWN_DIVERGENCES entry was deleted. Every other Anthropic entry on that
945
- page is unchanged: fable-5 $10/$50 ($1/$12.50), opus-5 / opus-4-8 /
946
- opus-4-7 / opus-4-6 $5/$25 ($0.50/$6.25), sonnet-4-6 $3/$15 ($0.30/$3.75),
947
- haiku-4-5 $1/$5 ($0.10/$1.25).)
948
- (re-verified 2026-09-01 — ADDED claude-fable-5-1, released that day and
949
- listed as "Active (latest)" on /docs/en/models/fable-5-1/overview, which
950
- moves claude-fable-5 to "Legacy models (still available)" → superseded.
951
- Same tier and same $10/$50 as fable-5, 1M ctx / 128K out, adaptive
952
- thinking always on, effort low|medium|high|xhigh|max default high, vision
953
- - tools + caching, reliable knowledge cutoff Jun 2026. The one price that
954
- is NOT the fleet ratio: cache read is $0.25/MTok — the pricing page
955
- footnotes fable-5-1 / mythos-5-1 as 0.025× input where every other model
956
- is 0.1×; cache write is the usual 1.25× ($12.50). Not modeled: the beta
957
- per-message effort / turn-scoped system messages / `display: "updates"`,
958
- and the three fable-5 → fable-5-1 breaking changes (forced tool_choice
959
- any/tool now 400s, thinking blocks are model-bound, editing earlier turns
960
- invalidates them) — Synthase sends tool_choice auto and is append-only,
961
- and the pre-commit dispatch probe covers the entry as sent.)
962
- (verified 2026-09-23 — ADDED claude-opus-5-5, released 2026-09-22 and
963
- listed as "Active (latest)" on /docs/en/models/opus-5-5/overview; the
964
- overview page now lists claude-opus-5 under "Legacy models (still
965
- available)" → superseded, with opus-4-8/4-7/4-6 repointed one hop.
966
- Pricing page: $4/$20, 5m cache write $5, cache hits $0.20 (footnote 2:
967
- 0.05× input on Opus 5.5 only), fast mode $8/$40. 1M ctx / 128K out, text +
968
- image input, reliable knowledge cutoff Jun 2026. Effort page: all five
969
- levels, default MEDIUM. What's-new page: thinking always on
970
- (disabled/budget_tokens 400), tool_choice any/tool 400, computer_20251124
971
- 400 — Synthase sends none of those. Every other Anthropic price on the
972
- pricing page is unchanged.)
973
- (verified 2026-09-29 — ADDED claude-sonnet-5-5, released 2026-09-28 and
974
- listed as "Active (latest)" on /docs/en/models/sonnet-5-5/overview; the
975
- overview page now lists claude-sonnet-5 under "Legacy models (still
976
- available)" → superseded, with sonnet-4-6 repointed one hop. Pricing
977
- page: $2/$10, 5m cache write $2.50, cache hits $0.20 (standard 0.1×).
978
- 1M ctx / 128K out, text + image input, reliable knowledge cutoff Jun
979
- 2026. Effort page: all five levels, default high. Model/what's-new
980
- pages: non-default temperature 400, tool_choice any/tool 400,
981
- thinking "disabled" replaced by "between_tools" — Synthase sends none of
982
- those. Every other Anthropic price on the pricing page is unchanged.)
983
- (re-verified 2026-10-08 on /docs/en/about-claude/pricing: sonnet-5-5 cache
984
- hits are $0.10 — footnote 2 prices Opus 5.5 AND Sonnet 5.5 cache hits at
985
- 0.05× input — not the $0.20 recorded at its add; catalog corrected. Every
986
- other cataloged Anthropic price on that page is unchanged.)
987
- (verified 2026-10-08 — ADDED claude-haiku-5-5, released 2026-10-07 and
988
- listed "Active (latest)" on /docs/en/models/haiku-5-5/overview, which
989
- moves claude-haiku-4-5 to "Legacy models (still available)" → superseded.
990
- Model page + pricing page: $0.10/$0.50 per MTok for prompts up to 100K
991
- tokens — the first Anthropic model priced BY PROMPT LENGTH (over 100K:
992
- $0.50/$2.50, cache read $0.05, 5m write $0.625 — modeled by
993
- `longContextPricing`; the Gemini/Grok >200K and GPT-6 >272K bands are
994
- NOT) — 5m cache write $0.125, cache
995
- hits $0.01 (standard 0.1×), web search $10/1k. 1M ctx / 128K out, text +
996
- image input, reliable knowledge cutoff Jun 2026. Effort page: all five
997
- levels, default MEDIUM. Model page "Good to know": non-default
998
- temperature/top_p/top_k → 400 (rejectsTemperature). Unlike
999
- opus-5-5/sonnet-5.5, forced tool_choice any/tool still works — the
1000
- pricing page's tool-token table carries an any/tool count for it (406)
1001
- where those two have none — and thinking {type:"disabled"} is accepted at
1002
- high-or-below effort; Synthase sends neither disabled nor a temperature.
1003
- Adaptive thinking only, budget_tokens is the legacy path. Every other
1004
- Anthropic price on the pricing page is unchanged.)
1005
- - OpenAI: https://developers.openai.com/api/docs/pricing (GPT-5.6 family GA
1006
- 2026-07-09; REPRICED 2026-07-30: -luna cut 80% to $0.20/$1.20, -terra cut
1007
- 20% to $2/$12, -sol unchanged $5/$30; cache read 0.1× input; gpt-5.5/
1008
- gpt-5.4 still listed as current; long-context 2× variants exist upstream —
1009
- not modeled, same as the Gemini/Grok tiers; Sol "Fast mode" 2.5× speed at
1010
- 2× price announced 2026-07-30 — not yet modeled)
1011
- (re-verified 2026-08-25: -sol on a >20% PROMO at $4/$20 (cache read $0.40,
1012
- cache write $5) since 2026-08-22, footnoted on that page as "available at
1013
- least through November 21, 2026" — catalog holds LIST $5/$30 so metering
1014
- never under-charges when it lapses, per KNOWN_DIVERGENCES; -terra and
1015
- -luna unchanged and matching the page; cache-read 0.1× and cache-write
1016
- 1.25× are now published first-party for all three tiers)
1017
- (re-verified 2026-09-21 on the pricing page: every cataloged OpenAI entry
1018
- is unchanged, and the -sol promo footnote still reads "available at least
1019
- through November 21, 2026". gpt-6-astra (released 2026-09-04) is listed at
1020
- $10/$50, cached input $1, cache writes $12.50 — and, like the Gemini/Grok
1021
- tiers, a long-context band above 272K prompt tokens that reprices the WHOLE
1022
- request ($20/$75, cached $2, cache writes $25): 2× input/cache, 1.5×
1023
- output. The catalog's price fields are flat per-MTok rates with no
1024
- context-band dimension, so that band is NOT modeled, exactly as the
1025
- > 200K tiers above are not. Astra was withheld at the time: it could not serve a
1026
- > tool-carrying request on /v1/chat/completions.)
1027
- > (re-verified 2026-09-24 on the gpt-6-astra model page: ADDED gpt-6-astra
1028
- > ($10/$50, cached $1, cache writes $12.50; 1.05M ctx / 128K out; image
1029
- > input; knowledge cutoff Apr 30 2026; effort low|medium|high|xhigh|max),
1030
- > now that the bond calls /v1/responses.)
1031
- > (re-verified 2026-09-23: ADDED gpt-6-sol ($2/$10, cached $0.20, cache
1032
- writes $2.50) and gpt-6-luna ($0.10/$0.50, cached $0.01, cache writes
1033
- $0.125), released 2026-09-22 — both with the same unmodeled >272K band,
1034
- > 1.05M ctx / 128K out, image input, knowledge cutoff Apr 20 / May 18 2026
1035
- > per their model pages. Unlike astra they serve tool-carrying requests on
1036
- > /v1/chat/completions with reasoning_effort 'none'. The 5.6 family is now
1037
- > superseded; every 5.6 price on the page is unchanged and the -sol promo
1038
- > footnote still reads "at least through November 21, 2026".)
1039
- > (re-verified 2026-09-30 on the pricing page + the gpt-6.1-sol model page:
1040
- > ADDED gpt-6.1-sol ($2/$10, cached $0.10 — 5% of input, not 10% — cache
1041
- writes $2.50; >272K band $4/$15, cached $0.20, writes $5 not modeled;
1042
- > 1.05M ctx / 128K out; image input; knowledge cutoff Apr 30 2026; effort
1043
- > low|medium|high|xhigh|max, no none/minimal; tools on /v1/responses only).
1044
- > It supersedes gpt-6-sol. Every other GPT-6 and 5.6 price on the page is
1045
- > unchanged and the 5.6-sol promo footnote still reads "at least through
1046
- > November 21, 2026".)
1047
- - Google: https://ai.google.dev/gemini-api/docs/pricing (gemini-3.6-flash GA
1048
- 2026-07-21 $1.50/$7.50 supersedes 3.5-flash as the agentic flagship;
1049
- gemini-3.1-pro-preview still the pro tier — "3.5 Pro" has NOT shipped as
1050
- of 2026-07-28 despite the coming-soon badge; do not add until it has an id)
1051
- (re-verified 2026-08-13: gemini-3.7-flash "New Stable" — supersedes
1052
- 3.6-flash as the flash flagship at the SAME list price ($1.50/$7.50, cache
1053
- read $0.15), with a launch promo ($0.75/$3.75, cache read $0.075) through
1054
- 2026-12-31 billed here at list; specs from /docs/models/gemini-3.7-flash:
1055
- 1M ctx / 65,536 out, thinking low|medium|high (no minimal), vision, tools,
1056
- caching, search grounding, code execution, url context)
1057
- (re-verified 2026-08-21: the pricing page shows that SAME launch promo on
1058
- gemini-3.6-flash too, verbatim "$0.75 through December 31, 2026. $1.50
1059
- starting January 1, 2027." for input, "$3.75 … $7.50" for output and
1060
- "$0.075 … $0.15" for caching read — i.e. the promo is flash-tier-wide, not
1061
- 3.7-only as the 2026-08-13 note assumed. Both flash entries therefore stay
1062
- at the post-promo list rate ($1.50/$7.50, cache read $0.15) under the same
1063
- never-under-charge policy, each with a KNOWN_DIVERGENCES entry expiring
1064
- 2026-12-31. gemini-3.5-flash carries no promo: still $1.50/$9.00, $0.15)
1065
- (re-verified 2026-09-02: gemini-3.8-flash "New Stable" — supersedes
1066
- 3.7-flash, which the models page now calls "previous-generation". THIRD id
1067
- on the same flash-tier promo row, verbatim "$0.75 through December 31,
1068
- 2026. $1.50 starting January 1, 2027." / "$3.75 … $7.50" / "$0.075 …
1069
- $0.15", so it too is cataloged at list with a KNOWN_DIVERGENCES entry.
1070
- Specs from /docs/models/gemini-3.8-flash: 1M ctx / 65,536 out, thinking
1071
- low|medium|high, vision, tools, caching, search grounding, code execution,
1072
- url context — identical surface to 3.7-flash. Knowledge cutoff is published
1073
- by neither Google nor models.dev for this id)
1074
- (re-verified 2026-10-14: gemini-4-argon "New Stable" — ADDED, the first
1075
- Gemini 4 id and the flagship-reasoning tier. List $4/$20, implicit cache
1076
- read $0.20 (explicit caching unsupported, no write premium/storage fee),
1077
- launch promo $2/$10 + $0.10 through 2026-11-30 → KNOWN_DIVERGENCES.
1078
- Specs from /docs/models/gemini-4-argon: 1M unified ctx / 65,536 out
1079
- (up to 1M via long decode, not requested), thinking low|medium|high
1080
- default "On (medium)", text+image+video+audio+PDF input, function calling
1081
- - search grounding + code execution + URL context; knowledge cutoff
1082
- unpublished by Google — models.dev lead 2026-03. Does NOT supersede
1083
- 3.8-flash: different tier — flash is the $1.50/$7.50 fast/agentic line
1084
- Google still recommends, and no Gemini 4 flash id exists yet.)
1085
- - xAI: https://docs.x.ai/developers/models + /developers/grok-4-7 +
1086
- /developers/model-capabilities/text/reasoning (re-read 2026-09-30:
1087
- grok-4.7 flagship: $2/$6, cached $0.50, 500K ctx, ≥200K prompts bill 2× —
1088
- not modeled; reasoning_effort low|medium|high|xhigh default high, image
1089
- input, knowledge cutoff May 2026, "No text output limit"; live-probed on
1090
- /v1/chat/completions with tools, forced + required tool_choice,
1091
- temperature 0, xhigh and an image — all 200, effort 'none' 400s.
1092
- grok-4.6 (re-read 2026-09-30 from the models page's model list — its own
1093
- page now redirects to grok-4-7; specs from that page as archived
1094
- 2026-09-10): $2/$6, cached $0.50, 500K ctx, image input, reasoning_effort
1095
- low|medium|high|xhigh default high, knowledge cutoff February 1, 2026 —
1096
- cataloged superseded by grok-4.7.
1097
- grok-4.5 still served at $2/$6, cached $0.30; grok-4.3 still served at
1098
- $1.25/$2.50 with the bigger 1M window; grok-code-fast-1 no longer listed)
1099
- - Chinese public holidays (DeepSeek's peak excludes them):
1100
- https://www.12371.gov.cn/web/article/web/content_1451614684968525824.html
1101
- (the State Council's 2026 notice; see CHINA_PUBLIC_HOLIDAYS)
1102
- - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing +
1103
- /updates/ (verified 2026-09-23 — the announced 2026-09-14 routing of
1104
- `deepseek-v4-pro` to V4.1 Flash was WITHDRAWN: V4 Pro keeps its card
1105
- 0.66/1.98/0.022 off-peak, so its staged `scheduledPricing` was deleted.
1106
- The card now also says peak hours exclude Chinese public holidays, which
1107
- `peakPricing` cannot express — peak is billed on those weekdays too.
1108
- Earlier, 2026-09-10: legacy deepseek-chat/-reasoner ids fully
1109
- retired 2026-07-24 — never in this catalog. The 2026-09-10 re-read caught
1110
- the V4.1-Flash release DAY-OF: new evergreen id `deepseek-flash` at
1111
- off-peak miss $0.15 / hit $0.003 / out $0.6 (peak ×2, same Mon-Fri UTC
1112
- windows, 1M ctx / 384K out), the V4 flash + vision-exp ids RETIRED with
1113
- their names "temporarily routed" to V4.1 Flash at Flash prices (the
1114
- `deepseek-v4-flash` entry is repriced to that card), and `deepseek-v4-pro`
1115
- announced to route to V4.1 Flash at Flash prices from 2026-09-14 12:00
1116
- Beijing (staged as `scheduledPricing` there); the pro card itself is
1117
- unchanged (V4-Pro-0813, 0.66/1.98/0.022 off-peak). The card qualifies the
1118
- peak windows BY DAY — "01:00 - 04:00 and 06:00 - 10:00 UTC, Monday through
1119
- Friday (all other hours are off-peak)" — so the windows are
1120
- `daysOfWeekUtc`-restricted rather than daily. `deepseek-v4-flash-vision-exp`
1121
- is retired with the rest of V4 flash and stays deliberately uncatalogued.
1122
- The US re-host rates (DeepInfra) are unchanged from the 2026-09-06 read —
1123
- `DeepSeek-V4-Flash-0731` at $0.06/$0.18, cache read $0.015; DeepInfra also
1124
- listed `deepseek-ai/DeepSeek-V4.1-Flash` on 2026-09-10 at $0.30/$1.20
1125
- (cache read 0.02× input) — 2× native, not wired. See each entry's
1126
- `regionPricing`.)
1127
- - Moonshot: https://platform.kimi.ai/docs/models + DeepInfra's model API for
1128
- the US re-host (kimi-k3 flagship 2026-07-16
1129
- — 2.8T MoE, 1M ctx, $3/$15 — NOT added: thinking is forced-on with
1130
- reasoning_content that must be replayed through tool loops, the same
1131
- constraint that kept kimi-k2.7-code out. BOTH are now in the catalog: the
1132
- moonshot bond gained preserved thinking (reasoning replayed through tool
1133
- loops), so kimi-k3 is the Moonshot pick.)
1134
- (re-verified 2026-09-10 on platform.kimi.ai/docs/models: kimi-k2.5 was
1135
- officially discontinued 2026-08-31 — calls 404 — so its entry is now
1136
- `disabled: true`. kimi-k3 / kimi-k2.6 / kimi-k2.7-code all still Active.)
1137
- (re-verified 2026-10-11 on api.deepinfra.com/models/: the US re-host
1138
- DEPRECATED moonshotai/Kimi-K2.7-Code on 2026-09-29 with replaced_by
1139
- Kimi-K3 — a live probe sat 221 s with no content, then streamed chunks
1140
- labeled Kimi-K3 — so kimi-k2.7-code is native-only (regions ['cn']) and
1141
- its US modelMap entry is gone. kimi-k3's US re-host is healthy, rates
1142
- unchanged.)
1143
- - MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
1144
- minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
1145
- - Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking
1146
- (qwen3.8-max GA'd 2026-08-03 on the pay-as-you-go international API and is
1147
- IN the catalog — verified 2026-08-04: flat $2/$6 per MTok on
1148
- help.aliyun.com/en/model-studio/model-pricing (Singapore International
1149
- CNY 14.988/44.965 at the same fixed conversion that maps qwen3.7-max's
1150
- CNY 18.736/56.207 to its $2.50/$7.50 list), 1M ctx, hybrid thinking,
1151
- tools. Cache rates come from the ZH context-cache doc
1152
- (help.aliyun.com/zh/model-studio/context-cache), which lists qwen3.8-max
1153
- as supported in every region under the unconditional standard table
1154
- (implicit: hit 20% of input, creation 100%; explicit: hit 10%, creation
1155
- 125%) — the EN edition of that doc simply lags (zero qwen3.8 mentions),
1156
- which an earlier pass misread as "excepted/console-only". qwen3.7-max
1157
- still runs its 50%-off promo — billed here at list, $2.50/$7.50)
1158
- (re-verified 2026-08-15 against api.deepinfra.com/models/: qwen3.8-max's US
1159
- re-host rates are unchanged — $1.65/$4.951, cache read 0.1248× input =
1160
- $0.206. DeepInfra also began serving `Qwen/Qwen3.8-2.4T-A95B` on
1161
- 2026-08-12; by DeepInfra's own description it is the OPEN-WEIGHT variant of
1162
- Qwen3.8 Max (2.4T MoE, 95B active), 262,144 ctx / 131,072 out, $2/$6 with
1163
- cache read 0.1× input. NOT added: it is the same tier as qwen3.8-max, which
1164
- the catalog already offers, and it costs MORE on that very host ($2/$6 vs
1165
- $1.65/$4.951), so nothing would ever select it — and carrying both would
1166
- put two selectable Alibaba flagships in one family. Revisit only if Alibaba
1167
- publishes it as a distinct first-party DashScope model id.)
1168
- (re-verified 2026-08-28 on the per-model pages, which publish USD rates per
1169
- region directly — a better source than the CNY pricing table: qwen3.8-max's
1170
- Singapore implicit-cache rate is $0.25, NOT the 20%/$0.40 the ZH cache doc's
1171
- standard table implies. That doc names qwen3.8-max, qwen3.8-flash and
1172
- qwen3.8-2.4t-a95b as exceptions and defers to the console; the model pages
1173
- are the console's figures. qwen3.7-max's $0.50 (20%) is confirmed unchanged.
1174
- qwen3.8-flash (2026-08-26) ADDED: $0.15/$0.47, implicit cache $0.016, 1M ctx
1175
- / 131,072 out, Image+Text+Video input, tools, hybrid thinking ON by default
1176
- with thinking_budget. It is cn-region-only — api.deepinfra.com has no
1177
- Qwen/Qwen3.8-Flash — so ALIBABA_US_MODEL_MAP needs no entry.)
1178
- (re-verified 2026-10-10: DashScope RETIRED qwen3-coder-plus — the native
1179
- compatible-mode endpoint 404s "Model not exist." on every request shape
1180
- and the id is gone from its own /v1/models list, while the help-center
1181
- model page still describes it (docs lag the endpoint). The catalog entry
1182
- dropped its cn region and is now US/DeepInfra-only, whose rates re-verified
1183
- unchanged the same day: $0.30/$1, cache read 0.3333× input.)
1184
- - Zhipu: https://docs.z.ai/guides/overview/pricing + docs.z.ai/guides/llm/
1185
- glm-5.3 (verified 2026-08-26: glm-5.3 shipped 2026-08-14 and IS in the
1186
- catalog — $1.40/$4.40, cached $0.26, i.e. glm-5.2's card unchanged, 1M ctx,
1187
- 128K out, text-only, reasoning_effort low|high|max with reasoning no longer
1188
- disableable. It supersedes glm-5.2: same tier, same base weights, gains are
1189
- post-training only. NOT on DeepInfra — api.deepinfra.com/models/zai-org/
1190
- GLM-5.3 returns "model not found", so it is cn-region-only for now and the
1191
- ZHIPU_US_MODEL_MAP needs no entry.
1192
- glm-5.3-flash (2026-08-26, natively multimodal, 1M ctx, 128K out) added
1193
- 2026-08-27 at the LIST card ($0.15/$0.50, cached $0.03 — verified on the
1194
- Z.ai pricing page) so metering never under-charges during the 50%-off
1195
- launch promo ($0.075/$0.25) that runs to 2026-09-09 24:00 UTC+8; the promo
1196
- is a KNOWN_DIVERGENCES entry in check-model-freshness. US path is the
1197
- DeepInfra re-host zai-org/GLM-5.3-Flash, which bills exactly the list card
1198
- ($0.15/$0.50, cache read 0.2x = $0.03 — verified live 2026-08-27), mapped
1199
- in molecule-dev's ZHIPU_US_MODEL_MAP.)
1200
- (re-verified 2026-09-10 on https://docs.z.ai/guides/overview/pricing: the
1201
- promo ended on schedule 2026-09-09 24:00 UTC+8 and the page prints the list
1202
- card again — $0.15/$0.50, cached input $0.03, no promo footnote. models.dev
1203
- still carries the expired promo rate, so the KNOWN_DIVERGENCES entry now
1204
- runs to a fixed 2026-12-09 re-verify date.)
1205
- (verified 2026-09-23: glm-5.3-flashx ADDED — the ~200 tokens/s tier of the
1206
- GLM-5.3-Flash series. Pricing page: $0.37/$1.25, cached input $0.075,
1207
- cache storage free. Chat-completion reference: id `glm-5.3-flashx` in the
1208
- vision request enum, 128K max output, reasoning_effort low|high|max
1209
- (default max), function tools supported. GLM-5.3-Flash guide: 1M ctx,
1210
- video/image/text/file input. No published knowledge cutoff. Not on
1211
- DeepInfra (zai-org/GLM-5.3-FlashX 404s), so cn-region-only. glm-5.3 and
1212
- glm-5.3-flash rates unchanged on the same page.)
1213
- (re-verified 2026-10-13: glm-5.3-flash flipped to cn-default — DeepInfra's
1214
- zai-org/GLM-5.3-Flash deployment is intermittently overloaded (429
1215
- engine_overloaded "Model busy, retry later" across the 2026-10-10 →
1216
- 2026-10-13 cron sweeps, while two other DeepInfra models 200 on the same
1217
- key at the same moment). Z.ai pricing page unchanged: $0.15/$0.50, cached
1218
- $0.03. DeepInfra's card re-verified live and identical (input $0.15,
1219
- output $0.50, cache read 0.2× input); deployment not deprecated.
1220
- 'us' stays selectable at that same card, like deepseek-flash's cn-first
1221
- default. glm-5.3 / glm-5.3-flashx unchanged, cn-only.)
1222
-
1223
- Knowledge-cutoff dates on non-Anthropic entries are best-effort estimates
1224
- where the provider doesn't publish one; the provider sources above verify
1225
- id / pricing / context window.
637
+
638
+ _(description truncated — read the full text in `node_modules/@molecule/api-resource-ai-models/dist/models.d.ts`.)_
1226
639
 
1227
640
  ```typescript
1228
641
  const MODELS: readonly ModelDefinition[]
@@ -1 +1 @@
1
- {"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAwDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4VG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EA44EnC,CAAA"}
1
+ {"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAwDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4VG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EAi5EnC,CAAA"}
package/dist/models.js CHANGED
@@ -2112,6 +2112,11 @@ export const MODELS = [
2112
2112
  // read 3% of input = $0.006 — roughly 2× this native off-peak card on
2113
2113
  // cache reads, so native stays the default and `us` is the fallback a
2114
2114
  // project picks when native is unavailable.
2115
+ // Re-verified 2026-10-19 against the mapped id: UNCHANGED. DeepInfra now
2116
+ // also serves the dated `DeepSeek-V4.1-Flash-1017` snapshot (the host does
2117
+ // not upgrade weights in place) at IDENTICAL rates — 0.00002/0.00006
2118
+ // cents, cache 3% — so bumping the us modelMap to it moves no price here;
2119
+ // a weights decision, not a pricing one (same as V4-Pro's `-0813`).
2115
2120
  regions: ['cn', 'us'],
2116
2121
  regionPricing: {
2117
2122
  us: { inputPricePerMTok: 0.2, outputPricePerMTok: 0.6, cacheReadPricePerMTok: 0.006 },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-ai-models",
3
- "version": "1.16.0",
3
+ "version": "1.16.1",
4
4
  "description": "AI model catalog — server-side source of truth plus an authentication-gated discovery endpoint",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -29,7 +29,7 @@
29
29
  "devDependencies": {
30
30
  "@molecule/api-bond": "1.0.2",
31
31
  "@molecule/api-i18n": "1.0.3",
32
- "@molecule/api-resource": "1.0.2",
32
+ "@molecule/api-resource": "1.0.5",
33
33
  "@types/node": "26.1.2",
34
34
  "typescript": "6.0.3",
35
35
  "vitest": "4.1.11"